Help content

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

Categorical Index Of SQLite Documents

Overview Documents
About SQLite | A high-level overview of what SQLite is and why you might be interested in using it.
Appropriate Uses For SQLite | This document describes situations where SQLite is an appropriate database engine to use versus situations where a client/server database engine might be a better choice.
Distinctive Features | This document enumerates and describes some of the features of SQLite that make it different from other SQL database engines.
How SQLite Is Tested | The reliability and robustness of SQLite is achieved in large part by thorough and careful testing. This document identifies the many tests that occur before every release of SQLite.
Copyright | SQLite is in the public domain. This document describes what that means and the implications for contributors.
Frequently Asked Questions | The title of the document says all...
Books About SQLite | A list of independently written books about SQLite.
Alphabetical Listing Of Documents | A list of all titled pages on this website, sorted by title.
Website Keyword Index | A cross-reference from keywords to various pages within this website.
Permuted Title Index | Also known as a "keyword in context" or "KWIC" index or as a concordance, this document is a listing of all other documents sorted by keyword.
SQLite Programming Interfaces Documentation describing the APIs used to program SQLite, and the SQL dialect that it interprets.
SQLite In 5 Minutes Or Less | A very quick introduction to programming with SQLite.
Introduction to the C/C++ API | This document introduces the C/C++ API. Users should read this document before the C/C++ API Reference Guide linked below.
C/C++ API Reference | This document describes each API function separately.
Tcl API | A description of the TCL interface bindings for SQLite.
SQL Syntax | This document describes the SQL language that is understood by SQLite.
Pragma commands | This document describes SQLite performance tuning options and other special purpose database commands.
Version 3 DataTypes | SQLite version 3 introduces the concept of manifest typing, where the type of a value is associated with the value itself, not the column that it is stored in. This page describes data typing for SQLite version 3 in further detail.
Null Handling | Different SQL database engines handle NULLs in different ways. The SQL standards are ambiguous. This document describes how SQLite handles NULLs in comparison with other SQL database engines.
Unsupported SQL | This page describes features of SQL that SQLite does not support.
SQLite Features and Extensions Pages describing specific features or extension modules of SQLite.
Asynchronous IO Mode | This page describes the asynchronous IO extension developed alongside SQLite. Using asynchronous IO can cause SQLite to appear more responsive by delegating database writes to a background thread.
Foreign Key Support | This document describes the support for foreign key constraints introduced in version 3.6.19.
Shared Cache Mode | Version 3.3.0 and later supports the ability for two or more database connections to share the same page and schema cache. This feature is useful for certain specialized applications.
Unlock Notify | The "unlock notify" feature can be used in conjunction with shared cache mode to more efficiently manage resource conflict (database table locks).
Using The Online Backup Interface | The online-backup interface can be used to copy content from a disk file into an in-memory database or vice versa and it can make a hot backup of a live database. This application note gives examples of how.
R-Trees | A description of the SQLite R-Tree extension. An R-Tree is a specialized data structure that supports fast multi-dimensional range queries often used in geospatial systems.
Full Text Search | A description of the SQLite Full Text Search (FTS3) extension.
Upgrading SQLite, Backwards Compatibility
Moving From SQLite 3.5 to 3.6 | A document describing the differences between SQLite version 3.5.9 and 3.6.0.
Moving From SQLite 3.4 to 3.5 | A document describing the differences between SQLite version 3.4.2 and 3.5.0.
Release History | A chronology of SQLite releases going back to version 1.0.0
Backwards Compatibility | This document details all of the incompatible changes to the SQLite file format that have occurred since version 1.0.0.
Private Branches | This document suggests procedures for maintaining a private branch or fork of SQLite and keeping that branch or fork in sync with the public SQLite source tree.
SQLite Technical/Design Documentation
Temporary Files Used By SQLite | SQLite can potentially use many different temporary files when processing certain SQL statements. This document describes the many kinds of temporary files that SQLite uses and offers suggestions for avoiding them on systems where creating a temporary file is an expensive operation.
In-Memory Databases | SQLite normally stores content in a disk file. However, it can also be used as an in-memory database engine. This document explains how.
How SQLite Implements Atomic Commit | A description of the logic within SQLite that implements transactions with atomic commit, even in the face of power failures.
Dynamic Memory Allocation in SQLite | SQLite has a sophisticated memory allocation subsystem that can be configured and customized to meet memory usage requirements of the application and that is robust against out-of-memory conditions and leak-free. This document provides the details.
Customizing And Porting SQLite | This document explains how to customize the build of SQLite and how to port SQLite to new platforms.
Locking And Concurrency In SQLite Version 3 | A description of how the new locking code in version 3 increases concurrency and decreases the problem of writer starvation.
Overview Of The Optimizer | A quick overview of the various query optimizations that are attempted by the SQLite code generator.
Architecture | An architectural overview of the SQLite library, useful for those who want to hack the code.
VDBE Opcodes | This document is an automatically generated description of the various opcodes that the VDBE understands. Programmers can use this document as a reference to better understand the output of EXPLAIN listings from SQLite.
SQLite File Format | A description of the format used for SQLite database and journal files, and other details required to create software to read and write SQLite databases without using SQLite.
Compilation Options | This document describes the compile time options that may be set to modify the default behavior of the library or omit optional features in order to reduce binary size.
Limits In SQLite | This document describes limitations of SQLite (the maximum length of a string or blob, the maximum size of a database, the maximum number of tables in a database, etc.) and how these limits can be altered at compile-time and run-time.
Old Documents These documents either pertain to SQLite version 2 or were written during the transition period between versions 2 and 3. They are no longer strictly applicable to recent versions of SQLite, but the information found within may still be useful.
Version 2 C/C++ API | A description of the C/C++ interface bindings for SQLite through version 2.8
Version 2 DataTypes | A description of how SQLite version 2 handles SQL datatypes. Short summary: Everything is a string.
VDBE Tutorial | The VDBE is the subsystem within SQLite that does the actual work of executing SQL statements. This page describes the principles of operation for the VDBE in SQLite version 2.7. This is essential reading for anyone who want to modify the SQLite sources.
SQLite Version 3 | A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
Version 3 C/C++ API | A summary of of the API related changes between SQLite version 2.8 and SQLite version 3.0.
Speed Comparison | The speed of version 2.7.6 of SQLite is compared against PostgreSQL and MySQL.


SQLite Changes From Version 3.4.2 To 3.5.0

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

Moving From SQLite 3.4.2 to 3.5.0

SQLite version 3.5.0 introduces a new OS interface layer that is incompatible with all prior versions of SQLite. In addition, a few existing interfaces have been generalized to work across all database connections within a process rather than just all connections within a thread. The purpose of this article is to describe the changes to 3.5.0 in detail so that users of prior versions of SQLite can judge what, if any, effort will be required to upgrade to newer versions.

1.0 Overview Of Changes

A quick enumeration of the changes in SQLite version 3.5.0 is provide here. Subsequent sections will describe these changes in more detail.

  1. The OS interface layer has been completely reworked:
    1. The undocumented sqlite3_os_switch() interface has been removed.
    2. The SQLITE_ENABLE_REDEF_IO compile-time flag no longer functions. I/O procedures are now always redefinable.
    3. Three new objects are defined for specifying I/O procedures: sqlite3_vfs, sqlite3_file, and sqlite3_io_methods.
    4. Three new interfaces are used to create alternative OS interfaces: sqlite3_vfs_register(), sqlite3_vfs_unregister(), and sqlite3_vfs_find().
    5. A new interface has been added to provided additional control over the creation of new database connections: sqlite3_open_v2(). The legacy interfaces of sqlite3_open() and sqlite3_open16() continue to be fully supported.
  2. The optional shared cache and memory management features that were introduced in version 3.3.0 can now be used across multiple threads within the same process. Formerly, these extensions only applied to database connections operating within a single thread.
    1. The sqlite3_enable_shared_cache() interface now applies to all threads within a process, not to just the one thread in which it was run.
    2. The sqlite3_soft_heap_limit() interface now applies to all threads within a process, not to just the one thread in which it was run.
    3. The sqlite3_release_memory() interface will now attempt to reduce the memory usages across all database connections in all threads, not just connections in the thread where the interface is called.
    4. The sqlite3_thread_cleanup() interface has become a no-op.
  3. Restrictions on the use of the same database connection by multiple threads have been dropped. It is now safe for multiple threads to use the same database connection at the same time.
  4. There is now a compile-time option that allows an application to define alternative malloc()/free() implementations without having to modify any core SQLite code.
  5. There is now a compile-time option that allows an application to define alternative mutex implementations without having to modify any core SQLite code.

Of these changes, only 1a and 2a through 2c are incompatibilities in any formal sense. But users who have previously made custom modifications to the SQLite source (for example to add a custom OS layer for embedded hardware) might find that these changes have a larger impact. On the other hand, an important goal of these changes is to make it much easier to customize SQLite for use on different operating systems.

2.0 The OS Interface Layer

If your system defines a custom OS interface for SQLite or if you were using the undocumented sqlite3_os_switch() interface, then you will need to make modifications in order to upgrade to SQLite version 3.5.0. This may seem painful at first glance. But as you look more closely, you will probably discover that your changes are made smaller and easier to understand and manage by the new SQLite interface. It is likely that your changes will now also work seamlessly with the SQLite amalgamation. You will no longer need to make any changes to the code SQLite source code. All of your changes can be effected by application code and you can link against a standard, unmodified version of the SQLite amalgamation. Furthermore, the OS interface layer, which was formerly undocumented, is now an officially support interface for SQLite. So you have some assurance that this will be a one-time change and that your new backend will continue to work in future versions of SQLite.

2.1 The Virtual File System Object

The new OS interface for SQLite is built around an object named sqlite3_vfs. The "vfs" stands for "Virtual File System". The sqlite3_vfs object is basically a structure containing pointers to functions that implement the primitive disk I/O operations that SQLite needs to perform in order to read and write databases. In this article, we will often refer a sqlite3_vfs objects as a "VFS".

SQLite is able to use multiple VFSes at the same time. Each individual database connection is associated with just one VFS. But if you have multiple database connections, each connection can be associated with a different VFS.

There is always a default VFS. The legacy interfaces sqlite3_open() and sqlite3_open16() always use the default VFS. The new interface for creating database connections, sqlite3_open_v2(), allows you to specify which VFS you want to use by name.

2.1.1 Registering New VFS Objects

Standard builds of SQLite for Unix or Windows come with a single VFS named "unix" or "win32", as appropriate. This one VFS is also the default. So if you are using the legacy open functions, everything will continue to operate as it has before. The change is that an application now has the flexibility of adding new VFS modules to implement a customized OS layer. The sqlite3_vfs_register() API can be used to tell SQLite about one or more application-defined VFS modules:

int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);

Applications can call sqlite3_vfs_register at any time, though of course a VFS needs to be registered before it can be used. The first argument is a pointer to a customized VFS object that the application has prepared. The second argument is true to make the new VFS the default VFS so that it will be used by the legacy sqlite3_open() and sqlite3_open16() APIs. If the new VFS is not the default, then you will probably have to use the new sqlite3_open_v2() API to use it. Note, however, that if a new VFS is the only VFS known to SQLite (if SQLite was compiled without its usual default VFS or if the precompiled default VFS was removed using sqlite3_vfs_unregister()) then the new VFS automatic becomes the default VFS regardless of the makeDflt argument to sqlite3_vfs_register().

Standard builds include the default "unix" or "win32" VFSes. But if you use the -DOS_OTHER=1 compile-time option, then SQLite is built without a default VFS. In that case, the application must register at least one VFS prior to calling sqlite3_open(). This is the approach that embedded applications should use. Rather than modifying the SQLite source to insert an alternative OS layer as was done in prior releases of SQLite, instead compile an unmodified SQLite source file (preferably the amalgamation) with the -DOS_OTHER=1 option, then invoke sqlite3_vfs_register() to define the interface to the underlying filesystem prior to creating any database connections.

2.1.2 Additional Control Over VFS Objects

The sqlite3_vfs_unregister() API is used to remove an existing VFS from the system.

int sqlite3_vfs_unregister(sqlite3_vfs*);

The sqlite3_vfs_find() API is used to locate a particular VFS by name. Its prototype is as follows:

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);

The argument is the symbolic name for the desired VFS. If the argument is a NULL pointer, then the default VFS is returned. The function returns a pointer to the sqlite3_vfs object that implements the VFS. Or it returns a NULL pointer if no object could be found that matched the search criteria.

2.1.3 Modifications Of Existing VFSes

Once a VFS has been registered, it should never be modified. If a change in behavior is required, a new VFS should be registered. The application could, perhaps, use sqlite3_vfs_find() to locate the old VFS, make a copy of the old VFS into a new sqlite3_vfs object, make the desired modifications to the new VFS, unregister the old VFS, the register the new VFS in its place. Existing database connections would continue to use the old VFS even after it is unregistered, but new database connections would use the new VFS.

2.1.4 The VFS Object

A VFS object is an instance of the following structure:

typedef struct sqlite3_vfs sqlite3_vfs;
struct sqlite3_vfs {
  int iVersion;            /* Structure version number */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
  int (*xGetTempName)(sqlite3_vfs*, char *zOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};

To create a new VFS, an application fills in an instance of this structure with appropriate values and then calls sqlite3_vfs_register().

The iVersion field of sqlite3_vfs should be 1 for SQLite version 3.5.0. This number may increase in future versions of SQLite if we have to modify the VFS object in some way. We hope that this never happens, but the provision is made in case it does.

The szOsFile field is the size in bytes of the structure that defines an open file: the sqlite3_file object. This object will be described more fully below. The point here is that each VFS implementation can define its own sqlite3_file object containing whatever information the VFS implementation needs to store about an open file. SQLite needs to know how big this object is, however, in order to preallocate enough space to hold it.

The mxPathname field is the maximum length of a file pathname that this VFS can use. SQLite sometimes has to preallocate buffers of this size, so it should be as small as reasonably possible. Some filesystems permit huge pathnames, but in practice pathnames rarely extend beyond 100 bytes or so. You do not have to put the longest pathname that the underlying filesystem can handle here. You only have to put the longest pathname that you want SQLite to be able to handle. A few hundred is a good value in most cases.

The pNext field is used internally by SQLite. Specifically, SQLite uses this field to form a linked list of registered VFSes.

The zName field is the symbolic name of the VFS. This is the name that the sqlite3_vfs_find() compares against when it is looking for a VFS.

The pAppData pointer is unused by the SQLite core. The pointer is available to store auxiliary information that a VFS information might want to carry around.

The remaining fields of the sqlite3_vfs object all store pointer to functions that implement primitive operations. We call these "methods". The first methods, xOpen, is used to open files on the underlying storage media. The result is an sqlite3_file object. There are additional methods, defined by the sqlite3_file object itself that are used to read and write and close the file. The additional methods are detailed below. The filename is in UTF-8. SQLite will guarantee that the zFilename string passed to xOpen() is a full pathname as generated by xFullPathname() and that the string will be valid and unchanged until xClose() is called. So the sqlite3_file can store a pointer to the filename if it needs to remember the filename for some reason. The flags argument to xOpen() is a copy of the flags argument to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16() is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. If xOpen() opens a file read-only then it sets *pOutFlags to include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be set. SQLite will also add one of the following flags to the xOpen() call, depending on the object being opened:

  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
The file I/O implementation can use the object type flags to changes the way it deals with files. For example, an application that does not care about crash recovery or rollback, might make the open of a journal file a no-op. Writes to this journal are also a no-op. Any attempt to read the journal returns SQLITE_IOERR. Or the implementation might recognize the a database file will be doing page-aligned sector reads and writes in a random order and set up its I/O subsystem accordingly. SQLite might also add one of the following flags to the xOpen method:
  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE
The SQLITE_OPEN_DELETEONCLOSE flag means the file should be deleted when it is closed. This will always be set for TEMP databases and journals and for subjournals. The SQLITE_OPEN_EXCLUSIVE flag means the file should be opened for exclusive access. This flag is set for all files except for the main database file. The sqlite3_file structure passed as the third argument to xOpen is allocated by the caller. xOpen just fills it in. The caller allocates a minimum of szOsFile bytes for the sqlite3_file structure.

The differences between an SQLITE_OPEN_TEMP_DB database and an SQLITE_OPEN_TRANSIENT_DB database is this: The SQLITE_OPEN_TEMP_DB is used for explicitly declared and named TEMP tables (using the CREATE TEMP TABLE syntax) or for named tables in a temporary database that is created by opening a database with a filename that is an empty string. An SQLITE_OPEN_TRANSIENT_DB holds a database table that SQLite creates automatically in order to evaluate a subquery or ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases are private and are deleted automatically. TEMP_DB databases last for the duration of the database connection. TRANSIENT_DB databases last only for the duration of a single SQL statement.

The xDelete method is used delete a file. The name of the file is given in the second parameter. The filename will be in UTF-8. The VFS must convert the filename into whatever character representation the underlying operating system expects. If the syncDir parameter is true, then the xDelete method should not return until the change to the directory contents for the directory containing the deleted file have been synced to disk in order to ensure that the file does not "reappear" if a power failure occurs soon after.

The xAccess method is used to check for access permissions on a file. The filename will be UTF-8 encoded. The flags argument will be SQLITE_ACCESS_EXISTS to check for the existence of the file, SQLITE_ACCESS_READWRITE to check to see if the file is both readable and writable, or SQLITE_ACCESS_READ to check to see if the file is at least readable. The "file" named by the second parameter might be a directory or folder name.

The xGetTempName method computes the name of a temporary file that SQLite can use. The name should be written into the buffer given by the second parameter. SQLite will size that buffer to hold at least mxPathname bytes. The generated filename should be in UTF-8. To avoid security problems, the generated temporary filename should contain enough randomness to prevent an attacker from guessing the temporary filename in advance.

The xFullPathname method is used to convert a relative pathname into a full pathname. The resulting full pathname is written into the buffer provided by the third parameter. SQLite will size the output buffer to at least mxPathname bytes. Both the input and output names should be in UTF-8.

The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for accessing shared libraries at run-time. These methods may be omitted (and their pointers set to zero) if the library is compiled with SQLITE_OMIT_LOAD_EXTENSION or if the sqlite3_enable_load_extension() interface is never used to enable dynamic extension loading. The xDlOpen method opens a shared library or DLL and returns a pointer to a handle. NULL is returned if the open fails. If the open fails, the xDlError method can be used to obtain a text error message. The message is written into the zErrMsg buffer of the third parameter which is at least nByte bytes in length. The xDlSym returns a pointer to a symbol in the shared library. The name of the symbol is given by the second parameter. UTF-8 encoding is assumed. If the symbol is not found a NULL pointer is returned. The xDlClose routine closes the shared library.

The xRandomness method is used exactly once to initialize the pseudo-random number generator (PRNG) inside of SQLite. Only the xRandomness method on the default VFS is used. The xRandomness methods on other VFSes are never accessed by SQLite. The xRandomness routine requests that nByte bytes of randomness be written into zOut. The routine returns the actual number of bytes of randomness obtained. The quality of the randomness so obtained will determine the quality of the randomness generated by built-in SQLite functions such as random() and randomblob(). SQLite also uses its PRNG to generate temporary file names.. On some platforms (ex: Windows) SQLite assumes that temporary file names are unique without actually testing for collisions, so it is important to have good-quality randomness even if the random() and randomblob() functions are never used.

The xSleep method is used to suspend the calling thread for at least the number of microseconds given. This method is used to implement the sqlite3_sleep() and sqlite3_busy_timeout() APIs. In the case of sqlite3_sleep() the xSleep method of the default VFS is always used. If the underlying system does not have a microsecond resolution sleep capability, then the sleep time should be rounded up. xSleep returns this rounded-up value.

The xCurrentTime method finds the current time and date and writes the result as double-precision floating point value into pointer provided by the second parameter. The time and date is in coordinated universal time (UTC) and is a fractional Julian day number.

2.1.5 The Open File Object

The result of opening a file is an instance of an sqlite3_file object. The sqlite3_file object is an abstract base class defined as follows:

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;
};

Each VFS implementation will subclass the sqlite3_file by adding additional fields at the end to hold whatever information the VFS needs to know about an open file. It does not matter what information is stored as long as the total size of the structure does not exceed the szOsFile value recorded in the sqlite3_vfs object.

The sqlite3_io_methods object is a structure that contains pointers to methods for reading, writing, and otherwise dealing with files. This object is defined as follows:

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};

The iVersion field of sqlite3_io_methods is provided as insurance against future enhancements. The iVersion value should always be 1 for SQLite version 3.5.

The xClose method closes the file. The space for the sqlite3_file structure is deallocated by the caller. But if the sqlite3_file contains pointers to other allocated memory or resources, those allocations should be released by the xClose method.

The xRead method reads iAmt bytes from the file beginning at a byte offset to iOfst. The data read is stored in the pointer of the second parameter. xRead returns the SQLITE_OK on success, SQLITE_IOERR_SHORT_READ if it was not able to read the full number of bytes because it reached end-of-file, or SQLITE_IOERR_READ for any other error.

The xWrite method writes iAmt bytes of data from the second parameter into the file beginning at an offset of iOfst bytes. If the size of the file is less than iOfst bytes prior to the write, then xWrite should ensure that the file is extended with zeros up to iOfst bytes prior to beginning its write. xWrite continues to extends the file as necessary so that the size of the file is at least iAmt+iOfst bytes at the conclusion of the xWrite call. The xWrite method returns SQLITE_OK on success. If the write cannot complete because the underlying storage medium is full, then SQLITE_FULL is returned. SQLITE_IOERR_WRITE should be returned for any other error.

The xTruncate method truncates a file to be nByte bytes in length. If the file is already nByte bytes or less in length then this method is a no-op. The xTruncate method returns SQLITE_OK on success and SQLITE_IOERR_TRUNCATE if anything goes wrong.

The xSync method is used to force previously written data out of operating system cache and into non-volatile memory. The second parameter is usually SQLITE_SYNC_NORMAL. If the second parameter is SQLITE_SYNC_FULL then the xSync method should make sure that data has also been flushed through the disk controllers cache. The SQLITE_SYNC_FULL parameter is the equivalent of the F_FULLSYNC ioctl() on Mac OS X. The xSync method returns SQLITE_OK on success and SQLITE_IOERR_FSYNC if anything goes wrong.

The xFileSize() method determines the current size of the file in bytes and writes that value into *pSize. It returns SQLITE_OK on success and SQLITE_IOERR_FSTAT if something goes wrong.

The xLock and xUnlock methods are used to set and clear file locks. SQLite supports five levels of file locks, in order:

  • SQLITE_LOCK_NONE
  • SQLITE_LOCK_SHARED
  • SQLITE_LOCK_RESERVED
  • SQLITE_LOCK_PENDING
  • SQLITE_LOCK_EXCLUSIVE
The underlying implementation can support some subset of these locking levels as long as it meets the other requirements of this paragraph. The locking level is specified as the second argument to both xLock and xUnlock. The xLock method increases the locking level to the specified locking level or higher. The xUnlock method decreases the locking level to no lower than the level specified. SQLITE_LOCK_NONE means that the file is unlocked. SQLITE_LOCK_SHARED gives permission to read the file. Multiple database connections can hold SQLITE_LOCK_SHARED at the same time. SQLITE_LOCK_RESERVED is like SQLITE_LOCK_SHARED in that its is permission to read the file. But only a single connection can hold a reserved lock at any point in time. The SQLITE_LOCK_PENDING is also permission to read the file. Other connections can continue to read the file as well, but no other connection is allowed to escalate a lock from none to shared. SQLITE_LOCK_EXCLUSIVE is permission to write on the file. Only a single connection can hold an exclusive lock and no other connection can hold any lock (other than "none") while one connection is hold an exclusive lock. The xLock returns SQLITE_OK on success, SQLITE_BUSY if it is unable to obtain the lock, or SQLITE_IOERR_RDLOCK if something else goes wrong. The xUnlock method returns SQLITE_OK on success and SQLITE_IOERR_UNLOCK for problems.

The xCheckReservedLock method checks to see if another connection or another process is currently holding a reserved, pending, or exclusive lock on the file. It returns true or false.

The xFileControl() method is a generic interface that allows custom VFS implementations to directly control an open file using the (new and experimental) sqlite3_file_control() interface. The second "op" argument is an integer opcode. The third argument is a generic pointer which is intended to be a pointer to a structure that may contain arguments or space in which to write return values. Potential uses for xFileControl() might be functions to enable blocking locks with timeouts, to change the locking strategy (for example to use dot-file locks), to inquire about the status of a lock, or to break stale locks. The SQLite core reserves opcodes less than 100 for its own use. A list of opcodes less than 100 is available. Applications that define a custom xFileControl method should use opcodes greater than 100 to avoid conflicts.

The xSectorSize returns the "sector size" of the underlying non-volatile media. A "sector" is defined as the smallest unit of storage that can be written without disturbing adjacent storage. On a disk drive the "sector size" has until recently been 512 bytes, though there is a push to increase this value to 4KiB. SQLite needs to know the sector size so that it can write a full sector at a time, and thus avoid corrupting adjacent storage space if a power lose occurs in the middle of a write.

The xDeviceCharacteristics method returns an integer bit vector that defines any special properties that the underlying storage medium might have that SQLite can use to increase performance. The allowed return is the bit-wise OR of the following values:

  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL
The SQLITE_IOCAP_ATOMIC bit means that all writes to this device are atomic in the sense that either the entire write occurs or none of it occurs. The other SQLITE_IOCAP_ATOMICnnn values indicate that writes of aligned blocks of the indicated size are atomic. SQLITE_IOCAP_SAFE_APPEND means that when extending a file with new data, the new data is written first and then the file size is updated. So if a power failure occurs, there is no chance that the file might have been extended with randomness. The SQLITE_IOCAP_SEQUENTIAL bit means that all writes occur in the order that they are issued and are not reordered by the underlying file system.

2.1.6 Checklist For Constructing A New VFS

The preceding paragraphs contain a lot of information. To ease the task of constructing a new VFS for SQLite we offer the following implementation checklist:

  1. Define an appropriate subclass of the sqlite3_file object.
  2. Implement the methods required by the sqlite3_io_methods object.
  3. Create a static and constant sqlite3_io_methods object containing pointers to the methods from the previous step.
  4. Implement the xOpen method that opens a file and populates an sqlite3_file object, including setting pMethods to point to the sqlite3_io_methods object from the previous step.
  5. Implement the other methods required by sqlite3_vfs.
  6. Define a static (but not constant) sqlite3_vfs structure that contains pointers to the xOpen method and the other methods and which contains the appropriate values for iVersion, szOsFile, mxPathname, zName, and pAppData.
  7. Implement a procedure that calls sqlite3_vfs_register() and passes it a pointer to the sqlite3_vfs structure from the previous step. This procedure is probably the only exported symbol in the source file that implements your VFS.

Within your application, call the procedure implemented in the last step above as part of your initialization process before any database connections are opened.

3.0 The Memory Allocation Subsystem

Beginning with version 3.5, SQLite obtains all of the heap memory it needs using the routines sqlite3_malloc(), sqlite3_free(), and sqlite3_realloc(). These routines have existed in prior versions of SQLite, but SQLite has previously bypassed these routines and used its own memory allocator. This all changes in version 3.5.0.

The SQLite source tree actually contains multiple versions of the memory allocator. The default high-speed version found in the "mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG flag is enabled, a separate memory allocator the "mem2.c" source file is used instead. The mem2.c allocator implements lots of hooks to do error checking and to simulate memory allocation failures for testing purposes. Both of these allocators use the malloc()/free() implementation in the standard C library.

Applications are not required to use either of these standard memory allocators. If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION then no implementation for the sqlite3_malloc(), sqlite3_realloc(), and sqlite3_free() functions is provided. Instead, the application that links against SQLite must provide its own implementation of these functions. The application provided memory allocator is not required to use the malloc()/free() implementation in the standard C library. An embedded application might provide an alternative memory allocator that uses memory for a fixed memory pool set aside for the exclusive use of SQLite, for example.

Applications that implement their own memory allocator must provide implementation for the usual three allocation functions sqlite3_malloc(), sqlite3_realloc(), and sqlite3_free(). And they must also implement a fourth function:

int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
  void *pArg,
  sqlite3_int64 iThreshold
);

The sqlite3_memory_alarm routine is used to register a callback on memory allocation events. This routine registers or clears a callbacks that fires when the amount of memory allocated exceeds iThreshold. Only a single callback can be registered at a time. Each call to sqlite3_memory_alarm() overwrites the previous callback. The callback is disabled by setting xCallback to a NULL pointer.

The parameters to the callback are the pArg value, the amount of memory currently in use, and the size of the allocation that provoked the callback. The callback will presumably invoke sqlite3_free() to free up memory space. The callback may invoke sqlite3_malloc() or sqlite3_realloc() but if it does, no additional callbacks will be invoked by the recursive calls.

The sqlite3_soft_heap_limit() interface works by registering a memory alarm at the soft heap limit and invoking sqlite3_release_memory() in the alarm callback. Application programs should not attempt to use the sqlite3_memory_alarm() interface because doing so will interfere with the sqlite3_soft_heap_limit() module. This interface is exposed only so that applications can provide their own alternative implementation when the SQLite core is compiled with SQLITE_OMIT_MEMORY_ALLOCATION.

The built-in memory allocators in SQLite also provide the following additional interfaces:

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

These interfaces can be used by an application to monitor how much memory SQLite is using. The sqlite3_memory_used() routine returns the number of bytes of memory currently in use and the sqlite3_memory_highwater() returns the maximum instantaneous memory usage. Neither routine includes the overhead associated with the memory allocator. These routines are provided for use by the application. SQLite never invokes them itself. So if the application is providing its own memory allocation subsystem, it can omit these interfaces if desired.

4.0 The Mutex Subsystem

SQLite has always been threadsafe in the sense that it is safe to use different SQLite database connections in different threads at the same time. The constraint was that the same database connection could not be used in two separate threads at once. SQLite version 3.5.0 relaxes this constraint.

In order to allow multiple threads to use the same database connection at the same time, SQLite must make extensive use of mutexes. And for this reason a new mutex subsystem as been added. The mutex subsystem as the following interface:

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);

Though these routines exist for the use of the SQLite core, application code is free to use these routines as well, if desired. A mutex is an sqlite3_mutex object. The sqlite3_mutex_alloc() routine allocates a new mutex object and returns a pointer to it. The argument to sqlite3_mutex_alloc() should be SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE for non-recursive and recursive mutexes, respectively. If the underlying system does not provide non-recursive mutexes, then a recursive mutex can be substituted in that case. The argument to sqlite3_mutex_alloc() can also be a constant designating one of several static mutexes:

  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_MUTEX_STATIC_LRU
These static mutexes are reserved for use internally by SQLite and should not be used by the application. The static mutexes are all non-recursive.

The sqlite3_mutex_free() routine should be used to deallocate a non-static mutex. If a static mutex is passed to this routine then the behavior is undefined.

The sqlite3_mutex_enter() attempts to enter the mutex and blocks if another threads is already there. sqlite3_mutex_try() attempts to enter and returns SQLITE_OK on success or SQLITE_BUSY if another thread is already there. sqlite3_mutex_leave() exits a mutex. The mutex is held until the number of exits matches the number of entrances. If sqlite3_mutex_leave() is called on a mutex that the thread is not currently holding, then the behavior is undefined. If any routine is called for a deallocated mutex, then the behavior is undefined.

The SQLite source code provides multiple implementations of these APIs, suitable for varying environments. If SQLite is compiled with the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that is fast but does no real mutual exclusion is provided. That implementation is suitable for use in single-threaded applications or applications that only use SQLite in a single thread. Other real mutex implementations are provided based on the underlying operating system.

Embedded applications may wish to provide their own mutex implementation. If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag then the SQLite core provides no mutex subsystem and a mutex subsystem that matches the interface described above must be provided by the application that links against SQLite.

5.0 Other Interface Changes

Version 3.5.0 of SQLite changes the behavior of a few APIs in ways that are technically incompatible. However, these APIs are seldom used and even when they are used it is difficult to imagine a scenario where the change might break something. The changes actually makes these interface much more useful and powerful.

Prior to version 3.5.0, the sqlite3_enable_shared_cache() API would enable and disable the shared cache feature for all connections within a single thread - the same thread from which the sqlite3_enable_shared_cache() routine was called. Database connections that used the shared cache were restricted to running in the same thread in which they were opened. Beginning with version 3.5.0, the sqlite3_enable_shared_cache() applies to all database connections in all threads within the process. Now database connections running in separate threads can share a cache. And database connections that use shared cache can migrate from one thread to another.

Prior to version 3.5.0 the sqlite3_soft_heap_limit() set an upper bound on heap memory usage for all database connections within a single thread. Each thread could have its own heap limit. Beginning in version 3.5.0, there is a single heap limit for the entire process. This seems more restrictive (one limit as opposed to many) but in practice it is what most users want.

Prior to version 3.5.0 the sqlite3_release_memory() function would try to reclaim memory from all database connections in the same thread as the sqlite3_release_memory() call. Beginning with version 3.5.0, the sqlite3_release_memory() function will attempt to reclaim memory from all database connections in all threads.

6.0 Summary

The transition from SQLite version 3.4.2 to 3.5.0 is a major change. Every source code file in the SQLite core had to be modified, some extensively. And the change introduced some minor incompatibilities in the C interface. But we feel that the benefits of the transition from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new VFS layer is now well-defined and stable and should simplify future customizations. The VFS layer, and the separable memory allocator and mutex subsystems allow a standard SQLite source code amalgamation to be used in an embedded project without change, greatly simplifying configuration management. And the resulting system is much more tolerant of highly threaded designs.


SQLite Changes From Version 3.5.9 To 3.6.0

Choose any three.
About Sitemap Documentation Download License News Support

Moving From SQLite 3.5.9 to 3.6.0

SQLite version 3.6.0 contains many changes. As is the custom with the SQLite project, most changes are fully backwards compatible. However, a few of the changes in version 3.6.0 are incompatible and might require modifications to application code and/or makefiles. This document is a briefing on the changes in SQLite 3.6.0 with special attention to the incompatible changes.

Key Points:
  • The database file format is unchanged.
  • All incompatibilities are on obscure interfaces and hence should have zero impact on most applications.

1.0 Incompatible Changes

Incompatible changes are covered first since they are the most important to maintainers and programmers.

1.1 Overview Of Incompatible Changes

  1. Changes to the sqlite3_vfs object

    1. The signature of the xAccess method has been modified to return an error code and to store its output into an integer pointed to by a parameter, rather than returning the output directly. This change allows the xAccess() method to report failures. In association with this signature change, a new extended error code SQLITE_IOERR_ACCESS has been added.

    2. The xGetTempname method has been removed from sqlite3_vfs. In its place, the xOpen method is enhanced to open a temporary file of its own invention when the filename parameter is NULL.

    3. Added the xGetLastError() method to sqlite3_vfs for returning filesystem-specific error messages and error codes back to SQLite.

  2. The signature of the xCheckReservedLock method on sqlite3_io_methods has been modified so that it returns an error code and stores its boolean result into an integer pointed to by a parameter. In association with this change, a new extended error code SQLITE_IOERR_CHECKRESERVEDLOCK has been added.

  3. When SQLite is ported to new operation systems (operating systems other than Unix, Windows, and OS/2 for which ports are provided together with the core) two new functions, sqlite3_os_init() and sqlite3_os_end(), must be provided as part of the port.

  4. The way in which the IN and NOT IN operators handle NULL values in their right-hand expressions has been brought into compliance with the SQL standard and with other SQL database engines.

  5. The column names for the result sets of SELECT statements have been tweaked in some cases to work more like other SQL database engines.

  6. Changes to compile-time options:

    1. The SQLITE_MUTEX_APPDEF compile-time parameter is no longer recognized. As a replacement, alternative mutex implementations may be created at runtime using sqlite3_config() with the SQLITE_CONFIG_MUTEX operator and the sqlite3_mutex_methods object.

    2. Compile-time options OS_UNIX, OS_WIN, OS_OS2, OS_OTHER, and TEMP_STORE have been renamed to include an "SQLITE_" prefix in order to help avoid namespace collisions with application software. The new names of these options are respectively: SQLITE_OS_UNIX, SQLITE_OS_WIN, SQLITE_OS_OS2, SQLITE_OS_OTHER, and SQLITE_TEMP_STORE.

1.2 Changes To The VFS Layer

SQLite version 3.5.0 introduced a new OS interface layer that provided an abstraction of the underlying operating system. This was an important innovation and has proven to be helpful in porting and maintaining SQLite. However, the developers have discovered some minor flaws in the original "virtual file system" design introduced in version 3.5.0 and so SQLite 3.6.0 includes some small incompatible changes to address these flaws.

Key Point: The incompatible changes in the SQLite operating-system interface for version 3.6.0 only affect the rare applications that make use of the virtual file system interface or that supply an application-defined mutex implementation or that make use of other obscure compile-time options. The changes introduced by SQLite version 3.6.0 will have zero impact on the vast majority of SQLite applications that use the built-in interfaces to Unix, Windows, and OS/2 and that use the standard build configuration.

1.3 Changes In The Way The IN Operator Handles NULLs

All versions of SQLite up to and including version 3.5.9 have mishandled NULL values on the right-hand side of IN and NOT IN operators. Specifically, SQLite has previously ignored NULLs on the right-hand side of IN and NOT IN.

Suppose we have a table X1 defined as follows:

  CREATE TABLE x1(x INTEGER);
  INSERT INTO x1 VALUES(1);
  INSERT INTO x1 VALUES(2);
  INSERT INTO x1 VALUES(NULL);

Given the definition of X1 above, the following expressions have historically evaluated to FALSE in SQLite, though the correct answer is actually NULL:

  3 IN (1,2,NULL)
  3 IN (SELECT * FROM x1)

Similarly, the following expressions have historically evaluated to TRUE when in fact NULL is also the correct answer here:

  3 NOT IN (1,2,NULL)
  3 NOT IN (SELECT * FROM x1)

The historical behavior of SQLite is incorrect according to the SQL:1999 standard and it is inconsistent with the behavior of MySQL and PostgreSQL. Version 3.6.0 changes the behavior of the IN and NOT IN operators to conform to the standard and to give the same results as other SQL database engines.

Key Point: The change to the way NULL values are handled by the IN and NOT IN operators is technically a bug fix, not a design change. However, maintainers should check to ensure that applications do not depend on the older, buggy behavior prior to upgrading to version 3.6.0.

1.4 Changes To Column Naming Rules

The column names reported by join subqueries have been modified slightly in order to work more like other database engines. Consider the following query:

  CREATE TABLE t1(a);
  CREATE TABLE t2(x);
  SELECT * FROM (SELECT t1.a FROM t1 JOIN t2 ORDER BY t2.x LIMIT 1) ORDER BY 1;

In version 3.5.9 the query above would return a single column named "t1.a". In version 3.6.0 the column name is just "a".

SQLite has never made any promises about the names of columns in the result set of SELECT statement unless the column contains an AS clause. So this change to column name is technically not an incompatibility. SQLite is merely changing from one undefined behavior to another. Nevertheless, many applications depend on the unspecified column naming behavior of SQLite and so this change is discussed under the incompatible changes subheading.

1.5 Changes To Compile-Time Options

Compile-time options to SQLite are controlled by C-preprocessor macros. SQLite version 3.6.0 changes the names of some of these macros so that all C-preprocessor macros that are specific to SQLite begin with the "SQLITE_" prefix. This is done to reduce the risk of name collisions with other software modules.

Key Point: Changes to compile-time options have the potential to affect makefiles in projects that do customized builds of SQLite. These changes should have zero impact on application code and for most projects which use a standard, default build of SQLite.

2.0 Fully Backwards-Compatible Enhancements

In addition to the incompatible changes listed above, SQLite version 3.6.0 adds the following backwards compatible changes and enhancements:

  7. The new sqlite3_config() interface allows an application to customize the behavior of SQLite at run-time. Customizations possible using sqlite3_config() include the following:

    1. Specify an alternative mutex implementation using the SQLITE_CONFIG_MUTEX verb with the sqlite3_mutex_methods object.

    2. Specify an alternative malloc implementation using the SQLITE_CONFIG_MALLOC verb with the sqlite3_mem_methods object.

    3. Partially or fully disable the use of mutexes using SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD and SQLITE_CONFIG_SERIALIZED.

  8. A new flag SQLITE_OPEN_NOMUTEX is made available to the sqlite3_open_v2() interface.

  9. The new sqlite3_status() interface allows an application to query the performance status of SQLite at runtime.

  10. The sqlite3_memory_used() and sqlite3_memory_highwater() interfaces are deprecated. The equivalent functionality is now available through sqlite3_status().

  11. The sqlite3_initialize() interface can be called to explicitly initialize the SQLite subsystem. The sqlite3_initialize() interface is called automatically when invoking certain interfaces so the use of sqlite3_initialize() is not required, but it is recommended.

  12. The sqlite3_shutdown() interface causes SQLite release any system resources (memory allocations, mutexes, open file handles) that it might have been allocated by sqlite3_initialize().

  13. The sqlite3_next_stmt() interface allows an application to discover all prepared statements associated with a database connection.

  14. Added the page_count PRAGMA for returning the size of the underlying database file in pages.

  15. Added a new R*Tree index extension.


About SQLite

See Also...

  • Features
  • Frequently Asked Questions
  • Well-known Users
  • Books About SQLite
  • Getting Started
  • SQL Syntax
    • Pragmas
    • SQL functions
    • Date & time functions
    • Aggregate functions
  • C/C++ Interface Spec
    • Introduction
    • List of C-language APIs
  • The TCL Interface Spec
  • Development Timeline
  • Report a Bug

SQLite is a in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. The code for SQLite is in the public domain and is thus free for use for any purpose, commercial or private. SQLite is currently found in more applications than we can count, including several high-profile projects.

SQLite is an embedded SQL database engine. Unlike most other SQL databases, SQLite does not have a separate server process. SQLite reads and writes directly to ordinary disk files. A complete SQL database with multiple tables, indices, triggers, and views, is contained in a single disk file. The database file format is cross-platform - you can freely copy a database between 32-bit and 64-bit systems or between big-endian and little-endian architectures. These features make SQLite a popular choice as an Application File Format. Think of SQLite not as a replacement for Oracle but as a replacement for fopen()

SQLite is a compact library. With all features enabled, the library size can be less than 350KiB, depending on the target platform and compiler optimization settings. (64-bit code is larger. And some compiler optimizations such as aggressive function inlining and loop unrolling can cause the object code to be much larger.) If optional features are omitted, the size of the SQLite library can be reduced below 200KiB. SQLite can also be made to run in minimal stack space (4KiB) and very little heap (100KiB), making SQLite a popular database engine choice on memory constrained gadgets such as cellphones, PDAs, and MP3 players. There is a tradeoff between memory usage and speed. SQLite generally runs faster the more memory you give it. Nevertheless, performance is usually quite good even in low-memory environments.

SQLite is very carefully tested prior to every release and has a reputation for being very reliable. Most of the SQLite source code is devoted purely to testing and verification. An automated test suite runs millions and millions of test cases involving hundreds of millions of individual SQL statements and achieves 100% branch test coverage. SQLite responds gracefully to memory allocation failures and disk I/O errors. Transactions are ACID even if interrupted by system crashes or power failures. All of this is verified by the automated tests using special test harnesses which simulate system failures. Of course, even with all this testing, there are still bugs. But unlike some similar projects (especially commercial competitors) SQLite is open and honest about all bugs and provides bugs lists including lists of critical bugs and minute-by-minute chronologies of bug reports and code changes.

The SQLite code base is supported by an international team of developers who work on SQLite full-time. The developers continue to expand the capabilities of SQLite and enhance its reliability and performance while maintaining backwards compatibility with the published interface spec, SQL syntax, and database file format. The source code is absolutely free to anybody who wants it, but professional support is also available.

We the developers hope that you find SQLite useful and we charge you to use it well: to make good and beautiful products that are fast, reliable, and simple to use. Seek forgiveness for yourself as you forgive others. And just as you have received SQLite for free, so also freely give, paying the debt forward.


The SQLite Amalgamation

The core SQLite library consists of about 96 files of C code (as of Version 3.6.21) in the core with 11 additional files in the FTS3 and RTREE extensions. Most of these are "source" files in the sense that they are stored in the configuration management system and are maintained directly. But 6 of the core C files are generated automatically during the compilation process. Of the 96 code files, 76 are C code and 20 are C header files.

The standard makefiles for SQLite have a target for building an object we call the "amalgamation". The amalgamation is a single C code file, named "sqlite3.c", that contains all C code for the core SQLite library and the FTS3 and RTREE extensions. This file contains about 110K lines of code (65K if you omit blank lines and comments) and is over 3.8 megabytes in size.

The amalgamation contains everything you need to integrate SQLite into a larger project. Just copy the amalgamation into your source directory and compile it along with the other C code files in your project. You may also want to make use of the "sqlite3.h" header file that defines the programming API for SQLite. The sqlite3.h header file is available separately. The sqlite3.h file is also contained within the amalgamation, in the first couple of thousand lines. So if you have a copy of sqlite3.c but cannot seem to locate sqlite3.h, you can always regenerate the sqlite3.h by copying and pasting from the amalgamation.

In addition to making SQLite easier to incorporate into other projects, the amalgamation also makes it run faster. Many compilers are able to do additional optimizations on code when it is contained with in a single translation unit such as it is in the amalgamation. We have measured performance improvements of between 5 and 10% when we use the amalgamation to compile SQLite rather than individual source files. The downside of this is that the additional optimizations often take the form of function inlining which tends to make the size of the resulting binary image larger.

The amalgamation and the sqlite3.h header file are available on the download page as a file named sqlite-amalgamation-X_X_X.zip where the X's are replaced by the appropriate version number.


Architecture of SQLite

Choose any three.
About Sitemap Documentation Download License News Support

The Architecture Of SQLite

Introduction

Block Diagram Of SQLite

This document describes the architecture of the SQLite library. The information here is useful to those who want to understand or modify the inner workings of SQLite.

A block diagram showing the main components of SQLite and how they interrelate is shown at the right. The text that follows will provide a quick overview of each of these components.

This document describes SQLite version 3.0. Version 2.8 and earlier are similar but the details differ.

Interface

Much of the public interface to the SQLite library is implemented by functions found in the main.c, legacy.c, and vdbeapi.c source files though some routines are scattered about in other files where they can have access to data structures with file scope. The sqlite3_get_table() routine is implemented in table.c. sqlite3_mprintf() is found in printf.c. sqlite3_complete() is in tokenize.c. The Tcl interface is implemented by tclsqlite.c. More information on the C interface to SQLite is available separately.

To avoid name collisions with other software, all external symbols in the SQLite library begin with the prefix sqlite3. Those symbols that are intended for external use (in other words, those symbols which form the API for SQLite) begin with sqlite3_.

Tokenizer

When a string containing SQL statements is to be executed, the interface passes that string to the tokenizer. The job of the tokenizer is to break the original string up into tokens and pass those tokens one by one to the parser. The tokenizer is hand-coded in C in the file tokenize.c.

Note that in this design, the tokenizer calls the parser. People who are familiar with YACC and BISON may be used to doing things the other way around -- having the parser call the tokenizer. The author of SQLite has done it both ways and finds things generally work out nicer for the tokenizer to call the parser. YACC has it backwards.

Parser

The parser is the piece that assigns meaning to tokens based on their context. The parser for SQLite is generated using the Lemon LALR(1) parser generator. Lemon does the same job as YACC/BISON, but it uses a different input syntax which is less error-prone. Lemon also generates a parser which is reentrant and thread-safe. And lemon defines the concept of a non-terminal destructor so that it does not leak memory when syntax errors are encountered. The source file that drives Lemon is found in parse.y.

Because lemon is a program not normally found on development machines, the complete source code to lemon (just one C file) is included in the SQLite distribution in the "tool" subdirectory. Documentation on lemon is found in the "doc" subdirectory of the distribution.

Code Generator

After the parser assembles tokens into complete SQL statements, it calls the code generator to produce virtual machine code that will do the work that the SQL statements request. There are many files in the code generator: attach.c, auth.c, build.c, delete.c, expr.c, insert.c, pragma.c, select.c, trigger.c, update.c, vacuum.c and where.c. In these files is where most of the serious magic happens. expr.c handles code generation for expressions. where.c handles code generation for WHERE clauses on SELECT, UPDATE and DELETE statements. The files attach.c, delete.c, insert.c, select.c, trigger.c update.c, and vacuum.c handle the code generation for SQL statements with the same names. (Each of these files calls routines in expr.c and where.c as necessary.) All other SQL statements are coded out of build.c. The auth.c file implements the functionality of sqlite3_set_authorizer().

Virtual Machine

The program generated by the code generator is executed by the virtual machine. Additional information about the virtual machine is available separately. To summarize, the virtual machine implements an abstract computing engine specifically designed to manipulate database files. The machine has a stack which is used for intermediate storage. Each instruction contains an opcode and up to three additional operands.

The virtual machine itself is entirely contained in a single source file vdbe.c. The virtual machine also has its own header files: vdbe.h that defines an interface between the virtual machine and the rest of the SQLite library and vdbeInt.h which defines structure private the virtual machine. The vdbeaux.c file contains utilities used by the virtual machine and interface modules used by the rest of the library to construct VM programs. The vdbeapi.c file contains external interfaces to the virtual machine such as the sqlite3_bind_... family of functions. Individual values (strings, integer, floating point numbers, and BLOBs) are stored in an internal object named "Mem" which is implemented by vdbemem.c.

SQLite implements SQL functions using callbacks to C-language routines. Even the built-in SQL functions are implemented this way. Most of the built-in SQL functions (ex: coalesce(), count(), substr(), and so forth) can be found in func.c. Date and time conversion functions are found in date.c.

B-Tree

An SQLite database is maintained on disk using a B-tree implementation found in the btree.c source file. A separate B-tree is used for each table and index in the database. All B-trees are stored in the same disk file. Details of the file format are recorded in a large comment at the beginning of btree.c.

The interface to the B-tree subsystem is defined by the header file btree.h.

Page Cache

The B-tree module requests information from the disk in fixed-size chunks. The default chunk size is 1024 bytes but can vary between 512 and 65536 bytes. The page cache is responsible for reading, writing, and caching these chunks. The page cache also provides the rollback and atomic commit abstraction and takes care of locking of the database file. The B-tree driver requests particular pages from the page cache and notifies the page cache when it wants to modify pages or commit or rollback changes. The page cache handles all the messy details of making sure the requests are handled quickly, safely, and efficiently.

The code to implement the page cache is contained in the single C source file pager.c. The interface to the page cache subsystem is defined by the header file pager.h.

OS Interface

In order to provide portability between POSIX and Win32 operating systems, SQLite uses an abstraction layer to interface with the operating system. The interface to the OS abstraction layer is defined in os.h. Each supported operating system has its own implementation: os_unix.c for Unix, os_win.c for Windows, and so forth. Each of these operating-specific implements typically has its own header file: os_unix.h, os_win.h, etc.

Utilities

Memory allocation and caseless string comparison routines are located in util.c. Symbol tables used by the parser are maintained by hash tables found in hash.c. The utf.c source file contains Unicode conversion subroutines. SQLite has its own private implementation of printf() (with some extensions) in printf.c and its own random number generator in random.c.

Test Code

If you count regression test scripts, more than half the total code base of SQLite is devoted to testing. There are many assert() statements in the main code files. In additional, the source files test1.c through test5.c together with md5.c implement extensions used for testing purposes only. The os_test.c backend interface is used to simulate power failures to verify the crash-recovery mechanism in the pager.


An Asynchronous I/O Module For SQLite

Normally, when SQLite writes to a database file, it waits until the write operation is finished before returning control to the calling application. Since writing to the file-system is usually very slow compared with CPU bound operations, this can be a performance bottleneck. The asynchronous I/O backend is an extension that causes SQLite to perform all write requests using a separate thread running in the background. Although this does not reduce the overall system resources (CPU, disk bandwidth etc.), it does allow SQLite to return control to the caller quickly even when writing to the database.

1.0 FUNCTIONALITY

With asynchronous I/O, write requests are handled by a separate thread running in the background. This means that the thread that initiates a database write does not have to wait for (sometimes slow) disk I/O to occur. The write seems to happen very quickly, though in reality it is happening at its usual slow pace in the background.

Asynchronous I/O appears to give better responsiveness, but at a price. You lose the Durable property. With the default I/O backend of SQLite, once a write completes, you know that the information you wrote is safely on disk. With the asynchronous I/O, this is not the case. If your program crashes or if a power loss occurs after the database write but before the asynchronous write thread has completed, then the database change might never make it to disk and the next user of the database might not see your change.

You lose Durability with asynchronous I/O, but you still retain the other parts of ACID: Atomic, Consistent, and Isolated. Many applications get along fine without the Durability.

1.1 How it Works

Asynchronous I/O works by creating an SQLite VFS object and registering it with sqlite3_vfs_register(). When files opened via this VFS are written to (using the vfs xWrite() method), the data is not written directly to disk, but is placed in the "write-queue" to be handled by the background thread.

When files opened with the asynchronous VFS are read from (using the vfs xRead() method), the data is read from the file on disk and the write-queue, so that from the point of view of the vfs reader the xWrite() appears to have already completed.

The asynchronous I/O VFS is registered (and unregistered) by calls to the API functions sqlite3async_initialize() and sqlite3async_shutdown(). See section "Compilation and Usage" below for details.

1.2 Limitations

In order to gain experience with the main ideas surrounding asynchronous IO, this implementation is deliberately kept simple. Additional capabilities may be added in the future.

For example, as currently implemented, if writes are happening at a steady stream that exceeds the I/O capability of the background writer thread, the queue of pending write operations will grow without bound. If this goes on for long enough, the host system could run out of memory. A more sophisticated module could to keep track of the quantity of pending writes and stop accepting new write requests when the queue of pending writes grows too large.

1.3 Locking and Concurrency

Multiple connections from within a single process that use this implementation of asynchronous IO may access a single database file concurrently. From the point of view of the user, if all connections are from within a single process, there is no difference between the concurrency offered by "normal" SQLite and SQLite using the asynchronous backend.

If file-locking is enabled (it is enabled by default), then connections from multiple processes may also read and write the database file. However concurrency is reduced as follows:

  • When a connection using asynchronous IO begins a database transaction, the database is locked immediately. However the lock is not released until after all relevant operations in the write-queue have been flushed to disk. This means (for example) that the database may remain locked for some time after a "COMMIT" or "ROLLBACK" is issued.

  • If an application using asynchronous IO executes transactions in quick succession, other database users may be effectively locked out of the database. This is because when a BEGIN is executed, a database lock is established immediately. But when the corresponding COMMIT or ROLLBACK occurs, the lock is not released until the relevant part of the write-queue has been flushed through. As a result, if a COMMIT is followed by a BEGIN before the write-queue is flushed through, the database is never unlocked,preventing other processes from accessing the database.

File-locking may be disabled at runtime using the sqlite3async_control() API (see below). This may improve performance when an NFS or other network file-system, as the synchronous round-trips to the server be required to establish file locks are avoided. However, if multiple connections attempt to access the same database file when file-locking is disabled, application crashes and database corruption is a likely outcome.

2.0 COMPILATION AND USAGE

The asynchronous IO extension consists of a single file of C code (sqlite3async.c), and a header file (sqlite3async.h), located in the ext/async/ subfolder of the SQLite source tree, that defines the C API used by applications to activate and control the modules functionality.

To use the asynchronous IO extension, compile sqlite3async.c as part of the application that uses SQLite. Then use the APIs defined in sqlite3async.h to initialize and configure the module.

The asynchronous IO VFS API is described in detail in comments in sqlite3async.h. Using the API usually consists of the following steps:

  1. Register the asynchronous IO VFS with SQLite by calling the sqlite3async_initialize() function.

  2. Create a background thread to perform write operations and call sqlite3async_run().

  3. Use the normal SQLite API to read and write to databases via the asynchronous IO VFS.

Refer to comments in the sqlite3async.h header file for details.

3.0 PORTING

Currently the asynchronous IO extension is compatible with win32 systems and systems that support the pthreads interface, including Mac OS X, Linux, and other varieties of Unix.

To port the asynchronous IO extension to another platform, the user must implement mutex and condition variable primitives for the new platform. Currently there is no externally available interface to allow this, but modifying the code within sqlite3async.c to include the new platforms concurrency primitives is relatively easy. Search within sqlite3async.c for the comment string "PORTING FUNCTIONS" for details. Then implement new versions of each of the following:

static void async_mutex_enter(int eMutex);
static void async_mutex_leave(int eMutex);
static void async_cond_wait(int eCond, int eMutex);
static void async_cond_signal(int eCond);
static void async_sched_yield(void);

The functionality required of each of the above functions is described in comments in sqlite3async.c.


Atomic Commit In SQLite

1.0 Introduction

An important feature of transactional databases like SQLite is "atomic commit". Atomic commit means that either all database changes within a single transaction occur or none of them occur. With atomic commit, it is as if many different writes to different sections of the database file occur instantaneously and simultaneously. Real hardware serializes writes to mass storage, and writing a single sector takes a finite amount of time. So it is impossible to truly write many different sectors of a database file simultaneously and/or instantaneously. But the atomic commit logic within SQLite makes it appear as if the changes for a transaction are all written instantaneously and simultaneously.

SQLite has the important property that transactions appear to be atomic even if the transaction is interrupted by an operating system crash or power failure.

This article describes the techniques used by SQLite to create the illusion of atomic commit.

The information in this article applies only when SQLite is not using a write-ahead log. Support for write-ahead logging was added in SQLite version 3.7.0. The write-ahead log is turned off by default.

2.0 Hardware Assumptions

Throughout this article, we will call the mass storage device "disk" even though the mass storage device might really be flash memory.

We assume that disk is written in chunks which we call a "sector". It is not possible to modify any part of the disk smaller than a sector. To change a part of the disk smaller than a sector, you have to read in the full sector that contains the part you want to change, make the change, then write back out the complete sector.

On a traditional spinning disk, a sector is the minimum unit of transfer in both directions, both reading and writing. On flash memory, however, the minimum size of a read is typically much smaller than a minimum write. SQLite is only concerned with the minimum write amount and so for the purposes of this article, when we say "sector" we mean the minimum amount of data that can be written to mass storage in a single go.

Prior to SQLite version 3.3.14, a sector size of 512 bytes was assumed in all cases. There was a compile-time option to change this but the code had never been tested with a larger value. The 512 byte sector assumption seemed reasonable since until very recently all disk drives used a 512 byte sector internally. However, there has recently been a push to increase the sector size of disks to 4096 bytes. Also the sector size for flash memory is usually larger than 512 bytes. For these reasons, versions of SQLite beginning with 3.3.14 have a method in the OS interface layer that interrogates the underlying filesystem to find the true sector size. As currently implemented (version 3.5.0) this method still returns a hard-coded value of 512 bytes, since there is no standard way of discovering the true sector size on either Unix or Windows. But the method is available for embedded device manufactures to tweak according to their own needs. And we have left open the possibility of filling in a more meaningful implementation on Unix and Windows in the future.

SQLite does not assume that a sector write is atomic. However, it does assume that a sector write is linear. By "linear" we mean that SQLite assumes that when writing a sector, the hardware begins at one end of the data and writes byte by byte until it gets to the other end. The write might go from beginning to end or from end to beginning. If a power failure occurs in the middle of a sector write it might be that part of the sector was modified and another part was left unchanged. The key assumption by SQLite is that if any part of the sector gets changed, then either the first or the last bytes will be changed. So the hardware will never start writing a sector in the middle and work towards the ends. We do not know if this assumption is always true but it seems reasonable.

The previous paragraph states that SQLite does not assume that sector writes are atomic. This is true by default. But as of SQLite version 3.5.0, there is a new interface called the Virtual File System (VFS) interface. The VFS is the only means by which SQLite communicates to the underlying filesystem. The code comes with default VFS implementations for Unix and Windows and there is a mechanism for creating new custom VFS implementations at runtime. In this new VFS interface there is a method called xDeviceCharacteristics. This method interrogates the underlying filesystem to discover various properties and behaviors that the filesystem may or may not exhibit. The xDeviceCharacteristics method might indicate that sector writes are atomic, and if it does so indicate, SQLite will try to take advantage of that fact. But the default xDeviceCharacteristics method for both Unix and Windows does not indicate atomic sector writes and so these optimizations are normally omitted.

SQLite assumes that the operating system will buffer writes and that a write request will return before data has actually been stored in the mass storage device. SQLite further assumes that write operations will be reordered by the operating system. For this reason, SQLite does a "flush" or "fsync" operation at key points. SQLite assumes that the flush or fsync will not return until all pending write operations for the file that is being flushed have completed. We are told that the flush and fsync primitives are broken on some versions of Windows and Linux. This is unfortunate. It opens SQLite up to the possibility of database corruption following a power loss in the middle of a commit. However, there is nothing that SQLite can do to test for or remedy the situation. SQLite assumes that the operating system that it is running on works as advertised. If that is not quite the case, well then hopefully you will not lose power too often.

SQLite assumes that when a file grows in length that the new file space originally contains garbage and then later is filled in with the data actually written. In other words, SQLite assumes that the file size is updated before the file content. This is a pessimistic assumption and SQLite has to do some extra work to make sure that it does not cause database corruption if power is lost between the time when the file size is increased and when the new content is written. The xDeviceCharacteristics method of the VFS might indicate that the filesystem will always write the data before updating the file size. (This is the SQLITE_IOCAP_SAFE_APPEND property for those readers who are looking at the code.) When the xDeviceCharacteristics method indicates that files content is written before the file size is increased, SQLite can forego some of its pedantic database protection steps and thereby decrease the amount of disk I/O needed to perform a commit. The current implementation, however, makes no such assumptions for the default VFSes for Windows and Unix.

SQLite assumes that a file deletion is atomic from the point of view of a user process. By this we mean that if SQLite requests that a file be deleted and the power is lost during the delete operation, once power is restored either the file will exist completely with all if its original content unaltered, or else the file will not be seen in the filesystem at all. If after power is restored the file is only partially deleted, if some of its data has been altered or erased, or the file has been truncated but not completely removed, then database corruption will likely result.

SQLite assumes that the detection and/or correction of bit errors caused by cosmic rays, thermal noise, quantum fluctuations, device driver bugs, or other mechanisms, is the responsibility of the underlying hardware and operating system. SQLite does not add any redundancy to the database file for the purpose of detecting corruption or I/O errors. SQLite assumes that the data it reads is exactly the same data that it previously wrote.

3.0 Single File Commit

We begin with an overview of the steps SQLite takes in order to perform an atomic commit of a transaction against a single database file. The details of file formats used to guard against damage from power failures and techniques for performing an atomic commit across multiple databases are discussed in later sections.

3.1 Initial State

The state of the computer when a database connection is first opened is shown conceptually by the diagram at the right. The area of the diagram on the extreme right (labeled "Disk") represents information stored on the mass storage device. Each rectangle is a sector. The blue color represents that the sectors contain original data. The middle area is the operating systems disk cache. At the onset of our example, the cache is cold and this is represented by leaving the rectangles of the disk cache empty. The left area of the diagram shows the content of memory for the process that is using SQLite. The database connection has just been opened and no information has been read yet, so the user space is empty.

3.2 Acquiring A Read Lock

Before SQLite can write to a database, it must first read the database to see what is there already. Even if it is just appending new data, SQLite still has to read in the database schema from the sqlite_master table so that it can know how to parse the INSERT statements and discover where in the database file the new information should be stored.

The first step toward reading from the database file is obtaining a shared lock on the database file. A "shared" lock allows two or more database connections to read from the database file at the same time. But a shared lock prevents another database connection from writing to the database file while we are reading it. This is necessary because if another database connection were writing to the database file at the same time we are reading from the database file, we might read some data before the change and other data after the change. This would make it appears as if the change made by the other process is not atomic.

Notice that the shared lock is on the operating system disk cache, not on the disk itself. File locks really are just flags within the operating system kernel, usually. (The details depend on the specific OS layer interface.) Hence, the lock will instantly vanish if the operating system crashes or if there is a power loss. It is usually also the case that the lock will vanish if the process that created the lock exits.

3.3 Reading Information Out Of The Database

After the shared lock is acquired, we can begin reading information from the database file. In this scenario, we are assuming a cold cache, so information must first be read from mass storage into the operating system cache then transferred from operating system cache into user space. On subsequent reads, some or all of the information might already be found in the operating system cache and so only the transfer to user space would be required.

Usually only a subset of the pages in the database file are read. In this example we are showing three pages out of eight being read. In a typical application, a database will have thousands of pages and a query will normally only touch a small percentage of those pages.

3.4 Obtaining A Reserved Lock

Before making changes to the database, SQLite first obtains a "reserved" lock on the database file. A reserved lock is similar to a shared lock in that both a reserved lock and shared lock allow other processes to read from the database file. A single reserve lock can coexist with multiple shared locks from other processes. However, there can only be a single reserved lock on the database file. Hence only a single process can be attempting to write to the database at one time.

The idea behind a reserved locks is that it signals that a process intends to modify the database file in the near future but has not yet started to make the modifications. And because the modifications have not yet started, other processes can continue to read from the database. However, no other process should also begin trying to write to the database.

3.5 Creating A Rollback Journal File

Prior to making any changes to the database file, SQLite first creates a separate rollback journal file and writes into the rollback journal the original content of the database pages that are to be altered. The idea behind the rollback journal is that it contains all information needed to restore the database back to its original state.

The rollback journal contains a small header (shown in green in the diagram) that records the original size of the database file. So if a change causes the database file to grow, we will still know the original size of the database. The page number is stored together with each database page that is written into the rollback journal.

When a new file is created, most desktop operating systems (Windows, Linux, Mac OS X) will not actually write anything to disk. The new file is created in the operating systems disk cache only. The file is not created on mass storage until sometime later, when the operating system has a spare moment. This creates the impression to users that I/O is happening much faster than is possible when doing real disk I/O. We illustrate this idea in the diagram to the right by showing that the new rollback journal appears in the operating system disk cache only and not on the disk itself.

3.6 Changing Database Pages In User Space

After the original page content has been saved in the rollback journal, the pages can be modified in user memory. Each database connection has its own private copy of user space, so the changes that are made in user space are only visible to the database connection that is making the changes. Other database connections still see the information in operating system disk cache buffers which have not yet been changed. And so even though one process is busy modifying the database, other processes can continue to read their own copies of the original database content.

3.7 Flushing The Rollback Journal File To Mass Storage

The next step is to flush the content of the rollback journal file to nonvolatile storage. As we will see later, this is a critical step in insuring that the database can survive an unexpected power loss. This step also takes a lot of time, since writing to nonvolatile storage is normally a slow operation.

This step is usually more complicated than simply flushing the rollback journal to the disk. On most platforms two separate flush (or fsync()) operations are required. The first flush writes out the base rollback journal content. Then the header of the rollback journal is modified to show the number of pages in the rollback journal. Then the header is flushed to disk. The details on why we do this header modification and extra flush are provided in a later section of this paper.

3.8 Obtaining An Exclusive Lock

Prior to making changes to the database file itself, we must obtain an exclusive lock on the database file. Obtaining an exclusive lock is really a two-step process. First SQLite obtains a "pending" lock. Then it escalates the pending lock to an exclusive lock.

A pending lock allows other processes that already have a shared lock to continue reading the database file. But it prevents new shared locks from being established. The idea behind a pending lock is to prevent writer starvation caused by a large pool of readers. There might be dozens, even hundreds, of other processes trying to read the database file. Each process acquires a shared lock before it starts reading, reads what it needs, then releases the shared lock. If, however, there are many different processes all reading from the same database, it might happen that a new process always acquires its shared lock before the previous process releases its shared lock. And so there is never an instant when there are no shared locks on the database file and hence there is never an opportunity for the writer to seize the exclusive lock. A pending lock is designed to prevent that cycle by allowing existing shared locks to proceed but blocking new shared locks from being established. Eventually all shared locks will clear and the pending lock will then be able to escalate into an exclusive lock.

3.9 Writing Changes To The Database File

Once an exclusive lock is held, we know that no other processes are reading from the database file and it is safe to write changes into the database file. Usually those changes only go as far as the operating systems disk cache and do not make it all the way to mass storage.

3.10 Flushing Changes To Mass Storage

Another flush must occur to make sure that all the database changes are written into nonvolatile storage. This is a critical step to ensure that the database will survive a power loss without damage. However, because of the inherent slowness of writing to disk or flash memory, this step together with the rollback journal file flush in section 3.7 above takes up most the time required to complete a transaction commit in SQLite.

3.11 Deleting The Rollback Journal

After the database changes are all safely on the mass storage device, the rollback journal file is deleted. This is the instant where the transaction commits. If a power failure or system crash occurs prior to this point, then recovery processes to be described later make it appears as if no changes were ever made to the database file. If a power failure or system crash occurs after the rollback journal is deleted, then it appears as if all changes have been written to disk. Thus, SQLite gives the appearance of having made no changes to the database file or having made the complete set of changes to the database file depending on whether or not the rollback journal file exists.

Deleting a file is not really an atomic operation, but it appears to be from the point of view of a user process. A process is always able to ask the operating system "does this file exist?" and the process will get back a yes or no answer. After a power failure that occurs during a transaction commit, SQLite will ask the operating system whether or not the rollback journal file exists. If the answer is "yes" then the transaction is incomplete and is rolled back. If the answer is "no" then it means the transaction did commit.

The existence of a transaction depends on whether or not the rollback journal file exists and the deletion of a file appears to be an atomic operation from the point of view of a user-space process. Therefore, a transaction appears to be an atomic operation.

The act of deleting a file is expensive on many systems. As an optimization, SQLite can be configured to truncate the journal file to zero bytes in length or overwrite the journal file header with zeros. In either case, the resulting journal file is no longer capable of rolling back and so the transaction still commits. Truncating a file to zero length, like deleting a file, is assumed to be an atomic operation from the point of view of a user process. Overwriting the header of the journal with zeros is not atomic, but if any part of the header is malformed the journal will not roll back. Hence, one can say that the commit occurs as soon as the header is sufficiently changed to make it invalid. Typically this happens as soon as the first byte of the header is zeroed.

3.12 Releasing The Lock

The last step in the commit process is to release the exclusive lock so that other processes can once again start accessing the database file.

In the diagram at the right, we show that the information that was held in user space is cleared when the lock is released. This used to be literally true for older versions of SQLite. But more recent versions of SQLite keep the user space information in memory in case it might be needed again at the start of the next transaction. It is cheaper to reuse information that is already in local memory than to transfer the information back from the operating system disk cache or to read it off of the disk drive again. Prior to reusing the information in user space, we must first reacquire the shared lock and then we have to check to make sure that no other process modified the database file while we were not holding a lock. There is a counter in the first page of the database that is incremented every time the database file is modified. We can find out if another process has modified the database by checking that counter. If the database was modified, then the user space cache must be cleared and reread. But it is commonly the case that no changes have been made and the user space cache can be reused for a significant performance savings.

4.0 Rollback

An atomic commit is supposed to happen instantaneously. But the processing described above clearly takes a finite amount of time. Suppose the power to the computer were cut part way through the commit operation described above. In order to maintain the illusion that the changes were instantaneous, we have to "rollback" any partial changes and restore the database to the state it was in prior to the beginning of the transaction.

4.1 When Something Goes Wrong...

Suppose the power loss occurred during step 3.10 above, while the database changes were being written to disk. After power is restored, the situation might be something like what is shown to the right. We were trying to change three pages of the database file but only one page was successfully written. Another page was partially written and a third page was not written at all.

The rollback journal is complete and intact on disk when the power is restored. This is a key point. The reason for the flush operation in step 3.7 is to make absolutely sure that all of the rollback journal is safely on nonvolatile storage prior to making any changes to the database file itself.

4.2 Hot Rollback Journals

The first time that any SQLite process attempts to access the database file, it obtains a shared lock as described in section 3.2 above. But then it notices that there is a rollback journal file present. SQLite then checks to see if the rollback journal is a "hot journal". A hot journal is a rollback journal that needs to be played back in order to restore the database to a sane state. A hot journal only exists when an earlier process was in the middle of committing a transaction when it crashed or lost power.

A rollback journal is a "hot" journal if all of the following are true:

  • The rollback journal exist.
  • The rollback journal is not an empty file.
  • There is no reserved lock on the main database file.
  • The header of the rollback journal is well-formed and in particular has not been zeroed out.
  • The rollback journal does not contain the name of a master journal file (see section 5.5 below) or if does contain the name of a master journal, then that master journal file exists.

The presence of a hot journal is our indication that a previous process was trying to commit a transaction but it aborted for some reason prior to the completion of the commit. A hot journal means that the database file is in an inconsistent state and needs to be repaired (by rollback) prior to being used.

4.3 Obtaining An Exclusive Lock On The Database

The first step toward dealing with a hot journal is to obtain an exclusive lock on the database file. This prevents two or more processes from trying to rollback the same hot journal at the same time.

4.4 Rolling Back Incomplete Changes

Once a process obtains an exclusive lock, it is permitted to write to the database file. It then proceeds to read the original content of pages out of the rollback journal and write that content back to were it came from in the database file. Recall that the header of the rollback journal records the original size of the database file prior to the start of the aborted transaction. SQLite uses this information to truncate the database file back to its original size in cases where the incomplete transaction caused the database to grow. At the end of this step, the database should be the same size and contain the same information as it did before the start of the aborted transaction.

4.5 Deleting The Hot Journal

After all information in the rollback journal has been played back into the database file (and flushed to disk in case we encounter yet another power failure), the hot rollback journal can be deleted.

As in section 3.11, the journal file might be truncated to zero length or its header might be overwritten with zeros as an optimization on systems where deleting a file is expense. Either way, the journal is no long hot after this step.

4.6 Continue As If The Uncompleted Writes Had Never Happened

The final recovery step is to reduce the exclusive lock back to a shared lock. Once this happens, the database is back in the state that it would have been if the aborted transaction had never started. Since all of this recovery activity happens completely automatically and transparently, it appears to the program using SQLite as if the aborted transaction had never begun.

5.0 Multi-file Commit

SQLite allows a single database connection to talk to two or more database files simultaneously through the use of the ATTACH DATABASE command. When multiple database files are modified within a single transaction, all files are updated atomically. In other words, either all of the database files are updated or else none of them are. Achieving an atomic commit across multiple database files is more complex that doing so for a single file. This section describes how SQLite works that bit of magic.

5.1 Separate Rollback Journals For Each Database

When multiple database files are involved in a transaction, each database has its own rollback journal and each database is locked separately. The diagram at the right shows a scenario where three different database files have been modified within one transaction. The situation at this step is analogous to the single-file transaction scenario at step 3.6. Each database file has a reserved lock. For each database, the original content of pages that are being changed have been written into the rollback journal for that database, but the content of the journals have not yet been flushed to disk. No changes have been made to the database file itself yet, though presumably there are changes being held in user memory.

For brevity, the diagrams in this section are simplified from those that came before. Blue color still signifies original content and pink still signifies new content. But the individual pages in the rollback journal and the database file are not shown and we are not making the distinction between information in the operating system cache and information that is on disk. All of these factors still apply in a multi-file commit scenario. They just take up a lot of space in the diagrams and they do not add any new information, so they are omitted here.

5.2 The Master Journal File

The next step in a multi-file commit is the creation of a "master journal" file. The name of the master journal file is the same name as the original database filename (the database that was opened using the sqlite3_open() interface, not one of the ATTACHed auxiliary databases) with the text "-mj HHHHHHHH" appended where HHHHHHHH is a random 32-bit hexadecimal number. The random HHHHHHHH suffix changes for every new master journal.

(Nota bene: The formula for computing the master journal filename given in the previous paragraph corresponds to the implementation as of SQLite version 3.5.0. But this formula is not part of the SQLite specification and is subject to change in future releases.)

Unlike the rollback journals, the master journal does not contain any original database page content. Instead, the master journal contains the full pathnames for rollback journals for every database that is participating in the transaction.

After the master journal is constructed, its content is flushed to disk before any further actions are taken. On Unix, the directory that contains the master journal is also synced in order to make sure the master journal file will appear in the directory following a power failure.

5.3 Updating Rollback Journal Headers

The next step is to record the full pathname of the master journal file in the header of every rollback journal. Space to hold the master journal filename was reserved at the beginning of each rollback journal as the rollback journals were created.

The content of each rollback journal is flushed to disk both before and after the master journal filename is written into the rollback journal header. It is important to do both of these flushes. Fortunately, the second flush is usually inexpensive since typically only a single page of the journal file (the first page) has changed.

This step is analogous to step 3.7 in the single-file commit scenario described above.

5.4 Updating The Database Files

Once all rollback journal files have been flushed to disk, it is safe to begin updating database files. We have to obtain an exclusive lock on all database files before writing the changes. After all the changes are written, it is important to flush the changes to disk so that they will be preserved in the event of a power failure or operating system crash.

This step corresponds to steps 3.8, 3.9, and 3.10 in the single-file commit scenario described previously.

5.5 Delete The Master Journal File

The next step is to delete the master journal file. This is the point where the multi-file transaction commits. This step corresponds to step 3.11 in the single-file commit scenario where the rollback journal is deleted.

If a power failure or operating system crash occurs at this point, the transaction will not rollback when the system reboots even though there are rollback journals present. The difference is the master journal pathname in the header of the rollback journal. Upon restart, SQLite only considers a journal to be hot and will only playback the journal if there is no master journal filename in the header (which is the case for a single-file commit) or if the master journal file still exists on disk.

5.6 Clean Up The Rollback Journals

The final step in a multi-file commit is to delete the individual rollback journals and drop the exclusive locks on the database files so that other processes can see the changes. This corresponds to step 3.12 in the single-file commit sequence.

The transaction has already committed at this point so timing is not critical in the deletion of the rollback journals. The current implementation deletes a single rollback journal then unlocks the corresponding database file before proceeding to the next rollback journal. But in the future we might change this so that all rollback journals are deleted before any database files are unlocked. As long as the rollback journal is deleted before its corresponding database file is unlocked it does not matter in what order the rollback journals are deleted or the database files are unlocked.

6.0 Additional Details Of The Commit Process

Section 3.0 above provides an overview of how atomic commit works in SQLite. But it glosses over a number of important details. The following subsections will attempt to fill in the gaps.

6.1 Always Journal Complete Sectors

When the original content of a database page is written into the rollback journal (as shown in section 3.5), SQLite always writes a complete sectors worth of data, even if the page size of the database is smaller than the sector size. Historically, the sector size in SQLite has been hard coded to 512 bytes and since the minimum page size is also 512 bytes, this has never been an issue. But beginning with SQLite version 3.3.14, it is possible for SQLite to use mass storage devices with a sector size larger than 512 bytes. So, beginning with version 3.3.14, whenever any page within a sector is written into the journal file, all pages in that same sector are stored with it.

It is important to store all pages of a sector in the rollback journal in order to prevent database corruption following a power loss while writing the sector. Suppose that pages 1, 2, 3, and 4 are all stored in sector 1 and that page 2 is modified. In order to write the changes to page 2, the underlying hardware must also rewrite the content of pages 1, 3, and 4 since the hardware must write the complete sector. If this write operation is interrupted by a power outage, one or more of the pages 1, 3, or 4 might be left with incorrect data. Hence, to avoid lasting corruption to the database, the original content of all of those pages must be contained in the rollback journal.

6.2 Dealing With Garbage Written Into Journal Files

When data is appended to the end of the rollback journal, SQLite normally makes the pessimistic assumption that the file is first extended with invalid "garbage" data and that afterwards the correct data replaces the garbage. In other words, SQLite assumes that the file size is increased first and then afterwards the content is written into the file. If a power failure occurs after the file size has been increased but before the file content has been written, the rollback journal can be left containing garbage data. If after power is restored, another SQLite process sees the rollback journal containing the garbage data and tries to roll it back into the original database file, it might copy some of the garbage into the database file and thus corrupt the database file.

SQLite uses two defenses against this problem. In the first place, SQLite records the number of pages in the rollback journal in the header of the rollback journal. This number is initially zero. So during an attempt to rollback an incomplete (and possibly corrupt) rollback journal, the process doing the rollback will see that the journal contains zero pages and will thus make no changes to the database. Prior to a commit, the rollback journal is flushed to disk to ensure that all content has been synced to disk and there is no "garbage" left in the file, and only then is the page count in the header changed from zero to true number of pages in the rollback journal. The rollback journal header is always kept in a separate sector from any page data so that it can be overwritten and flushed without risking damage to a data page if a power outage occurs. Notice that the rollback journal is flushed to disk twice: once to write the page content and a second time to write the page count in the header.

The previous paragraph describes what happens when the synchronous pragma setting is "full".

PRAGMA synchronous=FULL;

The default synchronous setting is full so the above is what usually happens. However, if the synchronous setting is lowered to "normal", SQLite only flushes the rollback journal once, after the page count has been written. This carries a risk of corruption because it might happen that the modified (non-zero) page count reaches the disk surface before all of the data does. The data will have been written first, but SQLite assumes that the underlying filesystem can reorder write requests and that the page count can be burned into oxide first even though its write request occurred last. So as a second line of defense, SQLite also uses a 32-bit checksum on every page of data in the rollback journal. This checksum is evaluated for each page during rollback while rolling back a journal as described in section 4.4. If an incorrect checksum is seen, the rollback is abandoned. Note that the checksum does not guarantee that the page data is correct since there is a small but finite probability that the checksum might be right even if the data is corrupt. But the checksum does at least make such an error unlikely.

Note that the checksums in the rollback journal are not necessary if the synchronous setting is FULL. We only depend on the checksums when synchronous is lowered to NORMAL. Nevertheless, the checksums never hurt and so they are included in the rollback journal regardless of the synchronous setting.

6.3 Cache Spill Prior To Commit

The commit process shown in section 3.0 assumes that all database changes fit in memory until it is time to commit. This is the common case. But sometimes a larger change will overflow the user-space cache prior to transaction commit. In those cases, the cache must spill to the database before the transaction is complete.

At the beginning of a cache spill, the status of the database connection is as shown in step 3.6. Original page content has been saved in the rollback journal and modifications of the pages exist in user memory. To spill the cache, SQLite executes steps 3.7 through 3.9. In other words, the rollback journal is flushed to disk, an exclusive lock is acquired, and changes are written into the database. But the remaining steps are deferred until the transaction really commits. A new journal header is appended to the end of the rollback journal (in its own sector) and the exclusive database lock is retained, but otherwise processing returns to step 3.6. When the transaction commits, or if another cache spill occurs, steps 3.7 and 3.9 are repeated. (Step 3.8 is omitted on second and subsequent passes since an exclusive database lock is already held due to the first pass.)

A cache spill causes the lock on the database file to escalate from reserved to exclusive. This reduces concurrency. A cache spill also causes extra disk flush or fsync operations to occur and these operations are slow, hence a cache spill can seriously reduce performance. For these reasons a cache spill is avoided whenever possible.

7.0 Optimizations

Profiling indicates that for most systems and in most circumstances SQLite spends most of its time doing disk I/O. It follows then that anything we can do to reduce the amount of disk I/O will likely have a large positive impact on the performance of SQLite. This section describes some of the techniques used by SQLite to try to reduce the amount of disk I/O to a minimum while still preserving atomic commit.

7.1 Cache Retained Between Transactions

Step 3.12 of the commit process shows that once the shared lock has been released, all user-space cache images of database content must be discarded. This is done because without a shared lock, other processes are free to modify the database file content and so any user-space image of that content might become obsolete. Consequently, each new transaction would begin by rereading data which had previously been read. This is not as bad as it sounds at first since the data being read is still likely in the operating systems file cache. So the "read" is really just a copy of data from kernel space into user space. But even so, it still takes time.

Beginning with SQLite version 3.3.14 a mechanism has been added to try to reduce the needless rereading of data. In newer versions of SQLite, the data in the user-space pager cache is retained when the lock on the database file is released. Later, after the shared lock is acquired at the beginning of the next transaction, SQLite checks to see if any other process has modified the database file. If the database has been changed in any way since the lock was last released, the user-space cache is erased at that point. But commonly the database file is unchanged and the user-space cache can be retained, and some unnecessary read operations can be avoided.

In order to determine whether or not the database file has changed, SQLite uses a counter in the database header (in bytes 24 through 27) which is incremented during every change operation. SQLite saves a copy of this counter prior to releasing its database lock. Then after acquiring the next database lock it compares the saved counter value against the current counter value and erases the cache if the values are different, or reuses the cache if they are the same.

7.2 Exclusive Access Mode

SQLite version 3.3.14 adds the concept of "Exclusive Access Mode". In exclusive access mode, SQLite retains the exclusive database lock at the conclusion of each transaction. This prevents other processes for accessing the database, but in many deployments only a single process is using a database so this is not a serious problem. The advantage of exclusive access mode is that disk I/O can be reduced in three ways:

  1. It is not necessary to increment the change counter in the database header for transactions after the first transaction. This will often save a write of page one to both the rollback journal and the main database file.

  2. No other processes can change the database so there is never a need to check the change counter and clear the user-space cache at the beginning of a transaction.

  3. Each transaction can be committed by overwriting the rollback journal header with zeros rather than deleting the journal file. This avoids having to modify the directory entry for the journal file and it avoids having to deallocate disk sectors associated with the journal. Furthermore, the next transaction will overwrite existing journal file content rather than append new content and on most systems overwriting is much faster than appending.

The third optimization, zeroing the journal file header rather than deleting the rollback journal file, does not depend on holding an exclusive lock at all times. This optimization can be set independently of exclusive lock mode using the journal_mode pragma as described in section 7.6 below.

7.3 Do Not Journal Freelist Pages

When information is deleted from an SQLite database, the pages used to hold the deleted information are added to a "freelist". Subsequent inserts will draw pages off of this freelist rather than expanding the database file.

Some freelist pages contain critical data; specifically the locations of other freelist pages. But most freelist pages contain nothing useful. These latter freelist pages are called "leaf" pages. We are free to modify the content of a leaf freelist page in the database without changing the meaning of the database in any way.

Because the content of leaf freelist pages is unimportant, SQLite avoids storing leaf freelist page content in the rollback journal in step 3.5 of the commit process. If a leaf freelist page is changed and that change does not get rolled back during a transaction recovery, the database is not harmed by the omission. Similarly, the content of a new freelist page is never written back into the database at step 3.9 nor read from the database at step 3.3. These optimizations can greatly reduce the amount of I/O that occurs when making changes to a database file that contains free space.

7.4 Single Page Updates And Atomic Sector Writes

Beginning in SQLite version 3.5.0, the new Virtual File System (VFS) interface contains a method named xDeviceCharacteristics which reports on special properties that the underlying mass storage device might have. Among the special properties that xDeviceCharacteristics might report is the ability of to do an atomic sector write.

Recall that by default SQLite assumes that sector writes are linear but not atomic. A linear write starts at one end of the sector and changes information byte by byte until it gets to the other end of the sector. If a power loss occurs in the middle of a linear write then part of the sector might be modified while the other end is unchanged. In an atomic sector write, either the entire sector is overwritten or else nothing in the sector is changed.

We believe that most modern disk drives implement atomic sector writes. When power is lost, the drive uses energy stored in capacitors and/or the angular momentum of the disk platter to provide power to complete any operation in progress. Nevertheless, there are so many layers in between the write system call and the on-board disk drive electronics that we take the safe approach in both Unix and w32 VFS implementations and assume that sector writes are not atomic. On the other hand, device manufactures with more control over their filesystems might want to consider enabling the atomic write property of xDeviceCharacteristics if their hardware really does do atomic writes.

When sector writes are atomic and the page size of a database is the same as a sector size, and when there is a database change that only touches a single database page, then SQLite skips the whole journaling and syncing process and simply writes the modified page directly into the database file. The change counter in the first page of the database file is modified separately since no harm is done if power is lost before the change counter can be updated.

7.5 Filesystems With Safe Append Semantics

Another optimization introduced in SQLite version 3.5.0 makes use of "safe append" behavior of the underlying disk. Recall that SQLite assumes that when data is appended to a file (specifically to the rollback journal) that the size of the file is increased first and that the content is written second. So if power is lost after the file size is increased but before the content is written, the file is left containing invalid "garbage" data. The xDeviceCharacteristics method of the VFS might, however, indicate that the filesystem implements "safe append" semantics. This means that the content is written before the file size is increased so that it is impossible for garbage to be introduced into the rollback journal by a power loss or system crash.

When safe append semantics are indicated for a filesystem, SQLite always stores the special value of -1 for the page count in the header of the rollback journal. The -1 page count value tells any process attempting to rollback the journal that the number of pages in the journal should be computed from the journal size. This -1 value is never changed. So that when a commit occurs, we save a single flush operation and a sector write of the first page of the journal file. Furthermore, when a cache spill occurs we no longer need to append a new journal header to the end of the journal; we can simply continue appending new pages to the end of the existing journal.

7.6 Persistent Rollback Journals

Deleting a file is an expensive operation on many systems. So as an optimization, SQLite can be configured to avoid the delete operation of section 3.11. Instead of deleting the journal file in order to commit a transaction, the file is either truncated to zero bytes in length or its header is overwritten with zeros. Truncating the file to zero length saves having to make modifications to the directory containing the file since the file is not removed from the directory. Overwriting the header has the additional savings of not having to update the length of the file (in the "inode" on many systems) and not having to deal with newly freed disk sectors. Furthermore, at the next transaction the journal will be created by overwriting existing content rather than appending new content onto the end of a file, and overwriting is often much faster than appending.

SQLite can be configured to commit transactions by overwriting the journal header with zeros instead of deleting the journal file by setting the "PERSIST" journaling mode using the journal_mode PRAGMA. For example:

PRAGMA journal_mode=PERSIST;

The use of persistent journal mode provide a noticeable performance improvement on many systems. Of course, the drawback is that the journal files remain on the disk, using disk space and cluttering directories, long after the transaction commits. The only safe way to delete a persistent journal file is to commit a transaction with journaling mode set to DELETE:

PRAGMA journal_mode=DELETE;
BEGIN EXCLUSIVE;
COMMIT;

Beware of deleting persistent journal files by any other means since the journal file might be hot, in which case deleting it will corrupt the corresponding database file.

Beginning in SQLite version 3.6.4, the TRUNCATE journal mode is also supported:

PRAGMA journal_mode=TRUNCATE;

In truncate journal mode, the transaction is committed by truncating the journal file to zero length rather than deleting the journal file (as in DELETE mode) or by zeroing the header (as in PERSIST mode). TRUNCATE mode shares the advantage of PERSIST mode that the directory that contains the journal file and database does not need to be updated. Hence truncating a file is often faster than deleting it. TRUNCATE has the additional advantage that it is not followed by a system call (ex: fsync()) to synchronize the change to disk. It might be safer if it did. But on many modern filesystems, a truncate is an atomic and synchronous operation and so we think that TRUNCATE will usually be safe in the face of power failures. If you are uncertain about whether or not TRUNCATE will be synchronous and atomic on your filesystem and it is important to you that your database survive a power loss or operating system crash that occurs during the truncation operation, then you might consider using a different journaling mode.

On embedded systems with synchronous filesystems, TRUNCATE results in slower behavior than PERSIST. The commit operation is the same speed. But subsequent transactions are slower following a TRUNCATE because it is faster to overwrite existing content than to append to the end of a file. New journal file entries will always be appended following a TRUNCATE but will usually overwrite with PERSIST.

8.0 Testing Atomic Commit Behavior

The developers of SQLite are confident that it is robust in the face of power failures and system crashes because the automatic test procedures do extensive checks on the ability of SQLite to recover from simulated power loss. We call these the "crash tests".

Crash tests in SQLite use a modified VFS that can simulate the kinds of filesystem damage that occur during a power loss or operating system crash. The crash-test VFS can simulate incomplete sector writes, pages filled with garbage data because a write has not completed, and out of order writes, all occurring at varying points during a test scenario. Crash tests execute transactions over and over, varying the time at which a simulated power loss occurs and the properties of the damage inflicted. Each test then reopens the database after the simulated crash and verifies that the transaction either occurred completely or not at all and that the database is in a completely consistent state.

The crash tests in SQLite have discovered a number of very subtle bugs (now fixed) in the recovery mechanism. Some of these bugs were very obscure and unlikely to have been found using only code inspection and analysis techniques. From this experience, the developers of SQLite feel confident that any other database system that does not use a similar crash test system likely contains undetected bugs that will lead to database corruption following a system crash or power failure.

9.0 Things That Can Go Wrong

The atomic commit mechanism in SQLite has proven to be robust, but it can be circumvented by a sufficiently creative adversary or a sufficiently broken operating system implementation. This section describes a few of the ways in which an SQLite database might be corrupted by a power failure or system crash. (See also: How To Corrupt Your Database Files.)

9.1 Broken Locking Implementations

SQLite uses filesystem locks to make sure that only one process and database connection is trying to modify the database at a time. The filesystem locking mechanism is implemented in the VFS layer and is different for every operating system. SQLite depends on this implementation being correct. If something goes wrong and two or more processes are able to write the same database file at the same time, severe damage can result.

We have received reports of implementations of both Windows network filesystems and NFS in which locking was subtly broken. We can not verify these reports, but as locking is difficult to get right on a network filesystem we have no reason to doubt them. You are advised to avoid using SQLite on a network filesystem in the first place, since performance will be slow. But if you must use a network filesystem to store SQLite database files, consider using a secondary locking mechanism to prevent simultaneous writes to the same database even if the native filesystem locking mechanism malfunctions.

The versions of SQLite that come preinstalled on Apple Mac OS X computers contain a version of SQLite that has been extended to use alternative locking strategies that work on all network filesystems that Apple supports. These extensions used by Apple work great as long as all processes are accessing the database file in the same way. Unfortunately, the locking mechanisms do not exclude one another, so if one process is accessing a file using (for example) AFP locking and another process (perhaps on a different machine) is using dot-file locks, the two processes might collide because AFP locks do not exclude dot-file locks or vice versa.

9.2 Incomplete Disk Flushes

SQLite uses the fsync() system call on Unix and the FlushFileBuffers() system call on w32 in order to sync the file system buffers onto disk oxide as shown in step 3.7 and step 3.10. Unfortunately, we have received reports that neither of these interfaces works as advertised on many systems. We hear that FlushFileBuffers() can be completely disabled using registry settings on some Windows versions. Some historical versions of Linux contain versions of fsync() which are no-ops on some filesystems, we are told. Even on systems where FlushFileBuffers() and fsync() are said to be working, often the IDE disk control lies and says that data has reached oxide while it is still held only in the volatile control cache.

On the Mac, you can set this pragma:

PRAGMA fullfsync=ON;

Setting fullfsync on a Mac will guarantee that data really does get pushed out to the disk platter on a flush. But the implementation of fullfsync involves resetting the disk controller. And so not only is it profoundly slow, it also slows down other unrelated disk I/O. So its use is not recommended.

9.3 Partial File Deletions

SQLite assumes that file deletion is an atomic operation from the point of view of a user process. If power fails in the middle of a file deletion, then after power is restored SQLite expects to see either the entire file with all of its original data intact, or it expects not to find the file at all. Transactions may not be atomic on systems that do not work this way.

9.4 Garbage Written Into Files

SQLite database files are ordinary disk files that can be opened and written by ordinary user processes. A rogue process can open an SQLite database and fill it with corrupt data. Corrupt data might also be introduced into an SQLite database by bugs in the operating system or disk controller; especially bugs triggered by a power failure. There is nothing SQLite can do to defend against these kinds of problems.

9.5 Deleting Or Renaming A Hot Journal

If a crash or power loss does occur and a hot journal is left on the disk, it is essential that the original database file and the hot journal remain on disk with their original names until the database file is opened by another SQLite process and rolled back. During recovery at step 4.2 SQLite locates the hot journal by looking for a file in the same directory as the database being opened and whose name is derived from the name of the file being opened. If either the original database file or the hot journal have been moved or renamed, then the hot journal will not be seen and the database will not be rolled back.

We suspect that a common failure mode for SQLite recovery happens like this: A power failure occurs. After power is restored, a well-meaning user or system administrator begins looking around on the disk for damage. They see their database file named "important.data". This file is perhaps familiar to them. But after the crash, there is also a hot journal named "important.data-journal". The user then deletes the hot journal, thinking that they are helping to cleanup the system. We know of no way to prevent this other than user education.

If there are multiple (hard or symbolic) links to a database file, the journal will be created using the name of the link through which the file was opened. If a crash occurs and the database is opened again using a different link, the hot journal will not be located and no rollback will occur.

Sometimes a power failure will cause a filesystem to be corrupted such that recently changed filenames are forgotten and the file is moved into a "/lost+found" directory. When that happens, the hot journal will not be found and recovery will not occur. SQLite tries to prevent this by opening and syncing the directory containing the rollback journal at the same time it syncs the journal file itself. However, the movement of files into /lost+found can be caused by unrelated processes creating unrelated files in the same directory as the main database file. And since this is out from under the control of SQLite, there is nothing that SQLite can do to prevent it. If you are running on a system that is vulnerable to this kind of filesystem namespace corruption (most modern journalling filesystems are immune, we believe) then you might want to consider putting each SQLite database file in its own private subdirectory.

10.0 Future Directions And Conclusion

Every now and then someone discovers a new failure mode for the atomic commit mechanism in SQLite and the developers have to put in a patch. This is happening less and less and the failure modes are becoming more and more obscure. But it would still be foolish to suppose that the atomic commit logic of SQLite is entirely bug-free. The developers are committed to fixing these bugs as quickly as they might be found.

The developers are also on the lookout for new ways to optimize the commit mechanism. The current VFS implementations for Unix (Linux and Mac OS X) and Windows make pessimistic assumptions about the behavior of those systems. After consultation with experts on how these systems work, we might be able to relax some of the assumptions on these systems and allow them to run faster. In particular, we suspect that most modern filesystems exhibit the safe append property and that many of them might support atomic sector writes. But until this is known for certain, SQLite will take the conservative approach and assume the worst.


SQLite Autoincrement

In SQLite, every row of every table has an 64-bit signed integer ROWID. The ROWID for each row is unique among all rows in the same table.

You can access the ROWID of an SQLite table using one the special column names ROWID, _ROWID_, or OID. Except if you declare an ordinary table column to use one of those special names, then the use of that name will refer to the declared column not to the internal ROWID.

If a table contains a column of type INTEGER PRIMARY KEY, then that column becomes an alias for the ROWID. You can then access the ROWID using any of four different names, the original three names described above or the name given to the INTEGER PRIMARY KEY column. All these names are aliases for one another and work equally well in any context.

When a new row is inserted into an SQLite table, the ROWID can either be specified as part of the INSERT statement or it can be assigned automatically by the database engine. To specify a ROWID manually, just include it in the list of values to be inserted. For example:

CREATE TABLE test1(a INT, b TEXT);
INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello');

If no ROWID is specified on the insert, or if the specified ROWID has a value of NULL, then an appropriate ROWID is created automatically. The usual algorithm is to give the newly created row a ROWID that is one larger than the largest ROWID in the table prior to the insert. If the table is initially empty, then a ROWID of 1 is used. If the largest ROWID is equal to the largest possible integer (9223372036854775807) then the database engine starts picking positive candidate ROWIDs at random until it finds one that is not previously used. If no unused ROWID can be found after a reasonable number of attempts, the insert operation fails with an SQLITE_FULL error. If no negative ROWID values are inserted explicitly, then automatically generated ROWID values will always be greater than zero.

The normal ROWID selection algorithm described above will generate monotonically increasing unique ROWIDs as long as you never use the maximum ROWID value and you never delete the entry in the table with the largest ROWID. If you ever delete rows or if you ever create a row with the maximum possible ROWID, then ROWIDs from previously deleted rows might be reused when creating new rows and newly created ROWIDs might not be in strictly ascending order.

The AUTOINCREMENT Keyword

If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly different ROWID selection algorithm is used. The ROWID chosen for the new row is at least one larger than the largest ROWID that has ever before existed in that same table. If the table has never before contained any data, then a ROWID of 1 is used. If the table has previously held a row with the largest possible ROWID, then new INSERTs are not allowed and any attempt to insert a new row will fail with an SQLITE_FULL error.

SQLite keeps track of the largest ROWID that a table has ever held using the special SQLITE_SEQUENCE table. The SQLITE_SEQUENCE table is created and initialized automatically whenever a normal table that contains an AUTOINCREMENT column is created. The content of the SQLITE_SEQUENCE table can be modified using ordinary UPDATE, INSERT, and DELETE statements. But making modifications to this table will likely perturb the AUTOINCREMENT key generation algorithm. Make sure you know what you are doing before you undertake such changes.

The behavior implemented by the AUTOINCREMENT keyword is subtly different from the default behavior. With AUTOINCREMENT, rows with automatically selected ROWIDs are guaranteed to have ROWIDs that have never been used before by the same table in the same database. And the automatically generated ROWIDs are guaranteed to be monotonically increasing. These are important properties in certain applications. But if your application does not need these properties, you should probably stay with the default behavior since the use of AUTOINCREMENT requires additional work to be done as each row is inserted and thus causes INSERTs to run a little slower.

Note that "monotonically increasing" does not imply that the ROWID always increases by exactly one. One is the usual increment. However, if an insert fails due to (for example) a uniqueness constraint, the ROWID of the failed insertion attempt might not be reused on subsequent inserts, resulting in gaps in the ROWID sequence. AUTOINCREMENT guarantees that automatically chosen ROWIDs will be increasing but not that they will be sequential.


SQLite Backup API

Choose any three.
About Sitemap Documentation Download License News Support

Using the SQLite Online Backup API

Historically, backups (copies) of SQLite databases have been created using the following method:

  1. Establish a shared lock on the database file using the SQLite API (i.e. the shell tool).
  2. Copy the database file using an external tool (for example the unix 'cp' utility or the DOS 'copy' command).
  3. Relinquish the shared lock on the database file obtained in step 1.

This procedure works well in many scenarios and is usually very fast. However, this technique has the following shortcomings:

  • Any database clients wishing to write to the database file while a backup is being created must wait until the shared lock is relinquished.
  • It cannot be used to copy data to or from in-memory databases.
  • If a power failure or operating system failure occurs while copying the database file the backup database may be corrupted following system recovery.

The Online Backup API was created to address these concerns. The online backup API allows the contents of one database to be copied into another database, overwriting the original contents of the target database. The copy operation may be done incrementally, in which case the source database does not need to be locked for the duration of the copy, only for the brief periods of time when it is actually being read from. This allows other database users to continue uninterrupted while a backup of an online database is made.

The online backup API is documented here. The remainder of this page contains two C language examples illustrating common uses of the API and discussions thereof. Reading these examples is no substitute for reading the API documentation!

Example 1: Loading and Saving In-Memory Databases

/*
** This function is used to load the contents of a database file on disk
** into the "main" database of open database connection pInMemory, or
** to save the current contents of the database opened by pInMemory into
** a database file on disk. pInMemory is probably an in-memory database,
** but this function will also work fine if it is not.
**
** Parameter zFilename points to a nul-terminated string containing the
** name of the database file on disk to load from or save to. If parameter
** isSave is non-zero, then the contents of the file zFilename are
** overwritten with the contents of the database opened by pInMemory. If
** parameter isSave is zero, then the contents of the database opened by
** pInMemory are replaced by data loaded from the file zFilename.
**
** If the operation is successful, SQLITE_OK is returned. Otherwise, if
** an error occurs, an SQLite error code is returned.
*/
int loadOrSaveDb(sqlite3 *pInMemory, const char *zFilename, int isSave){
  int rc;                   /* Function return code */
  sqlite3 *pFile;           /* Database connection opened on zFilename */
  sqlite3_backup *pBackup;  /* Backup object used to copy data */
  sqlite3 *pTo;             /* Database to copy to (pFile or pInMemory) */
  sqlite3 *pFrom;           /* Database to copy from (pFile or pInMemory) */

  /* Open the database file identified by zFilename. Exit early if this fails
  ** for any reason. */
  rc = sqlite3_open(zFilename, &pFile);
  if( rc==SQLITE_OK ){

    /* If this is a 'load' operation (isSave==0), then data is copied
    ** from the database file just opened to database pInMemory.
    ** Otherwise, if this is a 'save' operation (isSave==1), then data
    ** is copied from pInMemory to pFile.  Set the variables pFrom and
    ** pTo accordingly. */
    pFrom = (isSave ? pInMemory : pFile);
    pTo   = (isSave ? pFile     : pInMemory);

    /* Set up the backup procedure to copy from the "main" database of
    ** connection pFile to the main database of connection pInMemory.
    ** If something goes wrong, pBackup will be set to NULL and an error
    ** code and  message left in connection pTo.
    **
    ** If the backup object is successfully created, call backup_step()
    ** to copy data from pFile to pInMemory. Then call backup_finish()
    ** to release resources associated with the pBackup object.  If an
    ** error occurred, then  an error code and message will be left in
    ** connection pTo. If no error occurred, then the error code belonging
    ** to pTo is set to SQLITE_OK.
    */
    pBackup = sqlite3_backup_init(pTo, "main", pFrom, "main");
    if( pBackup ){
      (void)sqlite3_backup_step(pBackup, -1);
      (void)sqlite3_backup_finish(pBackup);
    }
    rc = sqlite3_errcode(pTo);
  }

  /* Close the database connection opened on database file zFilename
  ** and return the result of this function. */
  (void)sqlite3_close(pFile);
  return rc;
}

The C function to the right demonstrates of one of the simplest, and most common, uses of the backup API: loading and saving the contents of an in-memory database to a file on disk. The backup API is used as follows in this example:

  1. Function sqlite3_backup_init() is called to create an sqlite3_backup object to copy data between the two databases (either from a file and into the in-memory database, or vice-versa).
  2. Function sqlite3_backup_step() is called with a parameter of -1 to copy the entire source database to the destination.
  3. Function sqlite3_backup_finish() is called to clean up resources allocated by sqlite3_backup_init().

Error handling

If an error occurs in any of the three main backup API routines then the error code and message are attached to the destination database connection. Additionally, if sqlite3_backup_step() encounters an error, then the error code is returned by both the sqlite3_backup_step() call itself, and by the subsequent call to sqlite3_backup_finish(). So a call to sqlite3_backup_finish() does not overwrite an error code stored in the destination database connection by sqlite3_backup_step(). This feature is used in the example code to reduce amount of error handling required. The return values of the sqlite3_backup_step() and sqlite3_backup_finish() calls are ignored and the error code indicating the success or failure of the copy operation collected from the destination database connection afterward.

Possible Enhancements

The implementation of this function could be enhanced in at least two ways:

  1. Failing to obtain the lock on database file zFilename (an SQLITE_BUSY error) could be handled, and
  2. Cases where the page-sizes of database pInMemory and zFilename are different could be handled better.

Since database zFilename is a file on disk, then it may be accessed externally by another process. This means that when the call to sqlite3_backup_step() attempts to read from or write data to it, it may fail to obtain the required file lock. If this happens, this implementation will fail, returning SQLITE_BUSY immediately. The solution would be to register a busy-handler callback or timeout with database connection pFile using sqlite3_busy_handler() or sqlite3_busy_timeout() as soon as it is opened. If it fails to obtain a required lock immediately, sqlite3_backup_step() uses any registered busy-handler callback or timeout in the same way as sqlite3_step() or sqlite3_exec() does.

Usually, it does not matter if the page-sizes of the source database and the destination database are different before the contents of the destination are overwritten. The page-size of the destination database is simply changed as part of the backup operation. The exception is if the destination database happens to be an in-memory database. In this case, if the page sizes are not the same at the start of the backup operation, then the operation fails with an SQLITE_READONLY error. Unfortunately, this could occur when loading a database image from a file into an in-memory database using function loadOrSaveDb().

However, if in-memory database pInMemory has just been opened (and is therefore completely empty) before being passed to function loadOrSaveDb(), then it is still possible to change its page size using an SQLite "PRAGMA page_size" command. Function loadOrSaveDb() could detect this case, and attempt to set the page-size of the in-memory database to the page-size of database zFilename before invoking the online backup API functions.

Example 2: Online Backup of a Running Database

/*
** Perform an online backup of database pDb to the database file named
** by zFilename. This function copies 5 database pages from pDb to
** zFilename, then unlocks pDb and sleeps for 250 ms, then repeats the
** process until the entire database is backed up.
**
** The third argument passed to this function must be a pointer to a progress
** function. After each set of 5 pages is backed up, the progress function
** is invoked with two integer parameters: the number of pages left to
** copy, and the total number of pages in the source file. This information
** may be used, for example, to update a GUI progress bar.
**
** While this function is running, another thread may use the database pDb, or
** another process may access the underlying database file via a separate
** connection.
**
** If the backup process is successfully completed, SQLITE_OK is returned.
** Otherwise, if an error occurs, an SQLite error code is returned.
*/
int backupDb(
  sqlite3 *pDb,               /* Database to back up */
  const char *zFilename,      /* Name of file to back up to */
  void(*xProgress)(int, int)  /* Progress function to invoke */
){
  int rc;                     /* Function return code */
  sqlite3 *pFile;             /* Database connection opened on zFilename */
  sqlite3_backup *pBackup;    /* Backup handle used to copy data */

  /* Open the database file identified by zFilename. */
  rc = sqlite3_open(zFilename, &pFile);
  if( rc==SQLITE_OK ){

    /* Open the sqlite3_backup object used to accomplish the transfer */
    pBackup = sqlite3_backup_init(pFile, "main", pDb, "main");
    if( pBackup ){

      /* Each iteration of this loop copies 5 database pages from database
      ** pDb to the backup database. If the return value of backup_step()
      ** indicates that there are still further pages to copy, sleep for
      ** 250 ms before repeating. */
      do {
        rc = sqlite3_backup_step(pBackup, 5);
        xProgress(
            sqlite3_backup_remaining(pBackup),
            sqlite3_backup_pagecount(pBackup)
        );
        if( rc==SQLITE_OK || rc==SQLITE_BUSY || rc==SQLITE_LOCKED ){
          sqlite3_sleep(250);
        }
      } while( rc==SQLITE_OK || rc==SQLITE_BUSY || rc==SQLITE_LOCKED );

      /* Release resources allocated by backup_init(). */
      (void)sqlite3_backup_finish(pBackup);
    }
    rc = sqlite3_errcode(pFile);
  }

  /* Close the database connection opened on database file zFilename
  ** and return the result of this function. */
  (void)sqlite3_close(pFile);
  return rc;
}

The function presented in the previous example copies the entire source database in one call to sqlite3_backup_step(). This requires holding a read-lock on the source database file for the duration of the operation, preventing any other database user from writing to the database. It also holds the mutex associated with database pInMemory throughout the copy, preventing any other thread from using it. The C function in this section, designed to be called by a background thread or process for creating a backup of an online database, avoids these problems using the following approach:

  1. Function sqlite3_backup_init() is called to create an sqlite3_backup object to copy data from database pDb to the backup database file identified by zFilename.
  2. Function sqlite3_backup_step() is called with a parameter of 5 to copy 5 pages of database pDb to the backup database (file zFilename).
  3. If there are still more pages to copy from database pDb, then the function sleeps for 250 milliseconds (using the sqlite3_sleep() utility) and then returns to step 2.
  4. Function sqlite3_backup_finish() is called to clean up resources allocated by sqlite3_backup_init().

File and Database Connection Locking

During the 250 ms sleep in step 3 above, no read-lock is held on the database file and the mutex associated with pDb is not held. This allows other threads to use database connection pDb and other connections to write to the underlying database file.

If another thread or process writes to the source database while this function is sleeping, then SQLite detects this and usually restarts the backup process when sqlite3_backup_step() is next called. There is one exception to this rule: If the source database is not an in-memory database, and the write is performed from within the same process as the backup operation and uses the same database handle (pDb), then the destination database (the one opened using connection pFile) is automatically updated along with the source. The backup process may then be continued after the xSleep() call returns as if nothing had happened.

Whether or not the backup process is restarted as a result of writes to the source database mid-backup, the user can be sure that when the backup operation is completed the backup database contains a consistent and up-to-date snapshot of the original. However:

  • Writes to an in-memory source database, or writes to a file-based source database by an external process or thread using a database connection other than pDb are significantly more expensive than writes made to a file-based source database using pDb (as the entire backup operation must be restarted in the former two cases).
  • If the backup process is restarted frequently enough it may never run to completion and the backupDb() function may never return.

backup_remaining() and backup_pagecount()

The backupDb() function uses the sqlite3_backup_remaining() and sqlite3_backup_pagecount() functions to report its progress via the user-supplied xProgress() callback. Function sqlite3_backup_remaining() returns the number of pages left to copy and sqlite3_backup_pagecount() returns the total number of pages in the source database (in this case the database opened by pDb). So the percentage completion of the process may be calculated as:

Completion = 100% * (pagecount() - remaining()) / pagecount()

The sqlite3_backup_remaining() and sqlite3_backup_pagecount() APIs report values stored by the previous call to sqlite3_backup_step(), they do not actually inspect the source database file. This means that if the source database is written to by another thread or process after the call to sqlite3_backup_step() returns but before the values returned by sqlite3_backup_remaining() and sqlite3_backup_pagecount() are used, the values may be technically incorrect. This is not usually a problem.


Books About SQLite

The Definitive Guide to SQLite (2nd edition, 2010)

Authors: Mike Owens and Grant Allen
Publisher: Apress
Amazon

Outside of the world of enterprise computing, there is one database that enables a huge range of software and hardware to flex relational database capabilities, without the baggage and cost of traditional database management systems. That database is SQLite\u2014an embeddable database with an amazingly small footprint, yet able to handle databases of enormous size. SQLite comes equipped with an array of powerful features available through a host of programming and development environments. It is supported by languages such as C, Java, Perl, PHP, Python, Ruby, TCL, and more.

The Definitive Guide to SQLite, Second Edition is devoted to complete coverage of the latest version of this powerful database. It offers a thorough overview of SQLite\u2019s capabilities and APIs. The book also uses SQLite as the basis for helping newcomers make their first foray into database development. In only a short time you can be writing programs as diverse as a server-side browser plug-in or the next great iPhone or Android application!

Using SQLite (2010)

Author: Jay A. Kreibich
Publisher: O'Reilly Media
O'Reilly

Developers, take note: databases aren't just for the IS group any more. You can build database-backed applications for the desktop, Web, embedded systems, or operating systems without linking to heavy-duty client-server databases such as Oracle and MySQL. This book shows how you to use SQLite, a small and lightweight database that you can build right into your application during development. Applications that handle data have an enormous advantage today, and with SQLite, you'll discover how to develop a database-backed application that remains manageable in size and complexity. This book guides you every step of the way. You'll get a crash course in data modeling, become familiar with SQLite's dialect of the SQL database language, and learn how you to work with SQLite using either a scripting language or a C-based language, such as C# or Objective C.Now, even relatively small and nimble applications can be a part of the data revolution. Using SQLite shows you how.

SQLite 3 - Einstieg in die Datenbankwelt (2010)

Author: Key Droessler
Publisher: Lulu.com
Amazon

Die Datenbanksprache SQL ( Structured Query Language ) wird in Datenbanken zur Definition, Manipulation, Sicherung, aber hauptsaechlich zur Abfrage von Daten aus der Datenbank eingesetzt. Unabhaengig vom Betriebssystem oder aufwendigen, benutzerfreundlichen, graphischen Oberflaechen bleibt die Logik aber immer gleich.SQLite ist eine freie Desktop-Datenbank, sie kostet nichts, ist fuer viele Betriebssysteme verfuegbar, schnell heruntergeladen und installiert und auf das Notwendigste reduziert. Fuer den Einsteiger sind das die besten Voraussetzungen, ohne viel Aufwand schnell in die Welt der Datenbanken und Datenbanksprache reinzuschnuppern.Wer nach den Uebungen aber auf den Geschmack gekommen ist, hat schon den groessten Teil an Datenbanken und SQL gelernt, denn alles Besprochene ist Wissen, welches auch auf jedes andere der vielen Datenbanken grundlegend anwendbar ist. Nun koennen Sie auf die richtig Grossen zugehen, vom grossen Fachbuch bis zum riesigen Datenbanksystem.

Inside Symbian SQL (2010)

Authors: Ivan Litovski & Richard Maynard
Publisher: Wiley
wiley.com

This is the definitive reference book on the Symbian SQL database which is based on SQLite. The authors (both members of the Symbian engineering team responsible for the implementation of the code) show you how to design code and ease migration from an internal and external point of view, plus they reveal the dos and don'ts of writing high-performance database applications. Packed with resources and sample code, this timely book reveals how to design and tune applications that use the Symbian SQL framework to ultimately improve performance.

With its sample code and insider expertise, this text has everything you need to keep you ahead of the curve.

The SQL Guide to SQLite (2009)

Author: Rick F. van der Lans
Publisher: Lulu.com
Amazon

SQLite is a small, fast, embeddable, SQL-based database server. It is easy to install, needs no management, and is open source. This book describes SQLite in detail. With hundreds of examples, plus a proven approach and structure, the book teaches you how to use SQLite efficiently and effectively. It contains a complete description of the SQL dialect as implemented in SQLite version 3.6. The book can be seen as a tutorial and a reference book. Source code for the numerous SQL examples and exercises included in this book can be downloaded from www.r20.nl.

An Introduction to SQLite - 2nd Edition (2009)

Author: Naoki Nishizawa
Publisher: Shoeisha
Amazon.jp

This text is written in fluent Japanese specifically for a Japanese audience. This is the second edition of the book - the first edition was published in 2005.

Inside SQLite (2007)

Author: Sibsankar Haldar
Publisher: O'Reilly Media
O'Reilly

SQLite is a small, zero-configuration, custom-tailored, embeddable, thread-safe, easily maintainable, transaction-oriented, SQL-based, relational database management system. There is no separate install or setup procedure to initialize SQLite before using it. There is no configuration file. SQLite is open source, and is available in the public domain (for more information on open source, visit http://opensource.org). You can download SQLite source code from its homepage http://www.sqlite.org, compile it using your favorite C compiler, and start using the compiled library. SQLite runs on Linux, Windows, Mac OS X, and a few other operating systems. It has been widely used in low-to-medium tier database applications. This Short Cut discusses design principles, engineering trade-offs, implementation issues, and operations of SQLite. It presents a comprehensive description of all important components of the SQLite engine.

SQLite (2004)

Author: Chris Newman
Publisher: Sams
Amazon

SQLite is a small, fast, embeddable database. What makes it popular is the combination of the database engine and interface into a single library as well as the ability to store all the data in a single file. Its functionality lies between MySQL and PostgreSQL, however it is faster than both databases.

In SQLite, author Chris Newman provides a thorough, practical guide to using, administering and programming this up-and-coming database. If you want to learn about SQLite or about its use in conjunction with PHP this is the book for you.


No Title

Choose any three.
About Sitemap Documentation Download License News Support
SQLite B-Tree Module
Table Of Contents
1 Document Overview
1.1 Scope and Purpose
1.2 Document and Requirements Organization
1.3 Glossary
2 Module Requirements
2.1 Functional Requirements
2.1.1 Opening and Closing Connections
2.1.2 New Database Image Configuration
2.1.3 Transaction and Savepoint Functions
2.1.4 Reading From the Database Image
2.1.5 Writing to the Database Image
2.1.6 Page-Cache Configuration Requirements
2.1.7 Multi-User Database Requirements
2.1.8 Backup/Vacuum API Requirements
2.1.9 Integrity Check Requirements
2.2 Other Requirements and Constraints
2.2.1 Caching and Memory Management Requirements
2.2.2 Exception Handling Requirements
2.2.3 Well-Formedness Requirements
3 Module API
3.1 Opening and Closing Connections
3.1.1 sqlite3BtreeOpen
3.1.2 sqlite3BtreeClose
3.2 Database Image Configuration
3.3 Connection Configuration
3.4 Query Interfaces
3.5 Mutex Functions
3.6 Transaction and Savepoint API
3.7 Reading and Traversing the Database Image
3.7.1 sqlite3BtreeMovetoUnpacked
3.7.2 sqlite3BtreeGetMeta
3.8 Modifying the Database Image
3.8.1 sqlite3BtreeCreateTable
3.8.2 sqlite3BtreeDropTable
3.8.3 sqlite3BtreeClearTable
3.8.4 sqlite3BtreeCursorHasMoved
3.8.5 sqlite3BtreePutData
3.8.6 sqlite3BtreeUpdateMeta
3.8.7 sqlite3BtreeDelete
3.8.8 sqlite3BtreeInsert
3.8.9 sqlite3BtreeIncrVacuum
3.9 Advisory B-Tree Locks
3.9.1 sqlite3BtreeLockTable
3.9.2 sqlite3BtreeSchemaLocked
3.10 What do these do?
3.11 APIs not branded sqlite3BtreeXXX()
4 Module Implementation
4.1 Database Image Traversal
4.2 Database Image Manipulation
4.2.1 Creating a B-Tree Structure
4.2.2 Clearing a B-Tree Structure
4.2.3 Deleting a B-Tree Structure
4.2.4 Inserting, Replacing and Deleting B-Tree Entries
4.2.4.1 B-Tree Insert/Replace Entry
4.2.4.2 B-Tree Delete Entry
4.2.5 B-Tree Balancing Algorithm
4.2.5.1 Balance Deeper
4.2.5.2 Balance Shallower
4.2.5.3 Balance Quick
4.2.5.4 Balance Siblings
4.2.6 Page Allocation and Deallocation
4.2.6.1 Moving an overflow-chain to the free-list
4.2.7 Incremental Vacuum Step
4.3 Transactions and Savepoints
5 References

1 Document Overview

1.1 Scope and Purpose

This document provides a description of the functionality of and public interface offered by the SQLite b-tree module. It also, to a certain extent, describes the algorithm and implementation techniques used internally by the module.

  • To make it easier to maintain, test and improve this critical sub-system of the SQLite software library.

  • To facilitate development of compatible backend modules that can be used with other SQLite sub-systems, either for experimental or production purposes.

It is important to note that, even given the second bullet point above, the interfaces and sub-systems described in this document are not stable. They may be changed in any way with each new SQLite release. Any external software development that uses these interfaces must be prepared to adapt to interface refactoring without notice.

1.2 Document and Requirements Organization

Change the following so that those requirements that describe the API are "low-level" requirements.

Requirement ids | Contents
H50**** | Requirement statements specifying the functionality required of the B-Tree module.
H51**** | Requirement statements specifying the API provided by the B-Tree module.
L****** | Requirement statements specifying some details of the internal workings of the B-Tree module.

1.3 Glossary

Balance-Siblings Algorithm | The balance-siblings algorithm is one of four algorithms that may be used used to redistribute data within a b-tree structure after an insert or delete operation that causes a b-tree node to become overfull or underfull. See section 4.2.5.4 for details.
B-Tree Cursor | Define this.
B-Tree Database Connection | A B-Tree database connection is a single client connection to an in-memory page cache, through which a single temporary or persistent database may be accessed. This term is used throughout this document to avoid confusing such connections with SQL level SQLite client connections, which are sometime simply termed "database connections".
Lazy-write cache | Define this.
Overflow Cell | Define this.
Page cache | Define this.
Persistent database | Define this.
Read-through cache | Define this.
Shared-cache mode | Define this.
SQLite Error Code | Define this.
Temporary database | Define this.

2 Module Requirements

The SQLite B-Tree module, the software module described by this document, is designed to query and modify a database stored using the database image format described in [1]. Database images may exist only in volatile main-memory (in-memory databases), or may be stored persistently within the file-system (also described in [1]). Or, a database image may be stored primarily in main-memory with the file-system used as secondary storage if the database image grows too large. Database images stored only in main-memory, and those stored primarily in main-memory with the file-system used only to provide secondary storage space are known collectively as temporary databases. Database images stored persistently in the file-system are termed persistent databases.

This module implements an in-memory page cache to manage database image content. The size of the pages managed by the cache are the same as the page-size of the database image. When operating on a persistent database, the cache operates as a read-through, lazy-write cache. When committing a database transaction, the user explicitly directs the cache to flush all dirty pages through to persistent storage. A single in-memory page cache used to access the content of a persistent database may support multiple logical client connections. Some brief explanation of what this means. And maybe a pointer to the "Multi-User Database Requirements" section.

When operating on a temporary database, there may only be one client for each page cache. Depending on the SQLite configuration, either the database or journal file, or both, may be omitted from the system.

Figure 1 - Role of Page Cache

Figure 1 depicts...

Roughly what is encapsulated by the module.

2.1 Functional Requirements

This section contains requirements describing the functionality required from the B-Tree module.

Figure out where integrity-check goes.

2.1.1 Opening and Closing Connections

The B-Tree module provides an interface to open new b-tree database connections.

The B-Tree module shall provide an interface to open a connection to either a named persistent database file, or an anonymous temporary database. (C: * H51001)

When opening a persistent database, the B-Tree module shall allow the user to specify that the connection be opened for read-only access.

When opening a persistent database, the B-Tree module shall allow the user to specify that the connection only be opened if the specified file exists.

If SQLite is configured to run in shared-cache mode, and a connection is opened to a persistent database file for which there exists already a page-cache within the current processes address space, then the connection opened shall be a connection to the existing page-cache.

If a new B-Tree database connection is opened and requirement H50040 does not apply, then a new page-cache shall be created within the processes address space. The opened connection shall be a connection to the new page-cache.

The B-Tree module also provides an interface to close existing b-tree database connections.

The B-Tree module shall provide an interface to close a B-Tree database connection.

If a B-Tree database connection is closed and this causes the associated page-cache to have zero connections to it, then the page-cache shall be closed and all associated resources released.

2.1.2 New Database Image Configuration

The following requirements describe database configuration options that are only applicable to new database images. For the purposes of the following requirements, a "new database image" is defined as one that is zero pages in size.

The B-Tree module shall provide an interface to configure the page-size of a new database image.

The B-Tree module shall provide an interface to configure whether or not a new database image is auto-vacuum capable.

2.1.3 Transaction and Savepoint Functions

This needs a lot of work...

All read and write operations performed on a database image via the B-Tree module interfaces occur within the context of a read or write transaction. Something about the ACID nature of transactions and how this applies to read and write transactions)

The B-Tree module shall provide an interface to open (start) a read-only transaction.

The B-Tree module shall provide an interface to close (finish) a read-only transaction.

Read/write:

The B-Tree module shall provide an interface to open a read/write transaction or to upgrade from a read-only transaction to a read/write transaction.

The B-Tree module shall provide an interface to commit a read/write transaction.

The B-Tree module shall provide an interface to rollback a read/write transaction.

Multi-file transaction support.

Transaction state query:

The B-Tree module shall provide an interface to query a B-Tree database connection to determine if there is an open transaction, and if so if the open transaction is read-only or read/write.

Savepoints:

Define "savepoint transactions" and fix the following requirements.

The B-Tree module shall provide an interface to open savepoint transactions.

The B-Tree module shall provide an interface to commit savepoint transactions.

The B-Tree module shall provide an interface to rollback savepoint transactions.

2.1.4 Reading From the Database Image

The B-Tree module allows the user to read a subset of the fields from the database image header. Each such field is stored in the header as a 4-byte unsigned big-endian integer. A complete description of each field and its interpretation may be found in [1].

The B-Tree module shall provide an interface to read the value of any of the 4-byte unsigned big-endian integer fields beginning at byte offset 36 of the database image. (C: H51015 H51016 H51017)

In other words, the database image header fields that may be read via this module are:

  • The number of free pages in the database image,
  • The database image schema version (schema cookie).
  • The database image schema layer file-format.
  • The default page-cache size.
  • The "auto-vacuum last root-page" field.
  • The database image text-encoding field.
  • The database image user-cookie value.
  • The database image incremental-vacuum flag.

With the exception of the database image header fields described above, all data is read from the database image using B-Tree cursors. A B-Tree cursor is a control structure for traversing the contents of a single table or index b-tree structure within a database image. As well as "forward" and "back" operations, a B-Tree cursor supports fast seeking to a table entry identified by key value, or to the first or last entry in the table.

When a B-Tree cursor is created, the specific table or index b-tree that it is used to traverse is identified by the database image page number of its root page. Since the root-page of the schema table is always page 1, and the contents of the schema table includes the root page numbers of all other index and table b-tree structures in the database image, it is possible for the application to determine the set of valid root-page numbers by first traversing the schema table.

The B-Tree module shall provide an interface to open a B-Tree cursor on any table or index b-tree within the database image, given its root page number.

The B-Tree module shall provide an interface to close a B-Tree cursor.

The B-Tree module shall provide an interface to move an open B-Tree cursor to the entry associated with the largest key in the open b-tree structure.

The B-Tree module shall provide an interface to move an open B-Tree cursor to the entry associated with the smallest key in the open b-tree structure.

The B-Tree module shall provide an interface to move an open B-Tree cursor that currently points at a valid b-tree entry to the next entry in the b-tree structure, sorted in order of key value, if any.

The B-Tree module shall provide an interface to move an open B-Tree cursor that currently points at a valid b-tree entry to the previous entry in the b-tree structure, sorted in order of key value, if any.

The B-Tree module shall provide an interface to retrieve the key value associated with the b-tree structure entry that a B-Tree cursor is pointing to, if any.

The B-Tree module shall provide an interface to retrieve the blob of data (the database record) associated with the b-tree structure entry that a B-Tree cursor open on a table b-tree is pointing to, if any.

The B-Tree module shall provide an interface to return the number of entries currently stored in the b-tree structure that a B-Tree cursor is open on.

As well as traversing a b-tree structure using the operations enumerated by the above requirements, it is also possible to use a cursor to search a b-tree structure for a specified key value. If the key value can be found, the cursor is left pointing at the entry with the specified key value. Otherwise, the cursor is left pointing at either the entry with the largest key that is smaller than the specified key, or to the entry with the smallest key that is larger than the specified key. For table b-tree structures, where the key values are 64-bit integers, the definition of smaller, larger and equal to is straightforward. For index b-tree structures, where the key values are database records, the manner in which key values must be compared is more complicated. Refer to [1] for a full explanation.

There is a specific section in [1] devoted to record sort order in index b-tree structures. There needs to be some way to point to it. Or, better, to the requirement or range of requirements.

Maybe a system that automatically links text like H30100 to the corresponding requirement. Within a document if it can find it, or a summary page (hlreq.html for example).

Given a key value, the B-Tree module shall provide an interface to move a B-Tree cursor open on a b-tree structure to the B-Tree entry with the matching key value, if such an entry exists.

If the interface required by H50119 is used to search for a key value that is not present in the b-tree structure and the b-tree is not empty, the cursor shall be moved to an existing entry that would be adjacent to a hypothetical entry with the specified key value.

The interface required by H50119 shall provide an indication to the caller as to whether the cursor is left pointing at an entry with a key value that is smaller, larger or equal to the requested value, or if it is pointing to no entry at all (because the b-tree structure is empty).

Does it depend on the structure of the tree whether the cursor is left pointing to a smaller or larger entry after a failed search? Or is it possible to determine which it will be based only on the set of keys stored in the tree?

As well as the standard search operation described by the above requirements, cursors open on index b-tree structures are required to support several variants, as follows:

  • Ignore rowid search mode. The final value in a database record used as an index-btree key is always an integer "rowid" field. A search in this mode proceeds as if each key in the b-tree was missing this field.
  • Increment key mode.
  • Prefix match mode.
  • Prefix search mode.

Finish the bullet points above and add HLR for each search mode.

More than one cursor can be open on a single b-tree structure at one time. It is also possible for a write-cursor to modify the contents of a b-tree structure while other cursors are open on it. The b-tree module does not include any type of row-locking mechanism. It is possible for a write-cursor to be used to delete an entry from a b-tree structure even if there are one or more other cursors currently pointing to the entry being deleted.

Requirements to do with how the above is handled. Traceability to sqlite3BtreeCursorHasMoved is required.

2.1.5 Writing to the Database Image

The B-Tree module allows the user to write values to a subset of the fields from the database image header. The set of writable fields is the same as the set of fields enumerated in section 2.1.4 that the B-Tree module is required to provide read access to by requirement H50109.

The B-Tree module shall provide an interface to write a value to any of the 4-byte unsigned big-endian integer fields beginning at byte offset 36 of the database image.

The B-Tree module also supports operations to create new b-tree structures within the database image. Existing b-tree structures may be deleted from the database image entirely, or their entire contents may be deleted, leaving an empty b-tree structure.

The B-Tree module shall provide an interface to create a new index or table b-tree structures within the database image. The interface shall automatically assign a root-page to the new b-tree structure.

The B-Tree module shall provide an interface to remove an existing index or table b-tree structure from the database image, given the root page number of the b-tree to remove.

The B-Tree module shall provide an interface to remove all entries from (delete the contents of) an index or table b-tree, given the root page number of the b-tree to empty.

As one would expect, the B-Tree module also provides an interface to insert and delete entries from b-tree structures. These operations are performed using a B-Tree write cursor, a special type of B-Tree cursor (see section 2.1.4).

When opening a B-Tree cursor using the interface required by H50110, it shall be possible to specify that the new cursor be a write cursor, or an ordinary read-only cursor.

The B-Tree module shall provide an interface that allows the user to delete the b-tree entry that a write cursor points to, if any. (C: L50013)

The B-Tree module shall provide an interface to insert new entries into a table or index B-Tree, given a write cursor open on the table or index b-tree the new entry is to be inserted into. (C: L50001 L50002 L50003 L50004 L50012)

Incremental vacuum step.

2.1.6 Page-Cache Configuration Requirements

A page-cache has a number of operational parameters that may be configured at run-time via an open b-tree database connection. Note that even though the interfaces provided by this module allow these parameters to be set via a b-tree database connection, they are properties of the page-cache, not the b-tree database connection. In situations where more than one b-tree database connection is connected to a single page-cache, writes made via one b-tree database connection may overwrite the values set by another. The following table summarizes the available configuration parameters.

Parameter | Description | Requirements
Locking-mode | This! | H50138, H50139, H50140
Journal-mode | This! | H50141, H50142, H50143, H50144, H50145, H50146
Journal-file size limit | The journal-file size limit parameter may be set to any integer value within the range of a 64-bit signed integer. Any negative values is interpreted as "no limit". Otherwise, if the journal-file size limit is set to zero or a positive number, it represents an upper limit on the size of the journal file in bytes. If the application executes a database write operation that would normally cause the journal file to grow larger than this configured limit, the operation fails and an error is returned to the user. The default value of this parameter is -1 (no limit). | H50147, H50148, H50149
Database-file size limit | The database-image size limit parameter may be set to any integer value greater than zero within the range of a 32-bit signed integer. The configured value represents an upper limit on the size of the database image in pages. If the application executes a database write operation that would normally cause the database image to grow larger than this configured limit, the operation fails and an error is returned to the user. | H50150, H50151, H50152
Cache size | The cache-size parameter may be set to any integer value. How it affects operation depends on the specific P-Cache implementation used by the page-cache. Refer to details for the behaviour of the built-in default P-Cache. | H50153
Safety level | The safety-level parameter may be set to "none", "normal" or "full". Where will the effect of this defined/required? | H50154, H50155

The B-Tree module shall provide an interface allowing the application to set the locking-mode of a page-cache to either "normal" or "exclusive", given an open b-tree database connection to that page-cache.

If the locking-mode of a page-cache is set to "normal" when a read/write or read-only transaction is ended, any locks held on the database file-system representation by the page-cache shall be relinquished.

If the locking-mode of a page-cache is set to "exclusive" when a read/write or read-only transaction is ended, any locks held on the database file-system representation by the page-cache shall be retained.

And if a read/write transaction is downgraded to a read-only transaction? This scenario should also be dealt with in section 2.1.3.

The B-Tree module shall provide an interface allowing the application to set the journal-mode of a page-cache to one of "off", "memory", "delete", "persist", or "truncate", given an open b-tree database connection to that page-cache.

If the journal-mode of a page-cache is set to "off" when a read/write transaction is opened, then the transaction shall use no journal file.

If the journal-mode of a page-cache is set to "memory" when a read/write transaction is opened, then instead of using the journal file located in the file-system, journal-file data shall be stored in main-memory.

If the journal-mode of a page-cache is set to "delete" when a read/write transaction is opened, then any journal file used by the transaction shall be deleted at the conclusion of the transaction.

If the journal-mode of a page-cache is set to "truncate" when a read/write transaction is opened, then any journal file used by the transaction shall be truncated to zero bytes in size at the conclusion of the transaction.

If the journal-mode of a page-cache is set to "persist" when a read/write transaction is opened, then any journal file used by the transaction shall remain in the file-system at the conclusion of the transaction.

The difference in functionality provided by "off", "memory" and the 3 modes that use a real journal file should also feature in 2.1.3.

The B-Tree module shall provide an interface to set the value of the journal-file size limit configuration parameter of a page-cache, given an open b-tree database connection to that page-cache.

The default value assigned to the journal-file size limit configuration of a page-cache shall be -1.

If the journal-file size limit parameter is set to a non-negative value, and the user executes a write operation that would otherwise require the journal file to be extended to a size greater than the configured value in bytes, then the operation shall fail and an error be returned to the user.

The B-Tree module shall provide an interface to set the value of the database-image size limit configuration parameter of a page-cache, given an open b-tree database connection to that page-cache.

The default value assigned to the database-image size limit configuration of a page-cache shall be the value of the compile time symbol SQLITE_MAX_PAGE_COUNT (1073741823 by default).

If the database-image size limit parameter is set to a non-negative value, and the user executes a write operation that would otherwise require the journal file to be extended to a size greater than the configured value in bytes, then the operation shall fail and an error be returned to the user.

The B-Tree module shall provide an interface to set the value of the cache-size configuration parameter of a page-cache, given an open b-tree database connection to that page-cache.

See section 2.2.1 for a description of and requirements specifying how the value of the cache-size parameter affects the operation of a page-cache. Check this reference is relevant after it is written. Refer to a specific requirement if possible too.

The B-Tree module shall provide an interface allowing the application to set the safety-level of a page-cache to one of "off", "normal" or "full", given an open b-tree database connection to that page-cache.

The default value assigned to the safety-level configuration parameter of a page-cache shall be "full".

Description of what the safety-level actually does. Or pointer to where a description and requirements can be found (transactions section?).

Interface to set the codec function (encryption).

The busy-handler. Where exactly does this come in? Transactions and savepoints section?

The six page-cache operational parameters listed above may also be queried. The following requirements specify the required query interfaces.

The B-Tree module shall provide an interface to query the current locking-mode of a page-cache, given an open b-tree database connection to that page-cache.

The B-Tree module shall provide an interface to query the current journal-mode of a page-cache, given an open b-tree database connection to that page-cache.

The B-Tree module shall provide an interface to query the current journal file size-limit of a page-cache, given an open b-tree database connection to that page-cache.

The B-Tree module shall provide an interface to query the current database file size-limit of a page-cache, given an open b-tree database connection to that page-cache.

The B-Tree module shall provide an interface to query the current cache-size of a page-cache, given an open b-tree database connection to that page-cache.

The B-Tree module shall provide an interface to query the current safety-level of a page-cache, given an open b-tree database connection to that page-cache.

It is also possible to interrogate a b-tree database handle to determine if it was opened on a temporary or persistent database. An b-tree database handle opened on a persistent database may be queried for the name of (full-path to) either the database or journal file associated with the open database.

The B-Tree module shall provide an interface to query an open b-tree database handle to determine if the underlying database is a persistent database or a temporary database.

The B-Tree module shall provide an interface allowing the application to query a b-tree database connection open on a persistent database for the name of the underlying database file within the file-system.

The B-Tree module shall provide an interface allowing the application to query a b-tree database connection open on a persistent database for the name of the underlying journal file within the file-system.

2.1.7 Multi-User Database Requirements

The b-tree module shall provide an interface allowing database clients to acquire advisory read (shared) or write (exclusive) locks on a specific b-tree structure within the database.

  • Lock on schema memory object.
  • Locks on b-tree tables.
  • "Unlock notify" feature.
  • Mutexes/thread-safety features.

The b-tree module preventing deadlock (by always grabbing mutexes in order of BtShared pointer) should be required here.

2.1.8 Backup/Vacuum API Requirements

  • Callbacks for backup module.
  • Page read/write APIs for backup module.

2.1.9 Integrity Check Requirements

  • Callbacks for backup module.
  • Page read/write APIs for backup module.

2.2 Other Requirements and Constraints

2.2.1 Caching and Memory Management Requirements

  • Memory allocation related features (pcache, scratch memory, other...).
  • Default pcache implementation (sqlite3_release_memory()).
  • Schema memory object allocation (destructor registration).

2.2.2 Exception Handling Requirements

System failure. Do not corrupt the database image.

Three kinds of exception:

  • IO Error.
  • Malloc request failure.
  • Database image corruption.

2.2.3 Well-Formedness Requirements

  • Identify the subset of file-format well-formedness requirements that this module is responsible for implementing.
  • Define how the module should respond to corrupt database files: don't crash, return SQLITE_CORRUPT as early as is practical. Should it also put the b-tree into a permanent error state?

3 Module API

Description of the interface in btree.h. Also other interfaces accessed by external modules. Including release_memory() and those pager interfaces that are accessed directly by other modules. All of these requirements will be descended/derived from requirements in the previous sections. Some of the text could/should be pulled in from btree.h.

The name of sqlite3BtreeBeginStmt() should probably change to sqlite3BtreeOpenSavepoint(). Matches the pager layer and is a more accurate description of the function.

There are only a few places in which the pager object is used directly, always to call some trivial get/set configuration function. These should be replaced somehow with sqlite3BtreeXXX() APIs. Also, the current approach is probably Ok, but worth looking it over for thread-safety issues.

It would be easier to write up if the dependency between the B-Tree layer and the sqlite3 structure did not exist. At present, it is used for:
* The unlock-notify feature (arguments to sqlite3ConnectionBlocked() are database handles),
* Accessing the SQLITE_ReadUncommitted flag,
* Invoking the busy-handler callback,
* During sqlite3BtreeOpen(), to find the VFS to use,
* Accessing the SQLITE_SharedCache flag (for setting it),
* To check the same B-Tree is not attached more than once in shared-cache mode,
* To link the B-Tree into the pointer-order list of shared-cache b-trees used by the same handle (used for mutexes).
* To determine if an in-memory sub-journal should be used.
* To know how many savepoints are open in BtreeBeginTrans().
* Many, many times to assert() that the db mutex is held when the b-tree layer is accessed..

3.1 Opening and Closing Connections

This section describes the API offered by the B-Tree module to other SQLite sub-systems to open and close B-Tree database connections.

typedef struct Btree Btree;

A B-Tree database connection is accessed by other SQLite sub-systems using an opaque handle, modelled in C code using the type "Btree*".

3.1.1 sqlite3BtreeOpen

int sqlite3BtreeOpen(
  sqlite3_vfs *pVfs,       /* VFS to use with this b-tree */
  const char *zFilename,   /* Name of database file to open */
  sqlite3 *db,             /* Associated database connection */
  Btree **ppBtree,         /* Return open Btree* here */
  int flags,               /* Flags */
  int vfsFlags             /* Flags passed through to VFS open */
);

If successful, a call to the sqlite3BtreeOpen function shall return SQLITE_OK and set the value of *ppBtree to contain a new B-Tree database connection handle. (P: H50010)

If unsuccessful, a call to the sqlite3BtreeOpen function shall return an SQLite error code other than SQLITE_OK indicating the reason for the failure. The value of *ppBtree shall not be modified in this case.

If the zFilename parameter to a call to sqlite3BtreeOpen is NULL or a pointer to a buffer of which the first byte is a nul (0x00), then sqlite3BtreeOpen shall attempt to open a connection to a temporary database.

If the zFilename parameter to a call to sqlite3BtreeOpen is a pointer to a buffer containing a nul-terminated UTF-8 encoded string, sqlite3BtreeOpen shall attempt to open a connection to a persistent database.

The combination of the above two requirements implies that if the zFilename argument passed to sqlite3BtreeOpen is other than a NULL pointer or a pointer to a nul-terminated string, the type of or filename of the database that sqlite3BtreeOpen attempts to open a connection to are undefined.

Valid values for the flags argument to the sqlite3BtreeOpen function consist of the bitwise OR of zero or more of the following symbols.

#define BTREE_OMIT_JOURNAL  1  /* Do not create or use a rollback journal */
#define BTREE_NO_READLOCK   2  /* Omit readlocks on readonly files */

If the BTREE_OMIT_JOURNAL bit is set in the flags parameter passed to a successful call to sqlite3BtreeOpen to open a temporary database, then the page-cache created as a result shall not open or use a journal file for any purpose.

When opening a connection to a persistent database, the value of the BTREE_OMIT_JOURNAL bit in the flags parameter is ignored by sqlite3BtreeOpen.

If the BTREE_NO_READLOCK bit is set in the flags parameter passed to a successful call to sqlite3BtreeOpen to open a persistent database and a new page-cache is created as a result of the call, then the new page-cache shall only lock the database file-system representation when writing to it.

When opening a connection to a temporary database, the value of the BTREE_NO_READLOCK bit in the flags parameter is ignored, as temporary databases are never locked for either reading or writing (reference to some requirement for this statement.). Whether or not a new page-cache is created when a connection to a persistent database is opened is governed by requirements H50040 and H50050.

If the sqlite3BtreeOpen function is called to open a connection to a persistent database, and the call causes a new page-cache to be created, when opening the database file using the VFS interface xOpen method the 4th parameter passed to xOpen (flags) shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen.

If the sqlite3BtreeOpen function is called to open a connection to a temporary database, if and when a temporary file is opened to use as secondary storage using the VFS interface xOpen method the 4th parameter passed to xOpen (flags) shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen with the SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_EXCLUSIVE and SQLITE_OPEN_DELETEONCLOSE bits also set.

Requirements explaining how the db parameter to sqlite3BtreeOpen is used. Must be there for something.

3.1.2 sqlite3BtreeClose

int sqlite3BtreeClose(Btree*);

A call to the sqlite3BtreeClose function with a valid b-tree database connection handle passed as the only argument shall invalidate the handle, close the b-tree database connection and release all associated resources.

If a call to sqlite3BtreeClose is made with a value that is not a valid b-tree database connection handle passed as the only argument, the results are undefined.

If a call to sqlite3BtreeClose is made to close a b-tree database connection while there exist open B-Tree cursors that were opened using the specified b-tree database connection, they shall be closed automatically from within sqlite3BtreeClose, just as if their handles were passed to sqlite3BtreeCloseCursor.

See also requirement H50070.

3.2 Database Image Configuration

This category doesn't work all that well. These APIs are used for other things too (i.e. switching to incremental-vacuum mode).

#define BTREE_AUTOVACUUM_NONE 0        /* Do not do auto-vacuum */
#define BTREE_AUTOVACUUM_FULL 1        /* Do full auto-vacuum */
#define BTREE_AUTOVACUUM_INCR 2        /* Incremental vacuum */
int sqlite3BtreeSetAutoVacuum(Btree *, int);
int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix);

Queries:

int sqlite3BtreeGetPageSize(Btree*);
int sqlite3BtreeGetReserve(Btree*);
int sqlite3BtreeGetAutoVacuum(Btree *);

3.3 Connection Configuration

int sqlite3BtreeSetCacheSize(Btree*,int);
int sqlite3BtreeSetSafetyLevel(Btree*,int,int,int);
int sqlite3BtreeMaxPageCount(Btree*,int);

And functions to query the current configuration:

int sqlite3BtreeSyncDisabled(Btree*);

3.4 Query Interfaces

const char *sqlite3BtreeGetFilename(Btree *);

A call to the sqlite3BtreeGetFilename function with a valid B-Tree database connection handle opened on a persistent database as the first argument shall return a pointer to a buffer containing the full-path of the database file formatted as a nul-terminated, UTF-8 string.

A call to the sqlite3BtreeGetFilename function with a valid B-Tree database connection handle opened on a temporary database as the first argument shall return a pointer to a buffer to a nul-terminated string zero bytes in length (i.e. the first byte of the buffer shall be 0x00).

const char *sqlite3BtreeGetJournalname(Btree *);

A call to the sqlite3BtreeGetJournalname function with a valid B-Tree database connection handle opened on a persistent database as the first argument shall return a pointer to a buffer containing the full-path of the journal file formatted as a nul-terminated, UTF-8 string.

A call to the sqlite3BtreeGetJournalname function with a valid B-Tree database connection handle opened on a temporary database as the first argument shall return a pointer to a buffer to a nul-terminated string zero bytes in length (i.e. the first byte of the buffer shall be 0x00).

Requirement H51013 holds true even if the B-Tree database connection is configured to use an in-memory journal file or no journal file at all (ref requirements). In these cases the buffer returned contains the full-path of the journal file that would be used if the connection were configured to use a journal file.

3.5 Mutex Functions

void sqlite3BtreeEnter(Btree*);
void sqlite3BtreeEnterAll(sqlite3*);
void sqlite3BtreeLeave(Btree*);
void sqlite3BtreeEnterCursor(BtCursor*);
void sqlite3BtreeLeaveCursor(BtCursor*);
void sqlite3BtreeLeaveAll(sqlite3*);

3.6 Transaction and Savepoint API

int sqlite3BtreeBeginTrans(Btree*,int);
int sqlite3BtreeCommitPhaseOne(Btree*, const char *zMaster);
int sqlite3BtreeCommitPhaseTwo(Btree*, int);
int sqlite3BtreeCommit(Btree*);
int sqlite3BtreeRollback(Btree*);

int sqlite3BtreeBeginStmt(Btree*,int);
int sqlite3BtreeSavepoint(Btree *, int, int);

int sqlite3BtreeIsInTrans(Btree*);
int sqlite3BtreeIsInReadTrans(Btree*);
int sqlite3BtreeIsInBackup(Btree*);

3.7 Reading and Traversing the Database Image

    sqlite3BtreeMoveto is never called from outside of the b-tree layer. It
        could/should be removed from the API.

    The "bias" argument to sqlite3BtreeMovetoUnpacked is only ever true
        when it is called from within sqlite3BtreeInsert. This argument could/should
        also be removed from the API, if only to make it simpler to describe.

typedef struct BtCursor BtCursor;

int sqlite3BtreeCursor(
  Btree*,                              /* BTree containing table to open */
  int iTable,                          /* Index of root page */
  int wrFlag,                          /* 1 for writing.  0 for read-only */
  struct KeyInfo*,                     /* First argument to compare function */
  BtCursor *pCursor                    /* Space to write cursor structure */
);
int sqlite3BtreeCursorSize(void);

int sqlite3BtreeCloseCursor(BtCursor*);
void sqlite3BtreeClearCursor(BtCursor *);

int sqlite3BtreeFirst(BtCursor*, int *pRes);
int sqlite3BtreeLast(BtCursor*, int *pRes);
int sqlite3BtreeNext(BtCursor*, int *pRes);
int sqlite3BtreePrevious(BtCursor*, int *pRes);
int sqlite3BtreeEof(BtCursor*);

int sqlite3BtreeKeySize(BtCursor*, i64 *pSize);
int sqlite3BtreeKey(BtCursor*, u32 offset, u32 amt, void*);
const void *sqlite3BtreeKeyFetch(BtCursor*, int *pAmt);
const void *sqlite3BtreeDataFetch(BtCursor*, int *pAmt);
int sqlite3BtreeDataSize(BtCursor*, u32 *pSize);
int sqlite3BtreeData(BtCursor*, u32 offset, u32 amt, void*);

int sqlite3BtreeCount(BtCursor *, i64 *);

3.7.1 sqlite3BtreeMovetoUnpacked

        The sqlite3BtreeMovetoUnpacked function is used to

int sqlite3BtreeMovetoUnpacked(
  BtCursor*,
  UnpackedRecord *pUnKey,
  i64 intKey,
  int bias,
  int *pRes
);

        The following requirements specify exactly how a b-tree cursor is to be moved
        by a successful call to sqlite3BtreeMovetoUnpacked.

If a call is made to sqlite3BtreeMovetoUnpacked specifying a key value for
which there exists an entry with a matching key value in the b-tree structure,
the b-tree cursor shall be moved to point to this entry. In this case *pRes
(the value of the "int" variable pointed to by the pointer passed as the
fifth parameter to sqlite3BtreeMovetoUnpacked) shall be set to 0 before
returning.

If a call is made to sqlite3BtreeMovetoUnpacked specifying a key value for
which there does not exist an entry with a matching key value in the b-tree
structure, the b-tree cursor shall be moved to point to an entry located
on the leaf page that would contain the requested entry, were it present.

If the condition specified in L50009 is met and the b-tree structure
contains one or more entries (is not empty), the b-tree cursor shall be left
pointing to an entry that would lie adjacent (immediately before or after in
order by key) to the requested entry on the leaf page, were it present.

If the condition specified in L50009 is met and the b-tree cursor is left
pointing to an entry with a smaller key than that requested, or the cursor
is left pointing a no entry at all because the b-tree structure is completely
empty, *pRes (the value of the "int" variable pointed to by the pointer passed
as the fifth parameter to sqlite3BtreeMovetoUnpacked) shall be set to -1.
Otherwise, if the b-tree cursor is left pointing to an entry with a larger key
than that requested, *pRes shall be set to 1.

    Not clear how to deal with these. Define an external module to
    encapsulate these and define sorting order etc.? That's tricky as things are
    because the UnpackedRecord.flags field defines the "search mode" used
        by sqlite3BtreeMovetoUnpacked.

typedef struct KeyInfo KeyInfo;
struct KeyInfo {
  sqlite3 *db;        /* The database connection */
  u8 enc;             /* Text encoding - one of the SQLITE_UTF* values */
  u16 nField;         /* Number of entries in aColl}; hd_resolve_one {}; hd_puts { */
  u8 *aSortOrder;     /* Sort order for each column.  May be NULL */
  CollSeq *aColl}; hd_resolve_one {1}; hd_puts {;  /* Collating sequence for each term of the key */
};

typedef struct UnpackedRecord UnpackedRecord;
struct UnpackedRecord {
  KeyInfo *pKeyInfo;  /* Collation and sort-order information */
  u16 nField;         /* Number of entries in apMem}; hd_resolve_one {}; hd_puts { */
  u16 flags;          /* Boolean settings.  UNPACKED_... below */
  i64 rowid;          /* Used by UNPACKED_PREFIX_SEARCH */
  Mem *aMem;          /* Values */
};

3.7.2 sqlite3BtreeGetMeta

    The sqlite3BtreeGetMeta interface may be used to retrieve the current
        value of certain fields from the database image header.

void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue);

If the first parameter is a b-tree database connection handle with an open
read-only or read-write transaction, and the second parameter is an integer
between 0 and 7 inclusive, and the database image consists of zero pages,
a call to the sqlite3BtreeGetMeta function shall set the value of *pValue to
zero. (P: H50109)

If the first parameter is a b-tree database connection handle with an open
read-only or read-write transaction, and the second parameter is an integer
between 0 and 7 inclusive, and the database image consists of one or more
pages, a call to the sqlite3BtreeGetMeta function shall set the value of
*pValue to the current value of the specified 32-bit unsigned integer in the
database image database header. (P: H50109)

        The two requirements above imply that if sqlite3BtreeGetMeta is called with
        anything other than a b-tree database connection handle with an open read-only
        or read-write transaction as the first argument, or with anything other than
        an integer between 0 and 7 (inclusive) as the second, the results are undefined.

#define BTREE_FREE_PAGE_COUNT     0
#define BTREE_SCHEMA_VERSION      1
#define BTREE_FILE_FORMAT         2
#define BTREE_DEFAULT_CACHE_SIZE  3
#define BTREE_LARGEST_ROOT_PAGE   4
#define BTREE_TEXT_ENCODING       5
#define BTREE_USER_VERSION        6
#define BTREE_INCR_VACUUM         7

The database header field read from the database image by a call to
sqlite3BtreeGetMeta in the situation specified by H51016 shall be the 32-bit
unsigned integer header field stored at byte offset (36 + 4 * idx) of the
database header, where idx is the value of the second parameter passed to
sqlite3BtreeGetMeta. (P: H50109)

3.8 Modifying the Database Image

3.8.1 sqlite3BtreeCreateTable

int sqlite3BtreeCreateTable(Btree*, int*, int flags);

** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set.

3.8.2 sqlite3BtreeDropTable

int sqlite3BtreeDropTable(Btree*, int, int*);

3.8.3 sqlite3BtreeClearTable

int sqlite3BtreeClearTable(Btree*, int, int*);

3.8.4 sqlite3BtreeCursorHasMoved

int sqlite3BtreeCursorHasMoved(BtCursor*, int*);

3.8.5 sqlite3BtreePutData

int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*);

3.8.6 sqlite3BtreeUpdateMeta

int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value);

3.8.7 sqlite3BtreeDelete

int sqlite3BtreeDelete(BtCursor*);

A successful call to the sqlite3BtreeDelete function made with a read/write
b-tree cursor passed as the first argument shall remove the entry pointed to by
the b-tree cursor from the b-tree structure. (P: H50127)

        Effect of a delete operation on other cursors that are pointing to the
        deleted b-tree entry.

        Malloc and IO error handling. Same as for sqlite3BtreeInsert.

3.8.8 sqlite3BtreeInsert

int sqlite3BtreeInsert(BtCursor*, const void *pKey, i64 nKey,
                                  const void *pData, int nData,
                                  int nZero, int bias, int seekResult);

A successful call to the sqlite3BtreeInsert function made with a read/write
b-tree cursor passed as the first argument shall insert a new entry into
the b-tree structure the b-tree cursor is open on. (P: H50128)

        The requirement above implies that the results of passing anything else as
        the first argument to sqlite3BtreeInsert, for example a read-only b-tree cursor,
        are undefined.

If a call to sqlite3BtreeInsert is made to insert an entry specifying a key
value for which there already exists a matching key within the b-tree
structure, the entry with the matching key shall be removed from the b-tree
structure before the new entry is inserted. (P: H50128)

    In other words, the sqlite3BtreeInsert API could easily be renamed
        sqlite3BtreeInsertOrReplace. We will probably need a module
        requirement for the "replace" operation.

If the b-tree cursor passed to sqlite3BtreeInsert as the first argument is
open on a table b-tree, then the values passed as the second parameter (pKey)
shall be ignored. The value passed as the third parameter (nKey) shall be
used as the integer key for the new entry. (P: H50128)

If the b-tree cursor passed to sqlite3BtreeInsert as the first argument is
open on a table b-tree, then the database record associated with the new entry
shall consist of a copy of the first nData bytes of the buffer pointed to by pData
followed by nZero zero (0x00) bytes, where pData, nData and nZero are the
fourth, fifth and sixth parameters passed to sqlite3BtreeInsert, respectively. (P: H50128)

If the b-tree cursor passed to sqlite3BtreeInsert as the first argument is
open on an index b-tree, then the values passed as the fourth, fifth and sixth
parameters shall be ignored. The key (a database record) used by the new entry
shall consist of the first nKey bytes of the buffer pointed to by pKey, where
pKey and nKey are the second and third parameters passed to sqlite3BtreeInsert,
respectively. (P: H50128)

        The following requirements describe the seventh and eighth paramaters passed
        to the sqlite3BtreeInsert function. Both of these are used to provide extra
        information used by sqlite3BtreeInsert to optimize the insert operation. They
        may be safely ignored by alternative b-tree implementations.

        There should be some rationalization for these, eventually. Some traceability
        from somewhere to show how the b-tree module offering these slightly esoteric
        interfaces is helpful to SQLite overall.

If the value passed as the seventh parameter to a call to sqlite3BtreeInsert
is non-zero, sqlite3BtreeInsert shall interpret this to mean that it is likely
(but not certain) that the key belonging to the new entry is larger than the
largest key currently stored in the b-tree structure, and optimize accordingly.

If the value passed as the eighth parameter to a call to sqlite3BtreeInsert
is non-zero, then the B-Tree module shall interpret this to mean that the
the b-tree cursor has already been positioned by a successful call to
sqlite3BtreeMovetoUnpacked specifying the same key value as is being inserted,
and that sqlite3BtreeMovetoUnpacked has set the output value required by L50011 to
this value.

        If a non-zero value is passed as the eighth parameter to sqlite3BtreeInsert
        and the b-tree cursor has not been positioned as assumed by L50006, the
        results are undefined.

        Malloc and IO error handling. Maybe these should be grouped together
        for a whole bunch of APIs. And hook into the above via a definition of
        "successful call".

3.8.9 sqlite3BtreeIncrVacuum

int sqlite3BtreeIncrVacuum(Btree *);

3.9 Advisory B-Tree Locks

    This section describes the b-tree module interfaces used for acquiring
    and querying the advisory locks that can be placed on database image
    pages. The locking mechanisms described in this section are only used
    to arbitrate between multiple clients of the same in-memory page-cache.
    The locking mechanism used to control access to a file-system
    representation of the database when multiple in-memory page caches
    (possibly located in different OS processes) are open on it is
        described in this.

        As well as obtaining advisory locks explicitly using the
        sqlite3BtreeLockTable API (see below), a read-lock on page 1 of the
        database image is automatically obtained whenever a b-tree database
    connection opens a read-only or read-write transaction (see
        requirement number). Note that this means
        that a write-lock on page 1 is effectively an exclusive lock on
    the entire page-cache, as it prevents any other connection from opening
        a transaction of any kind.

3.9.1 sqlite3BtreeLockTable

int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock);

        The sqlite3BtreeLockTable API allows database clients to place
        advisory read or write locks on a specified page of the database
        image. The specified page need not exist within the database image.
        By convention, SQLite acquires read and write locks on the root
        pages of table b-trees only, but this is not required to be enforced
        by the b-tree module. Locks may only be obtained when a database
        client has an open transaction. All locks are automatically released
        when the open transaction is concluded.

A call to sqlite3BtreeLockTable, specifying a b-tree database connection handle
with an open read-only or read-write transaction as the first parameter, and
zero as the third parameter, shall attempt to obtain a read-lock on the database
page specified by the second parameter.

A call to sqlite3BtreeLockTable, specifying a b-tree database connection handle
with an open read-write transaction as the first parameter, and a non-zero value as
the third parameter, shall attempt to obtain a write-lock on the database
page specified by the second parameter.

        The two requirements above imply that the results of calling
        sqlite3BtreeLockTable on a b-tree database connection handle that does
        not currently have an open transaction, or attempting to obtain
        a write-lock using a b-tree database connection handle that only has
        a read-only transaction open are undefined.

If, when attempting to obtain a read-lock as described in L50016, there exists
another b-tree database connection connected to the same page-cache that is
holding a write-lock on the same database image page, the read-lock shall not
be granted and the call to sqlite3BtreeLockTable shall return SQLITE_LOCKED_SHAREDCACHE.

If, when attempting to obtain a write-lock as described in L50017, there exists
another b-tree database connection connected to the same page-cache that is
holding a read or write-lock on the same database image page, the write-lock
shall not be granted and the call to sqlite3BtreeLockTable shall return
SQLITE_LOCKED_SHAREDCACHE.

        Requirement L50020 is overly conservative. Because a write-lock may
        only be requested if the b-tree database connection has an open read-write
    transaction (L50017), and at most a single b-tree database connection
        may have such an open transaction at one time, it is not possible for
        a request for a write-lock to fail because another connection is holding
        a write-lock on the same b-tree database image page. It may, however,
        fail because another connection is holding a read-lock.

        All locks are held until the current transaction is concluded. Or, if
        a read-write transaction is downgraded to a read-only transaction, all
        currently held write-locks are changed to read-locks.

When a read-only or read-write transaction is concluded, all advisory b-tree locks
held by the b-tree database connection shall be relinquished.

When a read-write transaction is downgraded to a read-only transaction, all
advisory b-tree write-locks held by the b-tree database connection shall be
changed to read-locks.

 The requirement above should refer to some other
    requirement that defines when a read-write transaction is downgraded to
        a read-only transaction.

 Malloc failure?

 Read uncommitted flag. Maybe this should be handled
        outside of the b-tree module. Is there anything to stop connections
        with this flag set simply not obtaining read locks? There are assert()
        statements in the b-tree module that need to take this flag into account,
        but not actual functionality.

3.9.2 sqlite3BtreeSchemaLocked

int sqlite3BtreeSchemaLocked(Btree *pBtree);

A call to the sqlite3BtreeSchemaLocked function with a valid b-tree
database connection as the only argument shall return SQLITE_LOCKED_SHAREDCACHE
if there exists another b-tree database connection connected to the
same page-cache that currently holds a write-lock on database image
page 1.

A call to the sqlite3BtreeSchemaLocked function with a valid b-tree
database connection as the only argument shall return SQLITE_OK if
H51017 does not apply.

3.10 What do these do?

        Where do the following go?

char *sqlite3BtreeIntegrityCheck(Btree*, int *aRoot, int nRoot, int, int*);
struct Pager *sqlite3BtreePager(Btree*);
int sqlite3BtreeCopyFile(Btree *, Btree *);

void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
int sqlite3BtreeSchemaLocked(Btree *pBtree);
int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock);
void sqlite3BtreeTripAllCursors(Btree*, int);

        I know what the following do, but is this mechanism ever used? Or has it been superceded by other tricks in OP_NewRowid?

void sqlite3BtreeSetCachedRowid(BtCursor*, sqlite3_int64);
sqlite3_int64 sqlite3BtreeGetCachedRowid(BtCursor*);

        Should move to btreeInt.h

typedef struct BtShared BtShared;

3.11 APIs not branded sqlite3BtreeXXX()

  •  sqlite3PagerLockingMode

  •  sqlite3PagerJournalMode

  •  sqlite3PagerIsMemdb (vacuum and backup).

  •  sqlite3PagerJournalSizeLimit

  •  sqlite3PagerFile (used by sqlite3_file_control() and pragma lock_proxy_file).

  •  sqlite3PagerPagecount (pragma page_count and backup).

  •  Page APIs used by backup routines:

    •  sqlite3PagerGet

    •  sqlite3PagerWrite

    •  sqlite3PagerGetData

    •  sqlite3PagerGetExtra

    •  sqlite3PagerUnref

    •  sqlite3PagerTruncateImage

    •  sqlite3PagerSync

    •  sqlite3PagerFile

    •  sqlite3PagerCommitPhaseOne, sqlite3PagerCommitPhaseTwo

    •  sqlite3PagerBackupPtr

4 Module Implementation

4.1 Database Image Traversal

4.2 Database Image Manipulation

       This section should describe exactly how bits and bytes are shifted
       around when the database image is traversed and modified. i.e. how the b-tree
       balancing works, deleting an internal cell from an index b-tree etc.

4.2.1 Creating a B-Tree Structure

4.2.2 Clearing a B-Tree Structure

4.2.3 Deleting a B-Tree Structure

4.2.4 Inserting, Replacing and Deleting B-Tree Entries

        The following two sections describe the way entries are added and removed
        from B-Tree structures within a database image.

        As one might expect, the algorithms described in the following sections
        involve adding and removing b-tree cells to and from b-tree node pages.
        The format of b-tree node pages is described in detail in
        [1]. This document does not describe the exact
        way in which content is manipulated within a page, as these details are
        considered not considered high-level enough to be documented outside of
        the SQLite source code itself. For the purposes of the descriptions in
        the following sections, a b-tree node page is considered to be a container
        for an ordered list of b-tree cells. Cells may be inserted into or removed
        from any position in the ordered list as required.

    A b-tree node page has a finite capacity. If one of the algorithms
    described here is required to insert a cell into a b-tree node page,
    and there is not enough free space within the page to accommodate the
    cell, it is still nominally inserted into the requested position within
        the node, but becomes an overflow cell. Overflow cells never remain so
        for very long. If an insert, replace or delete entry operation creates
        one or more overflow cells, the b-tree structure is rearranged so that
        all cells are stored within the body of a b-tree node page before the
        operation is considered complete. This process of rearranging the b-tree
        structure is termed b-tree balancing, and is described in section
        4.2.5.

4.2.4.1 B-Tree Insert/Replace Entry

        This section describes the way in which new entries may be inserted
        into a b-tree structure, and how existing entries may be replaced. Both
        of these operations are accessed using the sqlite3BtreeInsert API.

        An insert/replace operation involves the following steps:

  1.  Based on the supplied key and value, and the type of b-tree being
             inserted into, allocate and populate any required overflow pages.
             Should reference file-format requirements that
             provide the formula for doing this.

  2.  Attempt to move the b-tree write cursor to an entry with a key
             that matches the new key being inserted. If a matching entry is
             found, then the operation is a replace. Otherwise, if the key is
             not found, an insert.

    1.  Requirements L50008, L50009, L50010 and L50011 apply to the cursor
               seek operation here. This ensures that if the search does not find
           an exact match, the cursor is left pointing to the leaf page that
               the new entry should be added into.

    2.  As specified by L50006, the cursor may already be positioned. In
               this case the seek operation is not required.

  3.  If a matching key was found in the b-tree, then it must be removed and
             the new entry added in its place.

    1.  If there are one or more overflow pages associated with the entry
               being replaced, they are moved to the free-list.

    2.  The cell corresponding to the entry being removed is removed from
               the b-tree node page.

    3.  The new cell is inserted in the position previously occupied by the
               cell removed in the previous step. If the page is not a leaf page,
           then the first four-bytes (the child-page pointer) of the old
               cell are copied to the first four bytes of the new cell. If the new
               cell is larger than the cell that it replaced, then it may become
               an overflow cell.

  4.  If no matching key was found in the b-tree, then the new cell is inserted
             into the leaf page that the cursor was left pointing to by step 1. The
             new cell may become an overflow cell.

  5.  If the new cell is now an overflow cell, then the balancing algorithm
             (see section 4.2.5) is run on the
             overflowing b-tree node page.

4.2.4.2 B-Tree Delete Entry

        This section describes the way in which entries may be removed from
    a b-tree structure, as required when the sqlite3BtreeDelete (section
        3.8.7) API is invoked. Removing an entry
        from a b-tree table involves the following steps:

  1.  All overflow pages in the overflow page chain (if any) associated
             with the entry must be moved to the database free-list. If the
             database image is an autovacuum database, the pointer-map entries
             that correspond to each overflow page in the chain must be updated.

  2.  The b-tree cell corresponding to the entry must be removed from
             the b-tree structure.

    Note about the optimization that makes it possible to move overflow pages
        to the free-list without reading their contents (i.e. without loading them
        into the cache).

        If the b-tree entry being removed is located on a leaf page (as is always the
        case with table b-tree structures), then deleting an entry from a b-tree
        is quite simple.

Figure 2 - Delete from an Internal Node

4.2.5 B-Tree Balancing Algorithm

  • The balance deeper sub-algorithm is used when the root page of
           a b-tree is overfull. It creates a new page and copies the
           entire contents of the overfull root page to it. The root page
           is then zeroed and the new page installed as its only child.
           The balancing algorithm is then run on the new child page (in case
           it is overfull).

  • The balance shallower sub-algorithm is used when the root page
           of a b-tree has only a single child page. If possible, the data from
           the child page is copied into the root-page and the child page discarded.

  • The balance quick sub-algorithm is used in a very specific,
           but common scenario. It is used only for table b-trees, when a new entry that
           has a key value greater than all existing keys in the b-tree is inserted and
           causes the right-most leaf page of the b-tree structure to become overfull.

  • The balance siblings sub-algorithm is run when a b-tree page that
           is not the root-page of its b-tree structure is either overfull or underfull.

4.2.5.1 Balance Deeper

  1.  Allocate a new page (the child-page).

  2.  Copy page data from root-page to child-page (including overflow cells).

  3.  Fix pointer map entries associated with new child-page content.

  4.  Zero the root-page.

  5.  Set the right-child pointer of the root-page to point to the new child-page.

  6.  Set the pointer map entry for the new child page.

  7.  Execute the balance procedure on the new child page.

Figure 3 - Example Balance Deeper Transform

4.2.5.2 Balance Shallower

  1.  Copy node data from child-page to root-page.

  2.  Fix pointer map entries associated with new root-page content.

  3.  Move child-page to database image free-list.

Figure 4 - Example Balance Shallower Transform

4.2.5.3 Balance Quick

  1.  Allocate a new page (the new sibling-page).

  2.  Populate the new sibling page with the new b-tree entry.

  3.  Add a new divider cell to the parent. The divider cell contains a
             pointer to the page that is currently the right-child of the parent.
             The key in the new divider cell is a copy of the largest key in the
             page that is currently the right-child of the parent.

  4.  Set the right-child of the parent page to point to the new sibling page.

  5.  If the database is an auto-vacuum database, set the pointer map
         entry associated with the new sibling page. If the cell on the new
             sibling page contains a pointer to an overflow page, set the pointer map
         entry associated with the overflow page.

  6.  Execute the balance procedure on the parent page.

Figure 5 - Example Balance Quick Transform

4.2.5.4 Balance Siblings

The balance-siblings algorithm shall redistribute the b-tree cells currently
stored on a overfull or underfull page and up to two sibling pages, adding
or removing siblings as required, such that no sibling page is overfull and
the minimum possible number of sibling pages is used to store the
redistributed b-tree cells.

      The following description describes how balance() is to be implemented. This
      represents (I think) the lowest level of detail that should be in this document.
      One skilled in the art could use this description to reimplement SQLite's
      balance-siblings algorithm. We also need requirements at a higher level
      of detail in this section. Something to test!

      The balance-siblings algorithm, as implemented by SQLite, is described as
      a series of steps below.   there are a few terms used
      below that need definitions/clarifications.

  1.  Determine the set of sibling pages to redistribute the cells of, using
             the following rules:

    1.  If the parent page has three or fewer child pages, then all child
               pages are deemed to be sibling pages for the purposes of the balance-siblings
               algorithm.

    2.  If the page being balanced is the left-most child of the parent
               page, then the three left-most child pages are used as the siblings.

    3.  If the page being balanced is the right-most child of the parent
               page, then the three right-most child pages are used as the siblings.

    4.  Otherwise, if none of the above three conditions are true, then the
               sibling pages are page being balanced and the child pages immediately
               to the left and right of it.

  2.  Determine an ordered list of cells to redistribute. There are several
             variations of this step, depending on the type of page being balanced.

    1.  If the page being balanced is a leaf page of a table b-tree,
           then the list of cells to redistribute is simply the concatenation
               of the ordered lists of cells stored on each sibling page, in order
               from left-most sibling to right-most.

    2.  If the page being balanced is a leaf page of an index b-tree, then
               the list of cells to redistribute is comprised of the cells on each
               of the sibling pages and the divider cells in the parent page that
               contain the pointers to each sibling page except the right-most. The
               list is arranged so that it contains:

      •  The cells from the left-most sibling page, in order, followed by

      •  the divider cell from the parent page that contains the pointer
          to the left-most sibling (if there is more than one sibling
                  page), followed by

      •  the divider cell that contains the pointer to the second left-most
                  sibling and the cells from the remaining sibling page (if there are three
                  sibling pages).

    3.  If the page being balanced is an internal b-tree node, then the list of
               cells to redistribute is determined as described in the previous case.
               However, when balancing an internal node each cell is associated with
               the page number of a child page of one of the sibling pages. The page
               number associated with cells stored on a sibling page is the same as
               the page number stored as the first four bytes of the cell. The page
               number associated with a divider cell within the parent page is the page
               number of the right-child page of the sibling page to which the divider
               cell contains a pointer.

  3.  Determine the new cell distribution, using the following steps:

    1.  Assign as may cells as will fit from the start of the ordered list of
               cells to the left-most sibling page. Then, if any cells remain, assign
               one to be a divider cell, and as many as will fit to the next sibling
           page. Repeat until all cells have been assigned a location.
                no divider cells for table b-tree leaf balance

    2.  The previous step generates a distribution that is biased towards the
           left-hand side. The right-most sibling may even be completely
           empty (if the last cell in the ordered list was assigned to be a
               divider cell). To rectify this, cells are moved out of the second
               right-most sibling page and into the right-most, one at a time, until
               there is at least one cell in the right-most sibling page and to move
               another cell would mean that the right-most sibling page is more full
               than the next to right-most sibling page. This is repeated for the next
               right-most pair of sibling pages, shifting cells out of the third
               right-most sibling page and into the second right-most, and so on.
                note about divider cells

  4.  Determine the set of database pages to use as the new sibling pages.

    1.  If there were an equal or greater number of siblings identified
                in step 1 than are required by the distribution calculated in step 3,
                reuse as many as possible, starting with the left-most. If step 3
                calculated a distribution that requires more sibling pages than were
                identified in step 1, allocate the required extra pages using the
                Refer to ??? algorithm.

    2.  Arrange the new sibling pages from left to right in ascending
                page number order. The new sibling page with the smallest page number
                becomes the left-most sibling page, and so forth.

  5.  Populate the new sibling pages.

    1.  Populate each new sibling page with the required set of cells. If the
                page being balanced is not a leaf page, then the child-page pointer
                field of each cell is populated with the page-number associated with
                the cell as part of step 2 above.

    2.  If the page being balanced is not a leaf page, then the right-child
                pointer stored in the page header of each new sibling page must also
                be populated. For each new sibling page except the right-most, this
                field is set to the page number associated with the cell that
                immediately follows the cells stored on the page (the cell that was
                assigned to be divider cell in step 3). For the right-most sibling page,
                the right-child pointer is set to the value that was stored in the
                right-child pointer of the right-most original sibling page identified
                in step 1.

  6.  Populate the parent page.

    1.  If the page being balanced is (was) not a leaf page of a table
           b-tree, the cells that contained pointers to the old sibling
               pages are replaced by the cells designated as divider cells as part
               of step 3. The right-child pointer field of the first divider cell
               is overwritten with the page number of the first new sibling page, and
               so on.

    2.  If the page being balanced is (was) a leaf page of a table
           b-tree, the cells that contained pointers to the old sibling
               pages are replaced by a divider cell associated with all but the
               right-most sibling page. The child-page number stored in each divider
               cell is set to the page number of the associated sibling. The integer key
               value stored in each divider cell is a copy of the largest integer key
               value stored on the associated sibling page.

    3.  Before balancing, the parent page contained a pointer to the right-most
               sibling page, either as part of a cell or as the right-child pointer
               stored in the page header. Either way, this value must be overwritten
               with the page number of the new right-most sibling page.

  7.  Populate pointer map entries.

    1.  For each sibling page that was not also an original sibling page, the
               associated pointer-map entry must be updated. Similarly, the pointer-map
               entry associated with each original sibling page that is no longer a
               sibling page must be updated.

    2.  For each cell containing an overflow pointer that has been moved from one
               page to another, the pointer-map entry associated with the overflow page
               must be updated.

    3.  If the page being balanced is (was) not a leaf, then for each cell that
               has moved from one page to another the pointer-map entry associated with
               the cell's child page must be updated.

    4.  If the page being balanced is (was) not a leaf, then the pointer-map entry
               associated with each sibling's right-child page may need to be updated.

4.2.6 Page Allocation and Deallocation

       Amongst other things, this section needs to explain our old pals the
       DontWrite() and DontRollback() optimizations.

4.2.6.1 Moving an overflow-chain to the free-list

       Describe how this can sometimes be done without reading the content of
       overflow pages.

4.2.7 Incremental Vacuum Step

4.3 Transactions and Savepoints

       Requirements surrounding how transactions are made atomic and isolated.
       Also how savepoints are implemented. What happens to active cursors after
       a rollback or savepoint-rollback.

5 References

[1] | SQLite Online Documentation,SQLite Database File Format, http://www.sqlite.org/fileformat.html.
[2] | SQLite Online Documentation,Application Defined Page Cache, http://www.sqlite.org/c3ref/pcache_methods.html.
[3] | SQLite Online Documentation,OS Interface Object, http://www.sqlite.org/c3ref/vfs.html.


The C language interface to SQLite Version 2

The SQLite library is designed to be very easy to use from a C or C++ program. This document gives an overview of the C/C++ programming interface.

1.0 The Core API

The interface to the SQLite library consists of three core functions, one opaque data structure, and some constants used as return values. The core interface is as follows:

typedef struct sqlite sqlite;
#define SQLITE_OK           0   /* Successful result */

sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);

void sqlite_close(sqlite *db);

int sqlite_exec(
  sqlite *db,
  char *sql,
  int (*xCallback)(void*,int,char**,char**),
  void *pArg,
  char **errmsg
);

The above is all you really need to know in order to use SQLite in your C or C++ programs. There are other interface functions available (and described below) but we will begin by describing the core functions shown above.

1.1 Opening a database

Use the sqlite_open function to open an existing SQLite database or to create a new SQLite database. The first argument is the database name. The second argument is intended to signal whether the database is going to be used for reading and writing or just for reading. But in the current implementation, the second argument to sqlite_open is ignored. The third argument is a pointer to a string pointer. If the third argument is not NULL and an error occurs while trying to open the database, then an error message will be written to memory obtained from malloc() and *errmsg will be made to point to this error message. The calling function is responsible for freeing the memory when it has finished with it.

The name of an SQLite database is the name of a file that will contain the database. If the file does not exist, SQLite attempts to create and initialize it. If the file is read-only (due to permission bits or because it is located on read-only media like a CD-ROM) then SQLite opens the database for reading only. The entire SQL database is stored in a single file on the disk. But additional temporary files may be created during the execution of an SQL command in order to store the database rollback journal or temporary and intermediate results of a query.

The return value of the sqlite_open function is a pointer to an opaque sqlite structure. This pointer will be the first argument to all subsequent SQLite function calls that deal with the same database. NULL is returned if the open fails for any reason.

1.2 Closing the database

To close an SQLite database, call the sqlite_close function passing it the sqlite structure pointer that was obtained from a prior call to sqlite_open. If a transaction is active when the database is closed, the transaction is rolled back.

1.3 Executing SQL statements

The sqlite_exec function is used to process SQL statements and queries. This function requires 5 parameters as follows:

  1. A pointer to the sqlite structure obtained from a prior call to sqlite_open.

  2. A null-terminated string containing the text of one or more SQL statements and/or queries to be processed.

  3. A pointer to a callback function which is invoked once for each row in the result of a query. This argument may be NULL, in which case no callbacks will ever be invoked.

  4. A pointer that is forwarded to become the first argument to the callback function.

  5. A pointer to an error string. Error messages are written to space obtained from malloc() and the error string is made to point to the malloced space. The calling function is responsible for freeing this space when it has finished with it. This argument may be NULL, in which case error messages are not reported back to the calling function.

The callback function is used to receive the results of a query. A prototype for the callback function is as follows:

int Callback(void *pArg, int argc, char **argv, char **columnNames){
  return 0;
}

The first argument to the callback is just a copy of the fourth argument to sqlite_exec This parameter can be used to pass arbitrary information through to the callback function from client code. The second argument is the number of columns in the query result. The third argument is an array of pointers to strings where each string is a single column of the result for that record. Note that the callback function reports a NULL value in the database as a NULL pointer, which is very different from an empty string. If the i-th parameter is an empty string, we will get:

argv[i][0] == 0

But if the i-th parameter is NULL we will get:

argv[i] == 0

The names of the columns are contained in first argc entries of the fourth argument. If the SHOW_DATATYPES pragma is on (it is off by default) then the second argc entries in the 4th argument are the datatypes for the corresponding columns.

If the EMPTY_RESULT_CALLBACKS pragma is set to ON and the result of a query is an empty set, then the callback is invoked once with the third parameter (argv) set to 0. In other words

argv == 0
The second parameter (argc) and the fourth parameter (columnNames) are still valid and can be used to determine the number and names of the result columns if there had been a result. The default behavior is not to invoke the callback at all if the result set is empty.

The callback function should normally return 0. If the callback function returns non-zero, the query is immediately aborted and sqlite_exec will return SQLITE_ABORT.

1.4 Error Codes

The sqlite_exec function normally returns SQLITE_OK. But if something goes wrong it can return a different value to indicate the type of error. Here is a complete list of the return codes:

#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */

The meanings of these various return values are as follows:

SQLITE_OK

This value is returned if everything worked and there were no errors.

SQLITE_INTERNAL

This value indicates that an internal consistency check within the SQLite library failed. This can only happen if there is a bug in the SQLite library. If you ever get an SQLITE_INTERNAL reply from an sqlite_exec call, please report the problem on the SQLite mailing list.

SQLITE_ERROR

This return value indicates that there was an error in the SQL that was passed into the sqlite_exec.

SQLITE_PERM

This return value says that the access permissions on the database file are such that the file cannot be opened.

SQLITE_ABORT

This value is returned if the callback function returns non-zero.

SQLITE_BUSY

This return code indicates that another program or thread has the database locked. SQLite allows two or more threads to read the database at the same time, but only one thread can have the database open for writing at the same time. Locking in SQLite is on the entire database.

SQLITE_LOCKED

This return code is similar to SQLITE_BUSY in that it indicates that the database is locked. But the source of the lock is a recursive call to sqlite_exec. This return can only occur if you attempt to invoke sqlite_exec from within a callback routine of a query from a prior invocation of sqlite_exec. Recursive calls to sqlite_exec are allowed as long as they do not attempt to write the same table.

SQLITE_NOMEM

This value is returned if a call to malloc fails.

SQLITE_READONLY

This return code indicates that an attempt was made to write to a database file that is opened for reading only.

SQLITE_INTERRUPT

This value is returned if a call to sqlite_interrupt interrupts a database operation in progress.

SQLITE_IOERR

This value is returned if the operating system informs SQLite that it is unable to perform some disk I/O operation. This could mean that there is no more space left on the disk.

SQLITE_CORRUPT

This value is returned if SQLite detects that the database it is working on has become corrupted. Corruption might occur due to a rogue process writing to the database file or it might happen due to a previously undetected logic error in of SQLite. This value is also returned if a disk I/O error occurs in such a way that SQLite is forced to leave the database file in a corrupted state. The latter should only happen due to a hardware or operating system malfunction.

SQLITE_FULL

This value is returned if an insertion failed because there is no space left on the disk, or the database is too big to hold any more information. The latter case should only occur for databases that are larger than 2GB in size.

SQLITE_CANTOPEN

This value is returned if the database file could not be opened for some reason.

SQLITE_PROTOCOL

This value is returned if some other process is messing with file locks and has violated the file locking protocol that SQLite uses on its rollback journal files.

SQLITE_SCHEMA

When the database first opened, SQLite reads the database schema into memory and uses that schema to parse new SQL statements. If another process changes the schema, the command currently being processed will abort because the virtual machine code generated assumed the old schema. This is the return code for such cases. Retrying the command usually will clear the problem.

SQLITE_TOOBIG

SQLite will not store more than about 1 megabyte of data in a single row of a single table. If you attempt to store more than 1 megabyte in a single row, this is the return code you get.

SQLITE_CONSTRAINT

This constant is returned if the SQL statement would have violated a database constraint.

SQLITE_MISMATCH

This error occurs when there is an attempt to insert non-integer data into a column labeled INTEGER PRIMARY KEY. For most columns, SQLite ignores the data type and allows any kind of data to be stored. But an INTEGER PRIMARY KEY column is only allowed to store integer data.

SQLITE_MISUSE

This error might occur if one or more of the SQLite API routines is used incorrectly. Examples of incorrect usage include calling sqlite_exec after the database has been closed using sqlite_close or calling sqlite_exec with the same database pointer simultaneously from two separate threads.

SQLITE_NOLFS

This error means that you have attempts to create or access a file database file that is larger that 2GB on a legacy Unix machine that lacks large file support.

SQLITE_AUTH

This error indicates that the authorizer callback has disallowed the SQL you are attempting to execute.

SQLITE_ROW

This is one of the return codes from the sqlite_step routine which is part of the non-callback API. It indicates that another row of result data is available.

SQLITE_DONE

This is one of the return codes from the sqlite_step routine which is part of the non-callback API. It indicates that the SQL statement has been completely executed and the sqlite_finalize routine is ready to be called.

2.0 Accessing Data Without Using A Callback Function

The sqlite_exec routine described above used to be the only way to retrieve data from an SQLite database. But many programmers found it inconvenient to use a callback function to obtain results. So beginning with SQLite version 2.7.7, a second access interface is available that does not use callbacks.

The new interface uses three separate functions to replace the single sqlite_exec function.

typedef struct sqlite_vm sqlite_vm;

int sqlite_compile(
  sqlite *db,              /* The open database */
  const char *zSql,        /* SQL statement to be compiled */
  const char **pzTail,     /* OUT: uncompiled tail of zSql */
  sqlite_vm **ppVm,        /* OUT: the virtual machine to execute zSql */
  char **pzErrmsg          /* OUT: Error message. */
);

int sqlite_step(
  sqlite_vm *pVm,          /* The virtual machine to execute */
  int *pN,                 /* OUT: Number of columns in result */
  const char ***pazValue,  /* OUT: Column data */
  const char ***pazColName /* OUT: Column names and datatypes */
);

int sqlite_finalize(
  sqlite_vm *pVm,          /* The virtual machine to be finalized */
  char **pzErrMsg          /* OUT: Error message */
);

The strategy is to compile a single SQL statement using sqlite_compile then invoke sqlite_step multiple times, once for each row of output, and finally call sqlite_finalize to clean up after the SQL has finished execution.

2.1 Compiling An SQL Statement Into A Virtual Machine

The sqlite_compile "compiles" a single SQL statement (specified by the second parameter) and generates a virtual machine that is able to execute that statement. As with must interface routines, the first parameter must be a pointer to an sqlite structure that was obtained from a prior call to sqlite_open.

A pointer to the virtual machine is stored in a pointer which is passed in as the 4th parameter. Space to hold the virtual machine is dynamically allocated. To avoid a memory leak, the calling function must invoke sqlite_finalize on the virtual machine after it has finished with it. The 4th parameter may be set to NULL if an error is encountered during compilation.

If any errors are encountered during compilation, an error message is written into memory obtained from malloc and the 5th parameter is made to point to that memory. If the 5th parameter is NULL, then no error message is generated. If the 5th parameter is not NULL, then the calling function should dispose of the memory containing the error message by calling sqlite_freemem.

If the 2nd parameter actually contains two or more statements of SQL, only the first statement is compiled. (This is different from the behavior of sqlite_exec which executes all SQL statements in its input string.) The 3rd parameter to sqlite_compile is made to point to the first character beyond the end of the first statement of SQL in the input. If the 2nd parameter contains only a single SQL statement, then the 3rd parameter will be made to point to the '\000' terminator at the end of the 2nd parameter.

On success, sqlite_compile returns SQLITE_OK. Otherwise and error code is returned.

2.2 Step-By-Step Execution Of An SQL Statement

After a virtual machine has been generated using sqlite_compile it is executed by one or more calls to sqlite_step. Each invocation of sqlite_step, except the last one, returns a single row of the result. The number of columns in the result is stored in the integer that the 2nd parameter points to. The pointer specified by the 3rd parameter is made to point to an array of pointers to column values. The pointer in the 4th parameter is made to point to an array of pointers to column names and datatypes. The 2nd through 4th parameters to sqlite_step convey the same information as the 2nd through 4th parameters of the callback routine when using the sqlite_exec interface. Except, with sqlite_step the column datatype information is always included in the in the 4th parameter regardless of whether or not the SHOW_DATATYPES pragma is on or off.

Each invocation of sqlite_step returns an integer code that indicates what happened during that step. This code may be SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or SQLITE_MISUSE.

If the virtual machine is unable to open the database file because it is locked by another thread or process, sqlite_step will return SQLITE_BUSY. The calling function should do some other activity, or sleep, for a short amount of time to give the lock a chance to clear, then invoke sqlite_step again. This can be repeated as many times as desired.

Whenever another row of result data is available, sqlite_step will return SQLITE_ROW. The row data is stored in an array of pointers to strings and the 2nd parameter is made to point to this array.

When all processing is complete, sqlite_step will return either SQLITE_DONE or SQLITE_ERROR. SQLITE_DONE indicates that the statement completed successfully and SQLITE_ERROR indicates that there was a run-time error. (The details of the error are obtained from sqlite_finalize.) It is a misuse of the library to attempt to call sqlite_step again after it has returned SQLITE_DONE or SQLITE_ERROR.

When sqlite_step returns SQLITE_DONE or SQLITE_ERROR, the *pN and *pazColName values are set to the number of columns in the result set and to the names of the columns, just as they are for an SQLITE_ROW return. This allows the calling code to find the number of result columns and the column names and datatypes even if the result set is empty. The *pazValue parameter is always set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR. If the SQL being executed is a statement that does not return a result (such as an INSERT or an UPDATE) then *pN will be set to zero and *pazColName will be set to NULL.

If you abuse the library by trying to call sqlite_step inappropriately it will attempt return SQLITE_MISUSE. This can happen if you call sqlite_step() on the same virtual machine at the same time from two or more threads or if you call sqlite_step() again after it returned SQLITE_DONE or SQLITE_ERROR or if you pass in an invalid virtual machine pointer to sqlite_step(). You should not depend on the SQLITE_MISUSE return code to indicate an error. It is possible that a misuse of the interface will go undetected and result in a program crash. The SQLITE_MISUSE is intended as a debugging aid only - to help you detect incorrect usage prior to a mishap. The misuse detection logic is not guaranteed to work in every case.

2.3 Deleting A Virtual Machine

Every virtual machine that sqlite_compile creates should eventually be handed to sqlite_finalize. The sqlite_finalize() procedure deallocates the memory and other resources that the virtual machine uses. Failure to call sqlite_finalize() will result in resource leaks in your program.

The sqlite_finalize routine also returns the result code that indicates success or failure of the SQL operation that the virtual machine carried out. The value returned by sqlite_finalize() will be the same as would have been returned had the same SQL been executed by sqlite_exec. The error message returned will also be the same.

It is acceptable to call sqlite_finalize on a virtual machine before sqlite_step has returned SQLITE_DONE. Doing so has the effect of interrupting the operation in progress. Partially completed changes will be rolled back and the database will be restored to its original state (unless an alternative recovery algorithm is selected using an ON CONFLICT clause in the SQL being executed.) The effect is the same as if a callback function of sqlite_exec had returned non-zero.

It is also acceptable to call sqlite_finalize on a virtual machine that has never been passed to sqlite_step even once.

3.0 The Extended API

Only the three core routines described in section 1.0 are required to use SQLite. But there are many other functions that provide useful interfaces. These extended routines are as follows:

int sqlite_last_insert_rowid(sqlite*);

int sqlite_changes(sqlite*);

int sqlite_get_table(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg
);

void sqlite_free_table(char**);

void sqlite_interrupt(sqlite*);

int sqlite_complete(const char *sql);

void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*);

void sqlite_busy_timeout(sqlite*, int ms);

const char sqlite_version[];

const char sqlite_encoding[];

int sqlite_exec_printf(
  sqlite*,
  char *sql,
  int (*)(void*,int,char**,char**),
  void*,
  char **errmsg,
  ...
);

int sqlite_exec_vprintf(
  sqlite*,
  char *sql,
  int (*)(void*,int,char**,char**),
  void*,
  char **errmsg,
  va_list
);

int sqlite_get_table_printf(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg,
  ...
);

int sqlite_get_table_vprintf(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg,
  va_list
);

char *sqlite_mprintf(const char *zFormat, ...);

char *sqlite_vmprintf(const char *zFormat, va_list);

void sqlite_freemem(char*);

void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);

All of the above definitions are included in the "sqlite.h" header file that comes in the source tree.

3.1 The ROWID of the most recent insert

Every row of an SQLite table has a unique integer key. If the table has a column labeled INTEGER PRIMARY KEY, then that column serves as the key. If there is no INTEGER PRIMARY KEY column then the key is a unique integer. The key for a row can be accessed in a SELECT statement or used in a WHERE or ORDER BY clause using any of the names "ROWID", "OID", or "_ROWID_".

When you do an insert into a table that does not have an INTEGER PRIMARY KEY column, or if the table does have an INTEGER PRIMARY KEY but the value for that column is not specified in the VALUES clause of the insert, then the key is automatically generated. You can find the value of the key for the most recent INSERT statement using the sqlite_last_insert_rowid API function.

3.2 The number of rows that changed

The sqlite_changes API function returns the number of rows that have been inserted, deleted, or modified since the database was last quiescent. A "quiescent" database is one in which there are no outstanding calls to sqlite_exec and no VMs created by sqlite_compile that have not been finalized by sqlite_finalize. In common usage, sqlite_changes returns the number of rows inserted, deleted, or modified by the most recent sqlite_exec call or since the most recent sqlite_compile. But if you have nested calls to sqlite_exec (that is, if the callback routine of one sqlite_exec invokes another sqlite_exec) or if you invoke sqlite_compile to create a new VM while there is still another VM in existence, then the meaning of the number returned by sqlite_changes is more complex. The number reported includes any changes that were later undone by a ROLLBACK or ABORT. But rows that are deleted because of a DROP TABLE are not counted.

SQLite implements the command "DELETE FROM table" (without a WHERE clause) by dropping the table then recreating it. This is much faster than deleting the elements of the table individually. But it also means that the value returned from sqlite_changes will be zero regardless of the number of elements that were originally in the table. If an accurate count of the number of elements deleted is necessary, use "DELETE FROM table WHERE 1" instead.

3.3 Querying into memory obtained from malloc()

The sqlite_get_table function is a wrapper around sqlite_exec that collects all the information from successive callbacks and writes it into memory obtained from malloc(). This is a convenience function that allows the application to get the entire result of a database query with a single function call.

The main result from sqlite_get_table is an array of pointers to strings. There is one element in this array for each column of each row in the result. NULL results are represented by a NULL pointer. In addition to the regular data, there is an added row at the beginning of the array that contains the name of each column of the result.

As an example, consider the following query:

SELECT employee_name, login, host FROM users WHERE login LIKE 'd%';

This query will return the name, login and host computer name for every employee whose login begins with the letter "d". If this query is submitted to sqlite_get_table the result might look like this:

nrow = 2
ncolumn = 3
result[0] = "employee_name"
result[1] = "login"
result[2] = "host"
result[3] = "dummy"
result[4] = "No such user"
result[5] = 0
result[6] = "D. Richard Hipp"
result[7] = "drh"
result[8] = "zadok"

Notice that the "host" value for the "dummy" record is NULL so the result[] array contains a NULL pointer at that slot.

If the result set of a query is empty, then by default sqlite_get_table will set nrow to 0 and leave its result parameter is set to NULL. But if the EMPTY_RESULT_CALLBACKS pragma is ON then the result parameter is initialized to the names of the columns only. For example, consider this query which has an empty result set:

SELECT employee_name, login, host FROM users WHERE employee_name IS NULL;

The default behavior gives this results:

nrow = 0
ncolumn = 0
result = 0

But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following is returned:

nrow = 0
ncolumn = 3
result[0] = "employee_name"
result[1] = "login"
result[2] = "host"

Memory to hold the information returned by sqlite_get_table is obtained from malloc(). But the calling function should not try to free this information directly. Instead, pass the complete table to sqlite_free_table when the table is no longer needed. It is safe to call sqlite_free_table with a NULL pointer such as would be returned if the result set is empty.

The sqlite_get_table routine returns the same integer result code as sqlite_exec.

3.4 Interrupting an SQLite operation

The sqlite_interrupt function can be called from a different thread or from a signal handler to cause the current database operation to exit at its first opportunity. When this happens, the sqlite_exec routine (or the equivalent) that started the database operation will return SQLITE_INTERRUPT.

3.5 Testing for a complete SQL statement

The next interface routine to SQLite is a convenience function used to test whether or not a string forms a complete SQL statement. If the sqlite_complete function returns true when its input is a string, then the argument forms a complete SQL statement. There are no guarantees that the syntax of that statement is correct, but we at least know the statement is complete. If sqlite_complete returns false, then more text is required to complete the SQL statement.

For the purpose of the sqlite_complete function, an SQL statement is complete if it ends in a semicolon.

The sqlite command-line utility uses the sqlite_complete function to know when it needs to call sqlite_exec. After each line of input is received, sqlite calls sqlite_complete on all input in its buffer. If sqlite_complete returns true, then sqlite_exec is called and the input buffer is reset. If sqlite_complete returns false, then the prompt is changed to the continuation prompt and another line of text is read and added to the input buffer.

3.6 Library version string

The SQLite library exports the string constant named sqlite_version which contains the version number of the library. The header file contains a macro SQLITE_VERSION with the same information. If desired, a program can compare the SQLITE_VERSION macro against the sqlite_version string constant to verify that the version number of the header file and the library match.

3.7 Library character encoding

By default, SQLite assumes that all data uses a fixed-size 8-bit character (iso8859). But if you give the --enable-utf8 option to the configure script, then the library assumes UTF-8 variable sized characters. This makes a difference for the LIKE and GLOB operators and the LENGTH() and SUBSTR() functions. The static string sqlite_encoding will be set to either "UTF-8" or "iso8859" to indicate how the library was compiled. In addition, the sqlite.h header file will define one of the macros SQLITE_UTF8 or SQLITE_ISO8859, as appropriate.

Note that the character encoding mechanism used by SQLite cannot be changed at run-time. This is a compile-time option only. The sqlite_encoding character string just tells you how the library was compiled.

3.8 Changing the library's response to locked files

The sqlite_busy_handler procedure can be used to register a busy callback with an open SQLite database. The busy callback will be invoked whenever SQLite tries to access a database that is locked. The callback will typically do some other useful work, or perhaps sleep, in order to give the lock a chance to clear. If the callback returns non-zero, then SQLite tries again to access the database and the cycle repeats. If the callback returns zero, then SQLite aborts the current operation and returns SQLITE_BUSY.

The arguments to sqlite_busy_handler are the opaque structure returned from sqlite_open, a pointer to the busy callback function, and a generic pointer that will be passed as the first argument to the busy callback. When SQLite invokes the busy callback, it sends it three arguments: the generic pointer that was passed in as the third argument to sqlite_busy_handler, the name of the database table or index that the library is trying to access, and the number of times that the library has attempted to access the database table or index.

For the common case where we want the busy callback to sleep, the SQLite library provides a convenience routine sqlite_busy_timeout. The first argument to sqlite_busy_timeout is a pointer to an open SQLite database and the second argument is a number of milliseconds. After sqlite_busy_timeout has been executed, the SQLite library will wait for the lock to clear for at least the number of milliseconds specified before it returns SQLITE_BUSY. Specifying zero milliseconds for the timeout restores the default behavior.

3.9 Using the _printf() wrapper functions

The four utility functions

  • sqlite_exec_printf()
  • sqlite_exec_vprintf()
  • sqlite_get_table_printf()
  • sqlite_get_table_vprintf()

implement the same query functionality as sqlite_exec and sqlite_get_table. But instead of taking a complete SQL statement as their second argument, the four _printf routines take a printf-style format string. The SQL statement to be executed is generated from this format string and from whatever additional arguments are attached to the end of the function call.

There are two advantages to using the SQLite printf functions instead of sprintf. First of all, with the SQLite printf routines, there is never a danger of overflowing a static buffer as there is with sprintf. The SQLite printf routines automatically allocate (and later frees) as much memory as is necessary to hold the SQL statements generated.

The second advantage the SQLite printf routines have over sprintf are two new formatting options specifically designed to support string literals in SQL. Within the format string, the %q formatting option works very much like %s in that it reads a null-terminated string from the argument list and inserts it into the result. But %q translates the inserted string by making two copies of every single-quote (') character in the substituted string. This has the effect of escaping the end-of-string meaning of single-quote within a string literal. The %Q formatting option works similar; it translates the single-quotes like %q and additionally encloses the resulting string in single-quotes. If the argument for the %Q formatting options is a NULL pointer, the resulting string is NULL without single quotes.

Consider an example. Suppose you are trying to insert a string value into a database table where the string value was obtained from user input. Suppose the string to be inserted is stored in a variable named zString. The code to do the insertion might look like this:

sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES('%s')",
  0, 0, 0, zString);

If the zString variable holds text like "Hello", then this statement will work just fine. But suppose the user enters a string like "Hi y'all!". The SQL statement generated reads as follows:

INSERT INTO table1 VALUES('Hi y'all')

This is not valid SQL because of the apostrophe in the word "y'all". But if the %q formatting option is used instead of %s, like this:

sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES('%q')",
  0, 0, 0, zString);

Then the generated SQL will look like the following:

INSERT INTO table1 VALUES('Hi y''all')

Here the apostrophe has been escaped and the SQL statement is well-formed. When generating SQL on-the-fly from data that might contain a single-quote character ('), it is always a good idea to use the SQLite printf routines and the %q formatting option instead of sprintf.

If the %Q formatting option is used instead of %q, like this:

sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES(%Q)",
  0, 0, 0, zString);

Then the generated SQL will look like the following:

INSERT INTO table1 VALUES('Hi y''all')

If the value of the zString variable is NULL, the generated SQL will look like the following:

INSERT INTO table1 VALUES(NULL)

All of the _printf() routines above are built around the following two functions:

char *sqlite_mprintf(const char *zFormat, ...);
char *sqlite_vmprintf(const char *zFormat, va_list);

The sqlite_mprintf() routine works like the standard library sprintf() except that it writes its results into memory obtained from malloc() and returns a pointer to the malloced buffer. sqlite_mprintf() also understands the %q and %Q extensions described above. The sqlite_vmprintf() is a varargs version of the same routine. The string pointer that these routines return should be freed by passing it to sqlite_freemem().

3.10 Performing background jobs during large queries

The sqlite_progress_handler() routine can be used to register a callback routine with an SQLite database to be invoked periodically during long running calls to sqlite_exec(), sqlite_step() and the various wrapper functions.

The callback is invoked every N virtual machine operations, where N is supplied as the second argument to sqlite_progress_handler(). The third and fourth arguments to sqlite_progress_handler() are a pointer to the routine to be invoked and a void pointer to be passed as the first argument to it.

The time taken to execute each virtual machine operation can vary based on many factors. A typical value for a 1 GHz PC is between half and three million per second but may be much higher or lower, depending on the query. As such it is difficult to schedule background operations based on virtual machine operations. Instead, it is recommended that a callback be scheduled relatively frequently (say every 1000 instructions) and external timer routines used to determine whether or not background jobs need to be run.

4.0 Adding New SQL Functions

Beginning with version 2.4.0, SQLite allows the SQL language to be extended with new functions implemented as C code. The following interface is used:

typedef struct sqlite_func sqlite_func;

int sqlite_create_function(
  sqlite *db,
  const char *zName,
  int nArg,
  void (*xFunc)(sqlite_func*,int,const char**),
  void *pUserData
);
int sqlite_create_aggregate(
  sqlite *db,
  const char *zName,
  int nArg,
  void (*xStep)(sqlite_func*,int,const char**),
  void (*xFinalize)(sqlite_func*),
  void *pUserData
);

char *sqlite_set_result_string(sqlite_func*,const char*,int);
void sqlite_set_result_int(sqlite_func*,int);
void sqlite_set_result_double(sqlite_func*,double);
void sqlite_set_result_error(sqlite_func*,const char*,int);

void *sqlite_user_data(sqlite_func*);
void *sqlite_aggregate_context(sqlite_func*, int nBytes);
int sqlite_aggregate_count(sqlite_func*);

The sqlite_create_function() interface is used to create regular functions and sqlite_create_aggregate() is used to create new aggregate functions. In both cases, the db parameter is an open SQLite database on which the functions should be registered, zName is the name of the new function, nArg is the number of arguments, and pUserData is a pointer which is passed through unchanged to the C implementation of the function. Both routines return 0 on success and non-zero if there are any errors.

The length of a function name may not exceed 255 characters. Any attempt to create a function whose name exceeds 255 characters in length will result in an error.

For regular functions, the xFunc callback is invoked once for each function call. The implementation of xFunc should call one of the sqlite_set_result_... interfaces to return its result. The sqlite_user_data() routine can be used to retrieve the pUserData pointer that was passed in when the function was registered.

For aggregate functions, the xStep callback is invoked once for each row in the result and then xFinalize is invoked at the end to compute a final answer. The xStep routine can use the sqlite_aggregate_context() interface to allocate memory that will be unique to that particular instance of the SQL function. This memory will be automatically deleted after xFinalize is called. The sqlite_aggregate_count() routine can be used to find out how many rows of data were passed to the aggregate. The xFinalize callback should invoke one of the sqlite_set_result_... interfaces to set the final result of the aggregate.

SQLite now implements all of its built-in functions using this interface. For additional information and examples on how to create new SQL functions, review the SQLite source code in the file func.c.

5.0 Multi-Threading And SQLite

If SQLite is compiled with the THREADSAFE preprocessor macro set to 1, then it is safe to use SQLite from two or more threads of the same process at the same time. But each thread should have its own sqlite* pointer returned from sqlite_open. It is never safe for two or more threads to access the same sqlite* pointer at the same time.

In precompiled SQLite libraries available on the website, the Unix versions are compiled with THREADSAFE turned off but the Windows versions are compiled with THREADSAFE turned on. If you need something different that this you will have to recompile.

Under Unix, an sqlite* pointer should not be carried across a fork() system call into the child process. The child process should open its own copy of the database after the fork().

6.0 Usage Examples

For examples of how the SQLite C/C++ interface can be used, refer to the source code for the sqlite program in the file src/shell.c of the source tree. Additional information about sqlite is available at sqlite.html. See also the sources to the Tcl interface for SQLite in the source file src/tclsqlite.c.


C/C++ Interface For SQLite Version 3 (old)

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

Note: This document was written in 2004 as a guide to helping programmers move from using SQLite version 2 to SQLite version 3. The information in this document is still essentially correct, however there have been many changes and enhancements over the years. We recommend that the following documents be used instead:

  • An Introduction To The SQLite C/C++ Interface
  • SQLite C/C++ Reference Guide

C/C++ Interface For SQLite Version 3

1.0 Overview

SQLite version 3.0 is a new version of SQLite, derived from the SQLite 2.8.13 code base, but with an incompatible file format and API. SQLite version 3.0 was created to answer demand for the following features:

  • Support for UTF-16.
  • User-definable text collating sequences.
  • The ability to store BLOBs in indexed columns.

It was necessary to move to version 3.0 to implement these features because each requires incompatible changes to the database file format. Other incompatible changes, such as a cleanup of the API, were introduced at the same time under the theory that it is best to get your incompatible changes out of the way all at once.

The API for version 3.0 is similar to the version 2.X API, but with some important changes. Most noticeably, the "sqlite_" prefix that occurs on the beginning of all API functions and data structures are changed to "sqlite3_". This avoids confusion between the two APIs and allows linking against both SQLite 2.X and SQLite 3.0 at the same time.

There is no agreement on what the C datatype for a UTF-16 string should be. Therefore, SQLite uses a generic type of void* to refer to UTF-16 strings. Client software can cast the void* to whatever datatype is appropriate for their system.

2.0 C/C++ Interface

The API for SQLite 3.0 includes 83 separate functions in addition to several data structures and #defines. (A complete API reference is provided as a separate document.) Fortunately, the interface is not nearly as complex as its size implies. Simple programs can still make do with only 3 functions: sqlite3_open(), sqlite3_exec(), and sqlite3_close(). More control over the execution of the database engine is provided using sqlite3_prepare_v2() to compile an SQLite statement into byte code and sqlite3_step() to execute that bytecode. A family of routines with names beginning with sqlite3_column_ is used to extract information about the result set of a query. Many interface functions come in pairs, with both a UTF-8 and UTF-16 version. And there is a collection of routines used to implement user-defined SQL functions and user-defined text collating sequences.

2.1 Opening and closing a database

   typedef struct sqlite3 sqlite3;
   int sqlite3_open(const char*, sqlite3**);
   int sqlite3_open16(const void*, sqlite3**);
   int sqlite3_close(sqlite3*);
   const char *sqlite3_errmsg(sqlite3*);
   const void *sqlite3_errmsg16(sqlite3*);
   int sqlite3_errcode(sqlite3*);

The sqlite3_open() routine returns an integer error code rather than a pointer to the sqlite3 structure as the version 2 interface did. The difference between sqlite3_open() and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native byte order) for the name of the database file. If a new database file needs to be created, then sqlite3_open16() sets the internal text representation to UTF-16 whereas sqlite3_open() sets the text representation to UTF-8.

The opening and/or creating of the database file is deferred until the file is actually needed. This allows options and parameters, such as the native text representation and default page size, to be set using PRAGMA statements.

The sqlite3_errcode() routine returns a result code for the most recent major API call. sqlite3_errmsg() returns an English-language text error message for the most recent error. The error message is represented in UTF-8 and will be ephemeral - it could disappear on the next call to any SQLite API function. sqlite3_errmsg16() works like sqlite3_errmsg() except that it returns the error message represented as UTF-16 in host native byte order.

The error codes for SQLite version 3 are unchanged from version 2. They are as follows:

#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */

2.2 Executing SQL statements

   typedef int (*sqlite_callback)(void*,int,char**, char**);
   int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);

The sqlite3_exec() function works much as it did in SQLite version 2. Zero or more SQL statements specified in the second parameter are compiled and executed. Query results are returned to a callback routine.

In SQLite version 3, the sqlite3_exec routine is just a wrapper around calls to the prepared statement interface.

   typedef struct sqlite3_stmt sqlite3_stmt;
   int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
   int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
   int sqlite3_finalize(sqlite3_stmt*);
   int sqlite3_reset(sqlite3_stmt*);

The sqlite3_prepare interface compiles a single SQL statement into byte code for later execution. This interface is now the preferred way of accessing the database.

The SQL statement is a UTF-8 string for sqlite3_prepare(). The sqlite3_prepare16() works the same way except that it expects a UTF-16 string as SQL input. Only the first SQL statement in the input string is compiled. The fifth parameter is filled in with a pointer to the next (uncompiled) SQLite statement in the input string, if any. The sqlite3_finalize() routine deallocates a prepared SQL statement. All prepared statements must be finalized before the database can be closed. The sqlite3_reset() routine resets a prepared SQL statement so that it can be executed again.

The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa" where "nnn" is an integer and "aaa" is an identifier. Such tokens represent unspecified literal values (or "wildcards") to be filled in later by the sqlite3_bind interface. Each wildcard has an associated number which is its sequence in the statement or the "nnn" in the case of a "?nnn" form. It is allowed for the same wildcard to occur more than once in the same SQL statement, in which case all instance of that wildcard will be filled in with the same value. Unbound wildcards have a value of NULL.

   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   int sqlite3_bind_double(sqlite3_stmt*, int, double);
   int sqlite3_bind_int(sqlite3_stmt*, int, int);
   int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
   int sqlite3_bind_null(sqlite3_stmt*, int);
   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
   int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);

There is an assortment of sqlite3_bind routines used to assign values to wildcards in a prepared SQL statement. Unbound wildcards are interpreted as NULLs. Bindings are not reset by sqlite3_reset(). But wildcards can be rebound to new values after an sqlite3_reset().

After an SQL statement has been prepared (and optionally bound), it is executed using:

   int sqlite3_step(sqlite3_stmt*);

The sqlite3_step() routine return SQLITE_ROW if it is returning a single row of the result set, or SQLITE_DONE if execution has completed, either normally or due to an error. It might also return SQLITE_BUSY if it is unable to open the database file. If the return value is SQLITE_ROW, then the following routines can be used to extract information about that row of the result set:

   const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
   int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
   int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
   int sqlite3_column_count(sqlite3_stmt*);
   const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
   const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
   double sqlite3_column_double(sqlite3_stmt*, int iCol);
   int sqlite3_column_int(sqlite3_stmt*, int iCol);
   long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
   const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
   const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
   const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
   const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
   int sqlite3_column_type(sqlite3_stmt*, int iCol);

The sqlite3_column_count() function returns the number of columns in the results set. sqlite3_column_count() can be called at any time after sqlite3_prepare_v2(). sqlite3_data_count() works similarly to sqlite3_column_count() except that it only works following sqlite3_step(). If the previous call to sqlite3_step() returned SQLITE_DONE or an error code, then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will continue to return the number of columns in the result set.

Returned data is examined using the other sqlite3_column_***() functions, all of which take a column number as their second parameter. Columns are zero-indexed from left to right. Note that this is different to parameters, which are indexed starting at one.

The sqlite3_column_type() function returns the datatype for the value in the Nth column. The return value is one of these:

   #define SQLITE_INTEGER  1
   #define SQLITE_FLOAT    2
   #define SQLITE_TEXT     3
   #define SQLITE_BLOB     4
   #define SQLITE_NULL     5

The sqlite3_column_decltype() routine returns text which is the declared type of the column in the CREATE TABLE statement. For an expression, the return type is an empty string. sqlite3_column_name() returns the name of the Nth column. sqlite3_column_bytes() returns the number of bytes in a column that has type BLOB or the number of bytes in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns the same value for BLOBs but for TEXT strings returns the number of bytes in a UTF-16 encoding. sqlite3_column_blob() return BLOB data. sqlite3_column_text() return TEXT data as UTF-8. sqlite3_column_text16() return TEXT data as UTF-16. sqlite3_column_int() return INTEGER data in the host machines native integer format. sqlite3_column_int64() returns 64-bit INTEGER data. Finally, sqlite3_column_double() return floating point data.

It is not necessary to retrieve data in the format specify by sqlite3_column_type(). If a different format is requested, the data is converted automatically.

Data format conversions can invalidate the pointer returned by prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16(). Pointers might be invalided in the following cases:

  • The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string.

  • The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16.

  • The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() is called. The content must be converted to UTF-8.

Note that conversions between UTF-16be and UTF-16le are always done in place and do not invalidate a prior pointer, though of course the content of the buffer that the prior pointer points to will have been modified. Other kinds of conversion are done in place when it is possible, but sometime it is not possible and in those cases prior pointers are invalidated.

The safest and easiest to remember policy is this: assume that any result from

  • sqlite3_column_blob(),
  • sqlite3_column_text(), or
  • sqlite3_column_text16()
is invalided by subsequent calls to
  • sqlite3_column_bytes(),
  • sqlite3_column_bytes16(),
  • sqlite3_column_text(), or
  • sqlite3_column_text16().
This means that you should always call sqlite3_column_bytes() or sqlite3_column_bytes16() before calling sqlite3_column_blob(), sqlite3_column_text(), or sqlite3_column_text16().

2.3 User-defined functions

User defined functions can be created using the following routine:

   typedef struct sqlite3_value sqlite3_value;
   int sqlite3_create_function(
     sqlite3 *,
     const char *zFunctionName,
     int nArg,
     int eTextRep,
     void*,
     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
     void (*xFinal)(sqlite3_context*)
   );
   int sqlite3_create_function16(
     sqlite3*,
     const void *zFunctionName,
     int nArg,
     int eTextRep,
     void*,
     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
     void (*xFinal)(sqlite3_context*)
   );
   #define SQLITE_UTF8     1
   #define SQLITE_UTF16    2
   #define SQLITE_UTF16BE  3
   #define SQLITE_UTF16LE  4
   #define SQLITE_ANY      5

The nArg parameter specifies the number of arguments to the function. A value of 0 indicates that any number of arguments is allowed. The eTextRep parameter specifies what representation text values are expected to be in for arguments to this function. The value of this parameter should be one of the parameters defined above. SQLite version 3 allows multiple implementations of the same function using different text representations. The database engine chooses the function that minimization the number of text conversions required.

Normal functions specify only xFunc and leave xStep and xFinal set to NULL. Aggregate functions specify xStep and xFinal and leave xFunc set to NULL. There is no separate sqlite3_create_aggregate() API.

The function name is specified in UTF-8. A separate sqlite3_create_function16() API works the same as sqlite_create_function() except that the function name is specified in UTF-16 host byte order.

Notice that the parameters to functions are now pointers to sqlite3_value structures instead of pointers to strings as in SQLite version 2.X. The following routines are used to extract useful information from these "values":

   const void *sqlite3_value_blob(sqlite3_value*);
   int sqlite3_value_bytes(sqlite3_value*);
   int sqlite3_value_bytes16(sqlite3_value*);
   double sqlite3_value_double(sqlite3_value*);
   int sqlite3_value_int(sqlite3_value*);
   long long int sqlite3_value_int64(sqlite3_value*);
   const unsigned char *sqlite3_value_text(sqlite3_value*);
   const void *sqlite3_value_text16(sqlite3_value*);
   int sqlite3_value_type(sqlite3_value*);

Function implementations use the following APIs to acquire context and to report results:

   void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
   void *sqlite3_user_data(sqlite3_context*);
   void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
   void sqlite3_result_double(sqlite3_context*, double);
   void sqlite3_result_error(sqlite3_context*, const char*, int);
   void sqlite3_result_error16(sqlite3_context*, const void*, int);
   void sqlite3_result_int(sqlite3_context*, int);
   void sqlite3_result_int64(sqlite3_context*, long long int);
   void sqlite3_result_null(sqlite3_context*);
   void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
   void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
   void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
   void *sqlite3_get_auxdata(sqlite3_context*, int);
   void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));

2.4 User-defined collating sequences

The following routines are used to implement user-defined collating sequences:

   sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
      int(*xCompare)(void*,int,const void*,int,const void*));
   sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
      int(*xCompare)(void*,int,const void*,int,const void*));
   sqlite3_collation_needed(sqlite3*, void*,
      void(*)(void*,sqlite3*,int eTextRep,const char*));
   sqlite3_collation_needed16(sqlite3*, void*,
      void(*)(void*,sqlite3*,int eTextRep,const void*));

The sqlite3_create_collation() function specifies a collating sequence name and a comparison function to implement that collating sequence. The comparison function is only used for comparing text values. The eTextRep parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or SQLITE_ANY to specify which text representation the comparison function works with. Separate comparison functions can exist for the same collating sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations. The sqlite3_create_collation16() works like sqlite3_create_collation() except that the collation name is specified in UTF-16 host byte order instead of in UTF-8.

The sqlite3_collation_needed() routine registers a callback which the database engine will invoke if it encounters an unknown collating sequence. The callback can lookup an appropriate comparison function and invoke sqlite_3_create_collation() as needed. The fourth parameter to the callback is the name of the collating sequence in UTF-8. For sqlite3_collation_need16() the callback sends the collating sequence name in UTF-16 host byte order.


C/C++ Interface For SQLite Version 3

This page defined the C-language interface to SQLite.

This is not a tutorial. These pages are designed to be precise, not easy to read. For a tutorial introduction see SQLite In 3 Minutes Or Less and/or the Introduction To The SQLite C/C++ Interface.

This page contains all C-language interface information in a single HTML file. The same information is also available broken out into lots of small pages for easier viewing, if you prefer.

This document is created by a script which scans comments in the source code files.

Experimental And Deprecated Interfaces

SQLite interfaces can be subdivided into three categories:

  1. Stable
  2. Experimental
  3. Deprecated

Stable interfaces will be maintained indefinitely in a backwards compatible way. An application that uses only stable interfaces should always be able to relink against a newer version of SQLite without any changes.

Experimental interfaces are subject to change. Applications that use experimental interfaces may need to be modified when upgrading to a newer SQLite release, though this is rare. When new interfaces are added to SQLite, they generally begin as experimental interfaces. After an interface has been in use for a while and the developers are confident that the design of the interface is sound and worthy of long-term support, the interface is marked as stable.

Deprecated interfaces have been superceded by better methods of accomplishing the same thing and should be avoided in new applications. Deprecated interfaces continue to be supported for the sake of backwards compatibility. At some point in the future, it is possible that deprecated interfaces may be removed.

Key points:

  • Experimental interfaces are subject to change and/or removal at any time.
  • Deprecated interfaces should not be used in new code and might be removed in some future release.

Objects:

Note: Objects marked with "exp" are experimental and objects marked with "(obs)" are deprecated.

  • sqlite3
  • sqlite3_backup
  • sqlite3_blob
  • sqlite3_context
  • sqlite3_file
  • sqlite3_index_info
  • sqlite3_int64
  • sqlite3_uint64
  • sqlite_int64
  • sqlite_uint64
  • sqlite3_io_methods
  • sqlite3_mem_methods
  • sqlite3_module
  • sqlite3_mutex
  • sqlite3_mutex_methods
  • sqlite3_pcache
  • sqlite3_pcache_methods
  • sqlite3_stmt
  • sqlite3_temp_directory
  • sqlite3_value
  • sqlite3_vfs
  • sqlite3_vtab
  • sqlite3_vtab_cursor

Constants:

Note: Constants marked with "(exp)" are experimental and constants marked with "(obs)" are deprecated

  • SQLITE_ABORT
  • SQLITE_ACCESS_EXISTS
  • SQLITE_ACCESS_READ
  • SQLITE_ACCESS_READWRITE
  • SQLITE_ALTER_TABLE
  • SQLITE_ANALYZE
  • SQLITE_ANY
  • SQLITE_ATTACH
  • SQLITE_AUTH
  • SQLITE_BLOB
  • SQLITE_BUSY
  • SQLITE_BUSY_RECOVERY
  • SQLITE_CANTOPEN
  • SQLITE_CANTOPEN_NOTEMPDIR
  • SQLITE_CHECKPOINT_FULL
  • SQLITE_CHECKPOINT_PASSIVE
  • SQLITE_CHECKPOINT_RESTART
  • SQLITE_CONFIG_GETMALLOC
  • SQLITE_CONFIG_GETMUTEX
  • SQLITE_CONFIG_GETPCACHE
  • SQLITE_CONFIG_HEAP
  • SQLITE_CONFIG_LOG
  • SQLITE_CONFIG_LOOKASIDE
  • SQLITE_CONFIG_MALLOC
  • SQLITE_CONFIG_MEMSTATUS
  • SQLITE_CONFIG_MULTITHREAD
  • SQLITE_CONFIG_MUTEX
  • SQLITE_CONFIG_PAGECACHE
  • SQLITE_CONFIG_PCACHE
  • SQLITE_CONFIG_SCRATCH
  • SQLITE_CONFIG_SERIALIZED
  • SQLITE_CONFIG_SINGLETHREAD
  • SQLITE_CONFIG_URI
  • SQLITE_CONSTRAINT
  • SQLITE_COPY
  • SQLITE_CORRUPT
  • SQLITE_CORRUPT_VTAB
  • SQLITE_CREATE_INDEX
  • SQLITE_CREATE_TABLE
  • SQLITE_CREATE_TEMP_INDEX
  • SQLITE_CREATE_TEMP_TABLE
  • SQLITE_CREATE_TEMP_TRIGGER
  • SQLITE_CREATE_TEMP_VIEW
  • SQLITE_CREATE_TRIGGER
  • SQLITE_CREATE_VIEW
  • SQLITE_CREATE_VTABLE
  • SQLITE_DBCONFIG_ENABLE_FKEY
  • SQLITE_DBCONFIG_ENABLE_TRIGGER
  • SQLITE_DBCONFIG_LOOKASIDE
  • SQLITE_DBSTATUS_CACHE_HIT
  • SQLITE_DBSTATUS_CACHE_MISS
  • SQLITE_DBSTATUS_CACHE_USED
  • SQLITE_DBSTATUS_LOOKASIDE_HIT
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
  • SQLITE_DBSTATUS_LOOKASIDE_USED
  • SQLITE_DBSTATUS_MAX
  • SQLITE_DBSTATUS_SCHEMA_USED
  • SQLITE_DBSTATUS_STMT_USED
  • SQLITE_DELETE
  • SQLITE_DENY
  • SQLITE_DETACH
  • SQLITE_DONE
  • SQLITE_DROP_INDEX
  • SQLITE_DROP_TABLE
  • SQLITE_DROP_TEMP_INDEX
  • SQLITE_DROP_TEMP_TABLE
  • SQLITE_DROP_TEMP_TRIGGER
  • SQLITE_DROP_TEMP_VIEW
  • SQLITE_DROP_TRIGGER
  • SQLITE_DROP_VIEW
  • SQLITE_DROP_VTABLE
  • SQLITE_EMPTY
  • SQLITE_ERROR
  • SQLITE_FAIL
  • SQLITE_FCNTL_CHUNK_SIZE
  • SQLITE_FCNTL_FILE_POINTER
  • SQLITE_FCNTL_LOCKSTATE
  • SQLITE_FCNTL_OVERWRITE
  • SQLITE_FCNTL_PERSIST_WAL
  • SQLITE_FCNTL_SIZE_HINT
  • SQLITE_FCNTL_SYNC_OMITTED
  • SQLITE_FCNTL_WIN32_AV_RETRY
  • SQLITE_FLOAT
  • SQLITE_FORMAT
  • SQLITE_FULL
  • SQLITE_FUNCTION
  • SQLITE_GET_LOCKPROXYFILE
  • SQLITE_IGNORE
  • SQLITE_INDEX_CONSTRAINT_EQ
  • SQLITE_INDEX_CONSTRAINT_GE
  • SQLITE_INDEX_CONSTRAINT_GT
  • SQLITE_INDEX_CONSTRAINT_LE
  • SQLITE_INDEX_CONSTRAINT_LT
  • SQLITE_INDEX_CONSTRAINT_MATCH
  • SQLITE_INSERT
  • SQLITE_INTEGER
  • SQLITE_INTERNAL
  • SQLITE_INTERRUPT
  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL
  • SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  • SQLITE_IOERR
  • SQLITE_IOERR_ACCESS
  • SQLITE_IOERR_BLOCKED
  • SQLITE_IOERR_CHECKRESERVEDLOCK
  • SQLITE_IOERR_CLOSE
  • SQLITE_IOERR_DELETE
  • SQLITE_IOERR_DIR_CLOSE
  • SQLITE_IOERR_DIR_FSYNC
  • SQLITE_IOERR_FSTAT
  • SQLITE_IOERR_FSYNC
  • SQLITE_IOERR_LOCK
  • SQLITE_IOERR_NOMEM
  • SQLITE_IOERR_RDLOCK
  • SQLITE_IOERR_READ
  • SQLITE_IOERR_SEEK
  • SQLITE_IOERR_SHMLOCK
  • SQLITE_IOERR_SHMMAP
  • SQLITE_IOERR_SHMOPEN
  • SQLITE_IOERR_SHMSIZE
  • SQLITE_IOERR_SHORT_READ
  • SQLITE_IOERR_TRUNCATE
  • SQLITE_IOERR_UNLOCK
  • SQLITE_IOERR_WRITE
  • SQLITE_LAST_ERRNO
  • SQLITE_LIMIT_ATTACHED
  • SQLITE_LIMIT_COLUMN
  • SQLITE_LIMIT_COMPOUND_SELECT
  • SQLITE_LIMIT_EXPR_DEPTH
  • SQLITE_LIMIT_FUNCTION_ARG
  • SQLITE_LIMIT_LENGTH
  • SQLITE_LIMIT_LIKE_PATTERN_LENGTH
  • SQLITE_LIMIT_SQL_LENGTH
  • SQLITE_LIMIT_TRIGGER_DEPTH
  • SQLITE_LIMIT_VARIABLE_NUMBER
  • SQLITE_LIMIT_VDBE_OP
  • SQLITE_LOCKED
  • SQLITE_LOCKED_SHAREDCACHE
  • SQLITE_LOCK_EXCLUSIVE
  • SQLITE_LOCK_NONE
  • SQLITE_LOCK_PENDING
  • SQLITE_LOCK_RESERVED
  • SQLITE_LOCK_SHARED
  • SQLITE_MISMATCH
  • SQLITE_MISUSE
  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_LRU
  • SQLITE_MUTEX_STATIC_LRU2
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_OPEN
  • SQLITE_MUTEX_STATIC_PMEM
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_NOLFS
  • SQLITE_NOMEM
  • SQLITE_NOTADB
  • SQLITE_NOTFOUND
  • SQLITE_NULL
  • SQLITE_OK
  • SQLITE_OPEN_AUTOPROXY
  • SQLITE_OPEN_CREATE
  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE
  • SQLITE_OPEN_FULLMUTEX
  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
  • SQLITE_OPEN_NOMUTEX
  • SQLITE_OPEN_PRIVATECACHE
  • SQLITE_OPEN_READONLY
  • SQLITE_OPEN_READWRITE
  • SQLITE_OPEN_SHAREDCACHE
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_URI
  • SQLITE_OPEN_WAL
  • SQLITE_PERM
  • SQLITE_PRAGMA
  • SQLITE_PROTOCOL
  • SQLITE_RANGE
  • SQLITE_READ
  • SQLITE_READONLY
  • SQLITE_READONLY_CANTLOCK
  • SQLITE_READONLY_RECOVERY
  • SQLITE_REINDEX
  • SQLITE_REPLACE
  • SQLITE_ROLLBACK
  • SQLITE_ROW
  • SQLITE_SAVEPOINT
  • SQLITE_SCHEMA
  • SQLITE_SELECT
  • SQLITE_SET_LOCKPROXYFILE
  • SQLITE_SHM_EXCLUSIVE
  • SQLITE_SHM_LOCK
  • SQLITE_SHM_NLOCK
  • SQLITE_SHM_SHARED
  • SQLITE_SHM_UNLOCK
  • SQLITE_SOURCE_ID
  • SQLITE_STATIC
  • SQLITE_STATUS_MALLOC_COUNT
  • SQLITE_STATUS_MALLOC_SIZE
  • SQLITE_STATUS_MEMORY_USED
  • SQLITE_STATUS_PAGECACHE_OVERFLOW
  • SQLITE_STATUS_PAGECACHE_SIZE
  • SQLITE_STATUS_PAGECACHE_USED
  • SQLITE_STATUS_PARSER_STACK
  • SQLITE_STATUS_SCRATCH_OVERFLOW
  • SQLITE_STATUS_SCRATCH_SIZE
  • SQLITE_STATUS_SCRATCH_USED
  • SQLITE_STMTSTATUS_AUTOINDEX
  • SQLITE_STMTSTATUS_FULLSCAN_STEP
  • SQLITE_STMTSTATUS_SORT
  • SQLITE_SYNC_DATAONLY
  • SQLITE_SYNC_FULL
  • SQLITE_SYNC_NORMAL
  • SQLITE_TESTCTRL_ALWAYS
  • SQLITE_TESTCTRL_ASSERT
  • SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS
  • SQLITE_TESTCTRL_BITVEC_TEST
  • SQLITE_TESTCTRL_FAULT_INSTALL
  • SQLITE_TESTCTRL_FIRST
  • SQLITE_TESTCTRL_ISKEYWORD
  • SQLITE_TESTCTRL_LAST
  • SQLITE_TESTCTRL_LOCALTIME_FAULT
  • SQLITE_TESTCTRL_OPTIMIZATIONS
  • SQLITE_TESTCTRL_PENDING_BYTE
  • SQLITE_TESTCTRL_PGHDRSZ
  • SQLITE_TESTCTRL_PRNG_RESET
  • SQLITE_TESTCTRL_PRNG_RESTORE
  • SQLITE_TESTCTRL_PRNG_SAVE
  • SQLITE_TESTCTRL_RESERVE
  • SQLITE_TESTCTRL_SCRATCHMALLOC
  • SQLITE_TEXT
  • SQLITE_TOOBIG
  • SQLITE_TRANSACTION
  • SQLITE_TRANSIENT
  • SQLITE_UPDATE
  • SQLITE_UTF16
  • SQLITE_UTF16BE
  • SQLITE_UTF16LE
  • SQLITE_UTF16_ALIGNED
  • SQLITE_UTF8
  • SQLITE_VERSION
  • SQLITE_VERSION_NUMBER
  • SQLITE_VTAB_CONSTRAINT_SUPPORT

Functions:

Note: Functions marked with "(exp)" are experimental and functions marked with (obs) are deprecated.

  • sqlite3_aggregate_context
  • sqlite3_aggregate_count (obs)
  • sqlite3_auto_extension
  • sqlite3_backup_finish
  • sqlite3_backup_init
  • sqlite3_backup_pagecount
  • sqlite3_backup_remaining
  • sqlite3_backup_step
  • sqlite3_bind_blob
  • sqlite3_bind_double
  • sqlite3_bind_int
  • sqlite3_bind_int64
  • sqlite3_bind_null
  • sqlite3_bind_parameter_count
  • sqlite3_bind_parameter_index
  • sqlite3_bind_parameter_name
  • sqlite3_bind_text
  • sqlite3_bind_text16
  • sqlite3_bind_value
  • sqlite3_bind_zeroblob
  • sqlite3_blob_bytes
  • sqlite3_blob_close
  • sqlite3_blob_open
  • sqlite3_blob_read
  • sqlite3_blob_reopen
  • sqlite3_blob_write
  • sqlite3_busy_handler
  • sqlite3_busy_timeout
  • sqlite3_changes
  • sqlite3_clear_bindings
  • sqlite3_close
  • sqlite3_collation_needed
  • sqlite3_collation_needed16
  • sqlite3_column_blob
  • sqlite3_column_bytes
  • sqlite3_column_bytes16
  • sqlite3_column_count
  • sqlite3_column_database_name
  • sqlite3_column_database_name16
  • sqlite3_column_decltype
  • sqlite3_column_decltype16
  • sqlite3_column_double
  • sqlite3_column_int
  • sqlite3_column_int64
  • sqlite3_column_name
  • sqlite3_column_name16
  • sqlite3_column_origin_name
  • sqlite3_column_origin_name16
  • sqlite3_column_table_name
  • sqlite3_column_table_name16
  • sqlite3_column_text
  • sqlite3_column_text16
  • sqlite3_column_type
  • sqlite3_column_value
  • sqlite3_commit_hook
  • sqlite3_compileoption_get
  • sqlite3_compileoption_used
  • sqlite3_complete
  • sqlite3_complete16
  • sqlite3_config
  • sqlite3_context_db_handle
  • sqlite3_create_collation
  • sqlite3_create_collation16
  • sqlite3_create_collation_v2
  • sqlite3_create_function
  • sqlite3_create_function16
  • sqlite3_create_function_v2
  • sqlite3_create_module
  • sqlite3_create_module_v2
  • sqlite3_data_count
  • sqlite3_db_config
  • sqlite3_db_handle
  • sqlite3_db_mutex
  • sqlite3_db_status
  • sqlite3_declare_vtab
  • sqlite3_enable_load_extension
  • sqlite3_enable_shared_cache
  • sqlite3_errcode
  • sqlite3_errmsg
  • sqlite3_errmsg16
  • sqlite3_exec
  • sqlite3_expired (obs)
  • sqlite3_extended_errcode
  • sqlite3_extended_result_codes
  • sqlite3_file_control
  • sqlite3_finalize
  • sqlite3_free
  • sqlite3_free_table
  • sqlite3_get_autocommit
  • sqlite3_get_auxdata
  • sqlite3_get_table
  • sqlite3_global_recover (obs)
  • sqlite3_initialize
  • sqlite3_interrupt
  • sqlite3_last_insert_rowid
  • sqlite3_libversion
  • sqlite3_libversion_number
  • sqlite3_limit
  • sqlite3_load_extension
  • sqlite3_log
  • sqlite3_malloc
  • sqlite3_memory_alarm (obs)
  • sqlite3_memory_highwater
  • sqlite3_memory_used
  • sqlite3_mprintf
  • sqlite3_mutex_alloc
  • sqlite3_mutex_enter
  • sqlite3_mutex_free
  • sqlite3_mutex_held
  • sqlite3_mutex_leave
  • sqlite3_mutex_notheld
  • sqlite3_mutex_try
  • sqlite3_next_stmt
  • sqlite3_open
  • sqlite3_open16
  • sqlite3_open_v2
  • sqlite3_os_end
  • sqlite3_os_init
  • sqlite3_overload_function
  • sqlite3_prepare
  • sqlite3_prepare16
  • sqlite3_prepare16_v2
  • sqlite3_prepare_v2
  • sqlite3_profile
  • sqlite3_progress_handler
  • sqlite3_randomness
  • sqlite3_realloc
  • sqlite3_release_memory
  • sqlite3_reset
  • sqlite3_reset_auto_extension
  • sqlite3_result_blob
  • sqlite3_result_double
  • sqlite3_result_error
  • sqlite3_result_error16
  • sqlite3_result_error_code
  • sqlite3_result_error_nomem
  • sqlite3_result_error_toobig
  • sqlite3_result_int
  • sqlite3_result_int64
  • sqlite3_result_null
  • sqlite3_result_text
  • sqlite3_result_text16
  • sqlite3_result_text16be
  • sqlite3_result_text16le
  • sqlite3_result_value
  • sqlite3_result_zeroblob
  • sqlite3_rollback_hook
  • sqlite3_set_authorizer
  • sqlite3_set_auxdata
  • sqlite3_shutdown
  • sqlite3_sleep
  • sqlite3_snprintf
  • sqlite3_soft_heap_limit (obs)
  • sqlite3_soft_heap_limit64
  • sqlite3_sourceid
  • sqlite3_sql
  • sqlite3_status
  • sqlite3_step
  • sqlite3_stmt_readonly
  • sqlite3_stmt_status
  • sqlite3_strnicmp
  • sqlite3_table_column_metadata
  • sqlite3_test_control
  • sqlite3_thread_cleanup (obs)
  • sqlite3_threadsafe
  • sqlite3_total_changes
  • sqlite3_trace
  • sqlite3_transfer_bindings (obs)
  • sqlite3_unlock_notify
  • sqlite3_update_hook
  • sqlite3_uri_parameter
  • sqlite3_user_data
  • sqlite3_value_blob
  • sqlite3_value_bytes
  • sqlite3_value_bytes16
  • sqlite3_value_double
  • sqlite3_value_int
  • sqlite3_value_int64
  • sqlite3_value_numeric_type
  • sqlite3_value_text
  • sqlite3_value_text16
  • sqlite3_value_text16be
  • sqlite3_value_text16le
  • sqlite3_value_type
  • sqlite3_version,
  • sqlite3_vfs_find
  • sqlite3_vfs_register
  • sqlite3_vfs_unregister
  • sqlite3_vmprintf
  • sqlite3_vsnprintf
  • sqlite3_vtab_config
  • sqlite3_vtab_on_conflict
  • sqlite3_wal_autocheckpoint
  • sqlite3_wal_checkpoint
  • sqlite3_wal_checkpoint_v2
  • sqlite3_wal_hook

Maximum xShmLock index

#define SQLITE_SHM_NLOCK        8

The xShmLock method on sqlite3_io_methods may use values between 0 and this upper bound as its "offset" argument. The SQLite core will never attempt to acquire or release a lock outside of this range

Virtual Table Configuration Options

#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1

These macros define the various options to the sqlite3_vtab_config() interface that virtual table implementations can use to customize and optimize their behavior.

SQLITE_VTAB_CONSTRAINT_SUPPORT
Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported, where X is an integer. If X is zero, then the virtual table whose xCreate or xConnect method invoked sqlite3_vtab_config() does not support constraints. In this configuration (which is the default) if a call to the xUpdate method returns SQLITE_CONSTRAINT, then the entire statement is rolled back as if OR ABORT had been specified as part of the users SQL statement, regardless of the actual ON CONFLICT mode specified.

If X is non-zero, then the virtual table implementation guarantees that if xUpdate returns SQLITE_CONSTRAINT, it will do so before any modifications to internal or persistent data structures have been made. If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite is able to roll back a statement or database transaction, and abandon or continue processing the current SQL statement as appropriate. If the ON CONFLICT mode is REPLACE and the xUpdate method returns SQLITE_CONSTRAINT, SQLite handles this as if the ON CONFLICT mode had been ABORT.

Virtual table implementations that are required to handle OR REPLACE must do so within the xUpdate method. If a call to the sqlite3_vtab_on_conflict() function indicates that the current ON CONFLICT policy is REPLACE, the virtual table implementation should silently replace the appropriate rows within the xUpdate callback and return SQLITE_OK. Or, if this is not possible, it may return SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT constraint handling.

Online Backup Object

typedef struct sqlite3_backup sqlite3_backup;

The sqlite3_backup object records state information about an ongoing online backup operation. The sqlite3_backup object is created by a call to sqlite3_backup_init() and is destroyed by a call to sqlite3_backup_finish().

See Also: Using the SQLite Online Backup API

SQL Function Context Object

typedef struct sqlite3_context sqlite3_context;

The context in which an SQL function executes is stored in an sqlite3_context object. A pointer to an sqlite3_context object is always first parameter to application-defined SQL functions. The application-defined SQL function implementation will pass this pointer through into calls to sqlite3_result(), sqlite3_aggregate_context(), sqlite3_user_data(), sqlite3_context_db_handle(), sqlite3_get_auxdata(), and/or sqlite3_set_auxdata().

OS Interface Open File Handle

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

An sqlite3_file object represents an open file in the OS interface layer. Individual OS interface implementations will want to subclass this object by appending additional fields for their own use. The pMethods entry is a pointer to an sqlite3_io_methods object that defines methods for performing I/O operations on the open file.

Virtual Table Indexing Information

struct sqlite3_index_info {
  /* Inputs */
  int nConstraint;           /* Number of entries in aConstraint */
  struct sqlite3_index_constraint {
     int iColumn;              /* Column on left-hand side of constraint */
     unsigned char op;         /* Constraint operator */
     unsigned char usable;     /* True if this constraint is usable */
     int iTermOffset;          /* Used internally - xBestIndex should ignore */
  } *aConstraint;            /* Table of WHERE clause constraints */
  int nOrderBy;              /* Number of terms in the ORDER BY clause */
  struct sqlite3_index_orderby {
     int iColumn;              /* Column number */
     unsigned char desc;       /* True for DESC.  False for ASC. */
  } *aOrderBy;               /* The ORDER BY clause */
  /* Outputs */
  struct sqlite3_index_constraint_usage {
    int argvIndex;           /* if >0, constraint is part of argv to xFilter */
    unsigned char omit;      /* Do not code a test for this constraint */
  } *aConstraintUsage;
  int idxNum;                /* Number used to identify the index */
  char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
  int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
  int orderByConsumed;       /* True if output is already ordered */
  double estimatedCost;      /* Estimated cost of using this index */
};

The sqlite3_index_info structure and its substructures is used as part of the virtual table interface to pass information into and receive the reply from the xBestIndex method of a virtual table module. The fields under **Inputs** are the inputs to xBestIndex and are read-only. xBestIndex inserts its results into the **Outputs** fields.

The aConstraint[] array records WHERE clause constraints of the form:

column OP expr

where OP is =, <, <=, >, or >=. The particular operator is stored in aConstraint[].op using one of the SQLITE_INDEX_CONSTRAINT_ values. The index of the column is stored in aConstraint[].iColumn. aConstraint[].usable is TRUE if the expr on the right-hand side can be evaluated (and thus the constraint is usable) and false if it cannot.

The optimizer automatically inverts terms of the form "expr OP column" and makes other simplifications to the WHERE clause in an attempt to get as many WHERE clause terms into the form shown above as possible. The aConstraint[] array only reports WHERE clause terms that are relevant to the particular virtual table being queried.

Information about the ORDER BY clause is stored in aOrderBy[]. Each term of aOrderBy records a column of the ORDER BY clause.

The xBestIndex method must fill aConstraintUsage[] with information about what parameters to pass to xFilter. If argvIndex>0 then the right-hand side of the corresponding aConstraint[] is evaluated and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit is true, then the constraint is assumed to be fully handled by the virtual table and is not checked again by SQLite.

The idxNum and idxPtr values are recorded and passed into the xFilter method. sqlite3_free() is used to free idxPtr if and only if needToFreeIdxPtr is true.

The orderByConsumed means that output from xFilter/xNext will occur in the correct order to satisfy the ORDER BY clause so that no separate sorting step is required.

The estimatedCost value is an estimate of the cost of doing the particular lookup. A full scan of a table with N entries should have a cost of N. A binary search of a table of N entries should have a cost of approximately log(N).

OS Interface File Virtual Methods Object

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* Methods above are valid for version 2 */
  /* Additional methods may be added in future releases */
};

Every file opened by the sqlite3_vfs.xOpen method populates an sqlite3_file object (or, more commonly, a subclass of the sqlite3_file object) with a pointer to an instance of this object. This object defines the methods used to perform various operations against the open file represented by the sqlite3_file object.

If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods element to a non-NULL pointer, then the sqlite3_io_methods.xClose method may be invoked even if the sqlite3_vfs.xOpen reported that it failed. The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods element to NULL.

The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or SQLITE_SYNC_FULL. The first choice is the normal fsync(). The second choice is a Mac OS X style fullsync. The SQLITE_SYNC_DATAONLY flag may be ORed in to indicate that only the data of the file and not its inode needs to be synced.

The integer values to xLock() and xUnlock() are one of

  • SQLITE_LOCK_NONE,
  • SQLITE_LOCK_SHARED,
  • SQLITE_LOCK_RESERVED,
  • SQLITE_LOCK_PENDING, or
  • SQLITE_LOCK_EXCLUSIVE.
xLock() increases the lock. xUnlock() decreases the lock. The xCheckReservedLock() method checks whether any database connection, either in this process or in some other process, is holding a RESERVED, PENDING, or EXCLUSIVE lock on the file. It returns true if such a lock exists and false otherwise.

The xFileControl() method is a generic interface that allows custom VFS implementations to directly control an open file using the sqlite3_file_control() interface. The second "op" argument is an integer opcode. The third argument is a generic pointer intended to point to a structure that may contain arguments or space in which to write return values. Potential uses for xFileControl() might be functions to enable blocking locks with timeouts, to change the locking strategy (for example to use dot-file locks), to inquire about the status of a lock, or to break stale locks. The SQLite core reserves all opcodes less than 100 for its own use. A list of opcodes less than 100 is available. Applications that define a custom xFileControl method should use opcodes greater than 100 to avoid conflicts. VFS implementations should return SQLITE_NOTFOUND for file control opcodes that they do not recognize.

The xSectorSize() method returns the sector size of the device that underlies the file. The sector size is the minimum write that can be performed without disturbing other bytes in the file. The xDeviceCharacteristics() method returns a bit vector describing behaviors of the underlying device:

  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL

The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQLITE_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite().

If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the unread portions of the buffer with zeros. A VFS that fails to zero-fill short reads might seem to work. However, failure to zero-fill short reads will eventually lead to database corruption.

Memory Allocation Routines

typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int);         /* Memory allocation function */
  void (*xFree)(void*);          /* Free a prior allocation */
  void *(*xRealloc)(void*,int);  /* Resize an allocation */
  int (*xSize)(void*);           /* Return the size of an allocation */
  int (*xRoundup)(int);          /* Round up request size to allocation size */
  int (*xInit)(void*);           /* Initialize the memory allocator */
  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  void *pAppData;                /* Argument to xInit() and xShutdown() */
};

An instance of this object defines the interface between SQLite and low-level memory allocation routines.

This object is used in only one place in the SQLite interface. A pointer to an instance of this object is the argument to sqlite3_config() when the configuration option is SQLITE_CONFIG_MALLOC or SQLITE_CONFIG_GETMALLOC. By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC) during configuration, an application can specify an alternative memory allocation subsystem for SQLite to use for all of its dynamic memory needs.

Note that SQLite comes with several built-in memory allocators that are perfectly adequate for the overwhelming majority of applications and that this object is only useful to a tiny minority of applications with specialized memory allocation requirements. This object is also used during testing of SQLite in order to specify an alternative memory allocator that simulates memory out-of-memory conditions in order to verify that SQLite recovers gracefully from such conditions.

The xMalloc, xRealloc, and xFree methods must work like the malloc(), realloc() and free() functions from the standard C library. SQLite guarantees that the second argument to xRealloc is always a value returned by a prior call to xRoundup.

xSize should return the allocated size of a memory allocation previously obtained from xMalloc or xRealloc. The allocated size is always at least as big as the requested size but may be larger.

The xRoundup method returns what would be the allocated size of a memory allocation given a particular requested size. Most memory allocators round up memory allocations at least to the next multiple of 8. Some allocators round up to a larger multiple or to a power of 2. Every memory allocation request coming in through sqlite3_malloc() or sqlite3_realloc() first calls xRoundup. If xRoundup returns 0, that causes the corresponding memory allocation to fail.

The xInit method initializes the memory allocator. (For example, it might allocate any require mutexes or initialize internal data structures. The xShutdown method is invoked (indirectly) by sqlite3_shutdown() and should deallocate any resources acquired by xInit. The pAppData pointer is used as the only parameter to xInit and xShutdown.

SQLite holds the SQLITE_MUTEX_STATIC_MASTER mutex when it invokes the xInit method, so the xInit method need not be threadsafe. The xShutdown method is only called from sqlite3_shutdown() so it does not need to be threadsafe either. For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM mutex as long as the SQLITE_CONFIG_MEMSTATUS configuration option is turned on (which it is by default) and so the methods are automatically serialized. However, if SQLITE_CONFIG_MEMSTATUS is disabled, then the other methods must be threadsafe or else make their own arrangements for serialization.

SQLite will never invoke xInit() more than once without an intervening call to xShutdown().

Mutex Handle

typedef struct sqlite3_mutex sqlite3_mutex;

The mutex module within SQLite defines sqlite3_mutex to be an abstract type for a mutex object. The SQLite core never looks at the internal representation of an sqlite3_mutex. It only deals with pointers to the sqlite3_mutex object.

Mutexes are created using sqlite3_mutex_alloc().

Mutex Methods Object

typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
struct sqlite3_mutex_methods {
  int (*xMutexInit)(void);
  int (*xMutexEnd)(void);
  sqlite3_mutex *(*xMutexAlloc)(int);
  void (*xMutexFree)(sqlite3_mutex *);
  void (*xMutexEnter)(sqlite3_mutex *);
  int (*xMutexTry)(sqlite3_mutex *);
  void (*xMutexLeave)(sqlite3_mutex *);
  int (*xMutexHeld)(sqlite3_mutex *);
  int (*xMutexNotheld)(sqlite3_mutex *);
};

An instance of this structure defines the low-level routines used to allocate and use mutexes.

Usually, the default mutex implementations provided by SQLite are sufficient, however the user has the option of substituting a custom implementation for specialized deployments or systems for which SQLite does not provide a suitable implementation. In this case, the user creates and populates an instance of this structure to pass to sqlite3_config() along with the SQLITE_CONFIG_MUTEX option. Additionally, an instance of this structure can be used as an output variable when querying the system for the current mutex implementation, using the SQLITE_CONFIG_GETMUTEX option.

The xMutexInit method defined by this structure is invoked as part of system initialization by the sqlite3_initialize() function. The xMutexInit routine is called by SQLite exactly once for each effective call to sqlite3_initialize().

The xMutexEnd method defined by this structure is invoked as part of system shutdown by the sqlite3_shutdown() function. The implementation of this method is expected to release all outstanding resources obtained by the mutex methods implementation, especially those obtained by the xMutexInit method. The xMutexEnd() interface is invoked exactly once for each call to sqlite3_shutdown().

The remaining seven methods defined by this structure (xMutexAlloc, xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and xMutexNotheld) implement the following interfaces (respectively):

  • sqlite3_mutex_alloc()
  • sqlite3_mutex_free()
  • sqlite3_mutex_enter()
  • sqlite3_mutex_try()
  • sqlite3_mutex_leave()
  • sqlite3_mutex_held()
  • sqlite3_mutex_notheld()

The only difference is that the public sqlite3_XXX functions enumerated above silently ignore any invocations that pass a NULL pointer instead of a valid mutex handle. The implementations of the methods defined by this structure are not required to handle this case, the results of passing a NULL pointer instead of a valid mutex handle are undefined (i.e. it is acceptable to provide an implementation that segfaults if it is passed a NULL pointer).

The xMutexInit() method must be threadsafe. It must be harmless to invoke xMutexInit() multiple times within the same process and without intervening calls to xMutexEnd(). Second and subsequent calls to xMutexInit() must be no-ops.

xMutexInit() must not use SQLite memory allocation (sqlite3_malloc() and its associates). Similarly, xMutexAlloc() must not use SQLite memory allocation for a static mutex. However xMutexAlloc() may use SQLite memory allocation for a fast or recursive mutex.

SQLite will invoke the xMutexEnd() method when sqlite3_shutdown() is called, but only if the prior call to xMutexInit returned SQLITE_OK. If xMutexInit fails in any way, it is expected to clean up after itself prior to returning.

Custom Page Cache Object

typedef struct sqlite3_pcache sqlite3_pcache;

The sqlite3_pcache type is opaque. It is implemented by the pluggable module. The SQLite core has no knowledge of its size or internal structure and never deals with the sqlite3_pcache object except by holding and passing pointers to the object.

See sqlite3_pcache_methods for additional information.

Name Of The Folder Holding Temporary Files

SQLITE_EXTERN char *sqlite3_temp_directory;

If this global variable is made to point to a string which is the name of a folder (a.k.a. directory), then all temporary files created by SQLite when using a built-in VFS will be placed in that directory. If this variable is a NULL pointer, then SQLite performs a search for an appropriate temporary file directory.

It is not safe to read or modify this variable in more than one thread at a time. It is not safe to read or modify this variable if a database connection is being used at the same time in a separate thread. It is intended that this variable be set once as part of process initialization and before any SQLite interface routines have been called and that this variable remain unchanged thereafter.

The temp_store_directory pragma may modify this variable and cause it to point to memory obtained from sqlite3_malloc. Furthermore, the temp_store_directory pragma always assumes that any string that this variable points to is held in memory obtained from sqlite3_malloc and the pragma may attempt to free that memory using sqlite3_free. Hence, if this variable is modified directly, either it should be made NULL or made to point to memory obtained from sqlite3_malloc or else the use of the temp_store_directory pragma should be avoided.

OS Interface Object

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens.
  */
};

An instance of the sqlite3_vfs object defines the interface between the SQLite core and the underlying operating system. The "vfs" in the name of the object stands for "virtual file system". See the VFS documentation for further information.

The value of the iVersion field is initially 1 but may be larger in future versions of SQLite. Additional fields may be appended to this object when the iVersion value is increased. Note that the structure of the sqlite3_vfs object changes in the transaction between SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not modified.

The szOsFile field is the size of the subclassed sqlite3_file structure used by this VFS. mxPathname is the maximum length of a pathname in this VFS.

Registered sqlite3_vfs objects are kept on a linked list formed by the pNext pointer. The sqlite3_vfs_register() and sqlite3_vfs_unregister() interfaces manage this list in a thread-safe way. The sqlite3_vfs_find() interface searches the list. Neither the application code nor the VFS implementation should use the pNext pointer.

The pNext field is the only field in the sqlite3_vfs structure that SQLite will ever modify. SQLite will only access or modify this field while holding a particular static mutex. The application should never modify anything within the sqlite3_vfs object once the object has been registered.

The zName field holds the name of the VFS module. The name must be unique across all VFS modules.

SQLite guarantees that the zFilename parameter to xOpen is either a NULL pointer or string obtained from xFullPathname() with an optional suffix added. If a suffix is added to the zFilename parameter, it will consist of a single "-" character followed by no more than 10 alphanumeric and/or "-" characters. SQLite further guarantees that the string will be valid and unchanged until xClose() is called. Because of the previous sentence, the sqlite3_file can safely store a pointer to the filename if it needs to remember the filename for some reason. If the zFilename parameter to xOpen is a NULL pointer then xOpen must invent its own temporary name for the file. Whenever the xFilename parameter is NULL it will also be the case that the flags parameter will include SQLITE_OPEN_DELETEONCLOSE.

The flags argument to xOpen() includes all bits set in the flags argument to sqlite3_open_v2(). Or if sqlite3_open() or sqlite3_open16() is used, then flags includes at least SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. If xOpen() opens a file read-only then it sets *pOutFlags to include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be set.

SQLite will also add one of the following flags to the xOpen() call, depending on the object being opened:

  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
  • SQLITE_OPEN_WAL

The file I/O implementation can use the object type flags to change the way it deals with files. For example, an application that does not care about crash recovery or rollback might make the open of a journal file a no-op. Writes to this journal would also be no-ops, and any attempt to read the journal would return SQLITE_IOERR. Or the implementation might recognize that a database file will be doing page-aligned sector reads and writes in a random order and set up its I/O subsystem accordingly.

SQLite might also add one of the following flags to the xOpen method:

  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE

The SQLITE_OPEN_DELETEONCLOSE flag means the file should be deleted when it is closed. The SQLITE_OPEN_DELETEONCLOSE will be set for TEMP databases and their journals, transient databases, and subjournals.

The SQLITE_OPEN_EXCLUSIVE flag is always used in conjunction with the SQLITE_OPEN_CREATE flag, which are both directly analogous to the O_EXCL and O_CREAT flags of the POSIX open() API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the SQLITE_OPEN_CREATE, is used to indicate that file should always be created, and that it is an error if it already exists. It is not used to indicate the file should be opened for exclusive access.

At least szOsFile bytes of memory are allocated by SQLite to hold the sqlite3_file structure passed as the third argument to xOpen. The xOpen method does not have to allocate the structure; it should just fill it in. Note that the xOpen method must set the sqlite3_file.pMethods to either a valid sqlite3_io_methods object or to NULL. xOpen must do this even if the open fails. SQLite expects that the sqlite3_file.pMethods element will be valid after xOpen returns regardless of the success or failure of the xOpen call.

The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS to test for the existence of a file, or SQLITE_ACCESS_READWRITE to test whether a file is readable and writable, or SQLITE_ACCESS_READ to test whether a file is at least readable. The file can be a directory.

SQLite will always allocate at least mxPathname+1 bytes for the output buffer xFullPathname. The exact size of the output buffer is also passed as a parameter to both methods. If the output buffer is not large enough, SQLITE_CANTOPEN should be returned. Since this is handled as a fatal error by SQLite, vfs implementations should endeavor to prevent this by setting mxPathname to a sufficiently large value.

The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() interfaces are not strictly a part of the filesystem, but they are included in the VFS structure for completeness. The xRandomness() function attempts to return nBytes bytes of good-quality randomness into zOut. The return value is the actual number of bytes of randomness obtained. The xSleep() method causes the calling thread to sleep for at least the number of microseconds given. The xCurrentTime() method returns a Julian Day Number for the current date and time as a floating point value. The xCurrentTimeInt64() method returns, as an integer, the Julian Day Number multiplied by 86400000 (the number of milliseconds in a 24-hour day). SQLite will use the xCurrentTimeInt64() method to get the current date and time if that method is available (if iVersion is 2 or greater and the function pointer is not NULL) and will fall back to xCurrentTime() if xCurrentTimeInt64() is unavailable.

The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces are not used by the SQLite core. These optional interfaces are provided by some VFSes to facilitate testing of the VFS code. By overriding system calls with functions under its control, a test program can simulate faults and error conditions that would otherwise be difficult or impossible to induce. The set of system calls that can be overridden varies from one VFS to another, and from one version of the same VFS to the next. Applications that use these interfaces must be prepared for any or all of these interfaces to be NULL or for their behavior to change from one release to the next. Applications must not attempt to access any of these methods if the iVersion of the VFS is less than 3.

Virtual Table Instance Object

struct sqlite3_vtab {
  const sqlite3_module *pModule;  /* The module for this virtual table */
  int nRef;                       /* NO LONGER USED */
  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  /* Virtual table implementations will typically add additional fields */
};

Every virtual table module implementation uses a subclass of this object to describe a particular instance of the virtual table. Each subclass will be tailored to the specific needs of the module implementation. The purpose of this superclass is to define certain fields that are common to all module implementations.

Virtual tables methods can set an error message by assigning a string obtained from sqlite3_mprintf() to zErrMsg. The method should take care that any prior string is freed by a call to sqlite3_free() prior to assigning a new string to zErrMsg. After the error message is delivered up to the client application, the string will be automatically freed by sqlite3_free() and the zErrMsg field will be zeroed.

Obtain Aggregate Function Context

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

Implementations of aggregate SQL functions use this routine to allocate memory for storing their state.

The first time the sqlite3_aggregate_context(C,N) routine is called for a particular aggregate function, SQLite allocates N of memory, zeroes out that memory, and returns a pointer to the new memory. On second and subsequent calls to sqlite3_aggregate_context() for the same aggregate function instance, the same buffer is returned. Sqlite3_aggregate_context() is normally called once for each invocation of the xStep callback and then one last time when the xFinal callback is invoked. When no rows match an aggregate query, the xStep() callback of the aggregate function implementation is never called and xFinal() is called exactly once. In those cases, sqlite3_aggregate_context() might be called for the first time from within xFinal().

The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is less than or equal to zero or if a memory allocate error occurs.

The amount of space allocated by sqlite3_aggregate_context(C,N) is determined by the N parameter on first successful call. Changing the value of N in subsequent call to sqlite3_aggregate_context() within the same aggregate function instance will not resize the memory allocation.

SQLite automatically frees the memory allocated by sqlite3_aggregate_context() when the aggregate query concludes.

The first parameter must be a copy of the SQL function context that is the first parameter to the xStep or xFinal callback routine that implements the aggregate function.

This routine must be called from the same thread in which the aggregate SQL function is running.

Automatically Load Statically Linked Extensions

int sqlite3_auto_extension(void (*xEntryPoint)(void));

This interface causes the xEntryPoint() function to be invoked for each new database connection that is created. The idea here is that xEntryPoint() is the entry point for a statically linked SQLite extension that is to be automatically loaded into all new database connections.

Even though the function prototype shows that xEntryPoint() takes no arguments and returns void, SQLite invokes xEntryPoint() with three arguments and expects and integer result as if the signature of the entry point where as follows:

   int xEntryPoint(
     sqlite3 *db,
     const char **pzErrMsg,
     const struct sqlite3_api_routines *pThunk
   );

If the xEntryPoint routine encounters an error, it should make *pzErrMsg point to an appropriate error message (obtained from sqlite3_mprintf()) and return an appropriate error code. SQLite ensures that *pzErrMsg is NULL before calling the xEntryPoint(). SQLite will invoke sqlite3_free() on *pzErrMsg after xEntryPoint() returns. If any xEntryPoint() returns an error, the sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() call that provoked the xEntryPoint() will fail.

Calling sqlite3_auto_extension(X) with an entry point X that is already on the list of automatic extensions is a harmless no-op. No entry point will be called more than once for each database connection that is opened.

See also: sqlite3_reset_auto_extension().

Number Of SQL Parameters

int sqlite3_bind_parameter_count(sqlite3_stmt*);

This routine can be used to find the number of SQL parameters in a prepared statement. SQL parameters are tokens of the form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as placeholders for values that are bound to the parameters at a later time.

This routine actually returns the index of the largest (rightmost) parameter. For all forms except ?NNN, this will correspond to the number of unique parameters. If parameters of the ?NNN form are used, there may be gaps in the list.

See also: sqlite3_bind(),
sqlite3_bind_parameter_name(), and
sqlite3_bind_parameter_index().

Index Of A Parameter With A Given Name

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

Return the index of an SQL parameter given its name. The index value returned is suitable for use as the second parameter to sqlite3_bind(). A zero is returned if no matching parameter is found. The parameter name must be given in UTF-8 even if the original statement was prepared from UTF-16 text using sqlite3_prepare16_v2().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_index().

Name Of A Host Parameter

const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

The sqlite3_bind_parameter_name(P,N) interface returns the name of the N-th SQL parameter in the prepared statement P. SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" respectively. In other words, the initial ":" or "$" or "@" or "?" is included as part of the name. Parameters of the form "?" without a following integer have no name and are referred to as "nameless" or "anonymous parameters".

The first host parameter has an index of 1, not 0.

If the value N is out of range or if the N-th parameter is nameless, then NULL is returned. The returned string is always in UTF-8 encoding even if the named parameter was originally specified as UTF-16 in sqlite3_prepare16() or sqlite3_prepare16_v2().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_index().

Return The Size Of An Open BLOB

int sqlite3_blob_bytes(sqlite3_blob *);

Returns the size in bytes of the BLOB accessible via the successfully opened BLOB handle in its only argument. The incremental blob I/O routines can only read or overwriting existing blob content; they cannot change the size of a blob.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

Close A BLOB Handle

int sqlite3_blob_close(sqlite3_blob *);

Closes an open BLOB handle.

Closing a BLOB shall cause the current transaction to commit if there are no other BLOBs, no pending prepared statements, and the database connection is in autocommit mode. If any writes were made to the BLOB, they might be held in cache until the close operation if they will fit.

Closing the BLOB often forces the changes out to disk and so if any I/O errors occur, they will likely occur at the time when the BLOB is closed. Any errors that occur during closing are reported as a non-zero return value.

The BLOB is closed unconditionally. Even if this routine returns an error code, the BLOB is still closed.

Calling this routine with a null pointer (such as would be returned by a failed call to sqlite3_blob_open()) is a harmless no-op.

Open A BLOB For Incremental I/O

int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

This interfaces opens a handle to the BLOB located in row iRow, column zColumn, table zTable in database zDb; in other words, the same BLOB that would be selected by:

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

If the flags parameter is non-zero, then the BLOB is opened for read and write access. If it is zero, the BLOB is opened for read access. It is not possible to open a column that is part of an index or primary key for writing. If foreign key constraints are enabled, it is not possible to open a column that is part of a child key for writing.

Note that the database name is not the filename that contains the database but rather the symbolic name of the database that appears after the AS keyword when the database is connected using ATTACH. For the main database file, the database name is "main". For TEMP tables, the database name is "temp".

On success, SQLITE_OK is returned and the new BLOB handle is written to *ppBlob. Otherwise an error code is returned and *ppBlob is set to be a null pointer. This function sets the database connection error code and message accessible via sqlite3_errcode() and sqlite3_errmsg() and related functions. Note that the *ppBlob variable is always initialized in a way that makes it safe to invoke sqlite3_blob_close() on *ppBlob regardless of the success or failure of this routine.

If the row that a BLOB handle points to is modified by an UPDATE, DELETE, or by ON CONFLICT side-effects then the BLOB handle is marked as "expired". This is true if any column of the row is changed, even a column other than the one the BLOB handle is open on. Calls to sqlite3_blob_read() and sqlite3_blob_write() for an expired BLOB handle fail with a return code of SQLITE_ABORT. Changes written into a BLOB prior to the BLOB expiring are not rolled back by the expiration of the BLOB. Such changes will eventually commit if the transaction continues to completion.

Use the sqlite3_blob_bytes() interface to determine the size of the opened blob. The size of a blob may not be changed by this interface. Use the UPDATE SQL command to change the size of a blob.

The sqlite3_bind_zeroblob() and sqlite3_result_zeroblob() interfaces and the built-in zeroblob SQL function can be used, if desired, to create an empty, zero-filled blob in which to read or write using this interface.

To avoid a resource leak, every open BLOB handle should eventually be released by a call to sqlite3_blob_close().

Read Data From A BLOB Incrementally

int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

This function is used to read data from an open BLOB handle into a caller-supplied buffer. N bytes of data are copied into buffer Z from the open BLOB, starting at offset iOffset.

If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR is returned and no data is read. If N or iOffset is less than zero, SQLITE_ERROR is returned and no data is read. The size of the blob (and hence the maximum value of N+iOffset) can be determined using the sqlite3_blob_bytes() interface.

An attempt to read from an expired BLOB handle fails with an error code of SQLITE_ABORT.

On success, sqlite3_blob_read() returns SQLITE_OK. Otherwise, an error code or an extended error code is returned.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_write().

Move a BLOB Handle to a New Row

int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);

This function is used to move an existing blob handle so that it points to a different row of the same database table. The new row is identified by the rowid value passed as the second argument. Only the row can be changed. The database, table and column on which the blob handle is open remain the same. Moving an existing blob handle to a new row can be faster than closing the existing handle and opening a new one.

The new row must meet the same criteria as for sqlite3_blob_open() - it must exist and there must be either a blob or text value stored in the nominated column. If the new row is not present in the table, or if it does not contain a blob or text value, or if another error occurs, an SQLite error code is returned and the blob handle is considered aborted. All subsequent calls to sqlite3_blob_read(), sqlite3_blob_write() or sqlite3_blob_reopen() on an aborted blob handle immediately return SQLITE_ABORT. Calling sqlite3_blob_bytes() on an aborted blob handle always returns zero.

This function sets the database handle error code and message.

Write Data Into A BLOB Incrementally

int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

This function is used to write data into an open BLOB handle from a caller-supplied buffer. N bytes of data are copied from the buffer Z into the open BLOB, starting at offset iOffset.

If the BLOB handle passed as the first argument was not opened for writing (the flags parameter to sqlite3_blob_open() was zero), this function returns SQLITE_READONLY.

This function may only modify the contents of the BLOB; it is not possible to increase the size of a BLOB using this API. If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR is returned and no data is written. If N is less than zero SQLITE_ERROR is returned and no data is written. The size of the BLOB (and hence the maximum value of N+iOffset) can be determined using the sqlite3_blob_bytes() interface.

An attempt to write to an expired BLOB handle fails with an error code of SQLITE_ABORT. Writes to the BLOB that occurred before the BLOB handle expired are not rolled back by the expiration of the handle, though of course those changes might have been overwritten by the statement that expired the BLOB handle or by other independent statements.

On success, sqlite3_blob_write() returns SQLITE_OK. Otherwise, an error code or an extended error code is returned.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_read().

Register A Callback To Handle SQLITE_BUSY Errors

int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

This routine sets a callback function that might be invoked whenever an attempt is made to open a database table that another thread or process has locked.

If the busy callback is NULL, then SQLITE_BUSY or SQLITE_IOERR_BLOCKED is returned immediately upon encountering the lock. If the busy callback is not NULL, then the callback might be invoked with two arguments.

The first argument to the busy handler is a copy of the void* pointer which is the third argument to sqlite3_busy_handler(). The second argument to the busy handler callback is the number of times that the busy handler has been invoked for this locking event. If the busy callback returns 0, then no additional attempts are made to access the database and SQLITE_BUSY or SQLITE_IOERR_BLOCKED is returned. If the callback returns non-zero, then another attempt is made to open the database for reading and the cycle repeats.

The presence of a busy handler does not guarantee that it will be invoked when there is lock contention. If SQLite determines that invoking the busy handler could result in a deadlock, it will go ahead and return SQLITE_BUSY or SQLITE_IOERR_BLOCKED instead of invoking the busy handler. Consider a scenario where one process is holding a read lock that it is trying to promote to a reserved lock and a second process is holding a reserved lock that it is trying to promote to an exclusive lock. The first process cannot proceed because it is blocked by the second and the second process cannot proceed because it is blocked by the first. If both processes invoke the busy handlers, neither will make any progress. Therefore, SQLite returns SQLITE_BUSY for the first process, hoping that this will induce the first process to release its read lock and allow the second process to proceed.

The default busy callback is NULL.

The SQLITE_BUSY error is converted to SQLITE_IOERR_BLOCKED when SQLite is in the middle of a large transaction where all the changes will not fit into the in-memory cache. SQLite will already hold a RESERVED lock on the database file, but it needs to promote this lock to EXCLUSIVE so that it can spill cache pages into the database file without harm to concurrent readers. If it is unable to promote the lock, then the in-memory cache will be left in an inconsistent state and so the error code is promoted from the relatively benign SQLITE_BUSY to the more severe SQLITE_IOERR_BLOCKED. This error code promotion forces an automatic rollback of the changes. See the CorruptionFollowingBusyError wiki page for a discussion of why this is important.

There can only be a single busy handler defined for each database connection. Setting a new busy handler clears any previously set handler. Note that calling sqlite3_busy_timeout() will also set or clear the busy handler.

The busy callback should not take any actions which modify the database connection that invoked the busy handler. Any such actions result in undefined behavior.

A busy handler must not close the database connection or prepared statement that invoked the busy handler.

Set A Busy Timeout

int sqlite3_busy_timeout(sqlite3*, int ms);

This routine sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated. After at least "ms" milliseconds of sleeping, the handler returns 0 which causes sqlite3_step() to return SQLITE_BUSY or SQLITE_IOERR_BLOCKED.

Calling this routine with an argument less than or equal to zero turns off all busy handlers.

There can only be a single busy handler for a particular database connection any any given moment. If another busy handler was defined (using sqlite3_busy_handler()) prior to calling this routine, that other busy handler is cleared.

Count The Number Of Rows Modified

int sqlite3_changes(sqlite3*);

This function returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement on the database connection specified by the first parameter. Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted. Auxiliary changes caused by triggers or foreign key actions are not counted. Use the sqlite3_total_changes() function to find the total number of changes including changes caused by triggers and foreign key actions.

Changes to a view that are simulated by an INSTEAD OF trigger are not counted. Only real table changes are counted.

A "row change" is a change to a single row of a single table caused by an INSERT, DELETE, or UPDATE statement. Rows that are changed as side effects of REPLACE constraint resolution, rollback, ABORT processing, DROP TABLE, or by any other mechanisms do not count as direct row changes.

A "trigger context" is a scope of execution that begins and ends with the script of a trigger. Most SQL statements are evaluated outside of any trigger. This is the "top level" trigger context. If a trigger fires from the top level, a new trigger context is entered for the duration of that one trigger. Subtriggers create subcontexts for their duration.

Calling sqlite3_exec() or sqlite3_step() recursively does not create a new trigger context.

This function returns the number of direct row changes in the most recent INSERT, UPDATE, or DELETE statement within the same trigger context.

Thus, when called from the top level, this function returns the number of changes in the most recent INSERT, UPDATE, or DELETE that also occurred at the top level. Within the body of a trigger, the sqlite3_changes() interface can be called to find the number of changes in the most recently completed INSERT, UPDATE, or DELETE statement within the body of the same trigger. However, the number returned does not include changes caused by subtriggers since those have their own context.

See also the sqlite3_total_changes() interface, the count_changes pragma, and the changes() SQL function.

If a separate thread makes changes on the same database connection while sqlite3_changes() is running then the value returned is unpredictable and not meaningful.

Reset All Bindings On A Prepared Statement

int sqlite3_clear_bindings(sqlite3_stmt*);

Contrary to the intuition of many, sqlite3_reset() does not reset the bindings on a prepared statement. Use this routine to reset all host parameters to NULL.

Closing A Database Connection

int sqlite3_close(sqlite3 *);

The sqlite3_close() routine is the destructor for the sqlite3 object. Calls to sqlite3_close() return SQLITE_OK if the sqlite3 object is successfully destroyed and all associated resources are deallocated.

Applications must finalize all prepared statements and close all BLOB handles associated with the sqlite3 object prior to attempting to close the object. If sqlite3_close() is called on a database connection that still has outstanding prepared statements or BLOB handles, then it returns SQLITE_BUSY.

If sqlite3_close() is invoked while a transaction is open, the transaction is automatically rolled back.

The C parameter to sqlite3_close(C) must be either a NULL pointer or an sqlite3 object pointer obtained from sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(), and not previously closed. Calling sqlite3_close() with a NULL pointer argument is a harmless no-op.

Number Of Columns In A Result Set

int sqlite3_column_count(sqlite3_stmt *pStmt);

Return the number of columns in the result set returned by the prepared statement. This routine returns 0 if pStmt is an SQL statement that does not return data (for example an UPDATE).

See also: sqlite3_data_count()

Configuring The SQLite Library

int sqlite3_config(int, ...);

The sqlite3_config() interface is used to make global configuration changes to SQLite in order to tune SQLite to the specific needs of the application. The default configuration is recommended for most applications and so this routine is usually not necessary. It is provided to support rare applications with unusual needs.

The sqlite3_config() interface is not threadsafe. The application must insure that no other SQLite interfaces are invoked by other threads while sqlite3_config() is running. Furthermore, sqlite3_config() may only be invoked prior to library initialization using sqlite3_initialize() or after shutdown by sqlite3_shutdown(). If sqlite3_config() is called after sqlite3_initialize() and before sqlite3_shutdown() then it will return SQLITE_MISUSE. Note, however, that sqlite3_config() can be called as part of the implementation of an application-defined sqlite3_os_init().

The first argument to sqlite3_config() is an integer configuration option that determines what property of SQLite is to be configured. Subsequent arguments vary depending on the configuration option in the first argument.

When a configuration option is set, sqlite3_config() returns SQLITE_OK. If the option is unknown or SQLite is unable to set the option then this routine returns a non-zero error code.

Database Connection For Functions

sqlite3 *sqlite3_context_db_handle(sqlite3_context*);

The sqlite3_context_db_handle() interface returns a copy of the pointer to the database connection (the 1st parameter) of the sqlite3_create_function() and sqlite3_create_function16() routines that originally registered the application defined function.

Number of columns in a result set

int sqlite3_data_count(sqlite3_stmt *pStmt);

The sqlite3_data_count(P) interface returns the number of columns in the current row of the result set of prepared statement P. If prepared statement P does not have results ready to return (via calls to the sqlite3_column_*() of interfaces) then sqlite3_data_count(P) returns 0. The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. The sqlite3_data_count(P) routine returns 0 if the previous call to sqlite3_step(P) returned SQLITE_DONE. The sqlite3_data_count(P) will return non-zero if previous call to sqlite3_step(P) returned SQLITE_ROW, except in the case of the PRAGMA incremental_vacuum where it always returns zero since each step of that multi-step pragma returns 0 columns of data.

See also: sqlite3_column_count()

Configure database connections

int sqlite3_db_config(sqlite3*, int op, ...);

The sqlite3_db_config() interface is used to make configuration changes to a database connection. The interface is similar to sqlite3_config() except that the changes apply to a single database connection (specified in the first argument).

The second argument to sqlite3_db_config(D,V,...) is the configuration verb - an integer code that indicates what aspect of the database connection is being configured. Subsequent arguments vary depending on the configuration verb.

Calls to sqlite3_db_config() return SQLITE_OK if and only if the call is considered successful.

Find The Database Handle Of A Prepared Statement

sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

The sqlite3_db_handle interface returns the database connection handle to which a prepared statement belongs. The database connection returned by sqlite3_db_handle is the same database connection that was the first argument to the sqlite3_prepare_v2() call (or its variants) that was used to create the statement in the first place.

Retrieve the mutex for a database connection

sqlite3_mutex *sqlite3_db_mutex(sqlite3*);

This interface returns a pointer the sqlite3_mutex object that serializes access to the database connection given in the argument when the threading mode is Serialized. If the threading mode is Single-thread or Multi-thread then this routine returns a NULL pointer.

Database Connection Status

int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);

This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQLITE_DBSTATUS options, that determines the parameter to interrogate. The set of SQLITE_DBSTATUS options is likely to grow in future releases of SQLite.

The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.

The sqlite3_db_status() routine returns SQLITE_OK on success and a non-zero error code on failure.

See also: sqlite3_status() and sqlite3_stmt_status().

Declare The Schema Of A Virtual Table

int sqlite3_declare_vtab(sqlite3*, const char *zSQL);

The xCreate and xConnect methods of a virtual table module call this interface to declare the format (the names and datatypes of the columns) of the virtual tables they implement.

Enable Or Disable Extension Loading

int sqlite3_enable_load_extension(sqlite3 *db, int onoff);

So as not to open security holes in older applications that are unprepared to deal with extension loading, and as a means of disabling extension loading while evaluating user-entered SQL, the following API is provided to turn the sqlite3_load_extension() mechanism on and off.

Extension loading is off by default. See ticket #1863. Call the sqlite3_enable_load_extension() routine with onoff==1 to turn extension loading on and call it with onoff==0 to turn it back off again.

One-Step Query Execution Interface

int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

The sqlite3_exec() interface is a convenience wrapper around sqlite3_prepare_v2(), sqlite3_step(), and sqlite3_finalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code.

The sqlite3_exec() interface runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed into its 2nd argument, in the context of the database connection passed in as its 1st argument. If the callback function of the 3rd argument to sqlite3_exec() is not NULL, then it is invoked for each result row coming out of the evaluated SQL statements. The 4th argument to sqlite3_exec() is relayed through to the 1st argument of each callback invocation. If the callback pointer to sqlite3_exec() is NULL, then no callback is ever invoked and result rows are ignored.

If an error occurs while evaluating the SQL statements passed into sqlite3_exec(), then execution of the current statement stops and subsequent statements are skipped. If the 5th parameter to sqlite3_exec() is not NULL then any error message is written into memory obtained from sqlite3_malloc() and passed back through the 5th parameter. To avoid memory leaks, the application should invoke sqlite3_free() on error message strings returned through the 5th parameter of of sqlite3_exec() after the error message string is no longer needed. If the 5th parameter to sqlite3_exec() is not NULL and no errors occur, then sqlite3_exec() sets the pointer in its 5th parameter to NULL before returning.

If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() routine returns SQLITE_ABORT without invoking the callback again and without running any subsequent SQL statements.

The 2nd argument to the sqlite3_exec() callback function is the number of columns in the result. The 3rd argument to the sqlite3_exec() callback is an array of pointers to strings obtained as if from sqlite3_column_text(), one for each column. If an element of a result row is NULL then the corresponding string pointer for the sqlite3_exec() callback is a NULL pointer. The 4th argument to the sqlite3_exec() callback is an array of pointers to strings where each entry represents the name of corresponding result column as obtained from sqlite3_column_name().

If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer to an empty string, or a pointer that contains only whitespace and/or SQL comments, then no SQL statements are evaluated and the database is not changed.

Restrictions:

  • The application must insure that the 1st parameter to sqlite3_exec() is a valid and open database connection.
  • The application must not close database connection specified by the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
  • The application must not modify the SQL statement text passed into the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.

Enable Or Disable Extended Result Codes

int sqlite3_extended_result_codes(sqlite3*, int onoff);

The sqlite3_extended_result_codes() routine enables or disables the extended result codes feature of SQLite. The extended result codes are disabled by default for historical compatibility.

Low-Level Control Of Database Files

int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

The sqlite3_file_control() interface makes a direct call to the xFileControl method for the sqlite3_io_methods object associated with a particular database identified by the second argument. The name of the database is "main" for the main database or "temp" for the TEMP database, or the name that appears after the AS keyword for databases that are added using the ATTACH SQL command. A NULL pointer can be used in place of "main" to refer to the main database file. The third and fourth parameters to this routine are passed directly through to the second and third parameters of the xFileControl method. The return value of the xFileControl method becomes the return value of this routine.

The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes a pointer to the underlying sqlite3_file object to be written into the space pointed to by the 4th parameter. The SQLITE_FCNTL_FILE_POINTER case is a short-circuit path which does not actually invoke the underlying sqlite3_io_methods.xFileControl method.

If the second parameter (zDbName) does not match the name of any open database file, then SQLITE_ERROR is returned. This error code is not remembered and will not be recalled by sqlite3_errcode() or sqlite3_errmsg(). The underlying xFileControl method might also return SQLITE_ERROR. There is no way to distinguish between an incorrect zDbName and an SQLITE_ERROR return from the underlying xFileControl method.

See also: SQLITE_FCNTL_LOCKSTATE

Destroy A Prepared Statement Object

int sqlite3_finalize(sqlite3_stmt *pStmt);

The sqlite3_finalize() function is called to delete a prepared statement. If the most recent evaluation of the statement encountered no errors or if the statement is never been evaluated, then sqlite3_finalize() returns SQLITE_OK. If the most recent evaluation of statement S failed, then sqlite3_finalize(S) returns the appropriate error code or extended error code.

The sqlite3_finalize(S) routine can be called at any point during the life cycle of prepared statement S: before statement S is ever evaluated, after one or more calls to sqlite3_reset(), or after any call to sqlite3_step() regardless of whether or not the statement has completed execution.

Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.

The application must finalize every prepared statement in order to avoid resource leaks. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption.

Interrupt A Long-Running Query

void sqlite3_interrupt(sqlite3*);

This function causes any pending database operation to abort and return at its earliest opportunity. This routine is typically called in response to a user action such as pressing "Cancel" or Ctrl-C where the user wants a long query operation to halt immediately.

It is safe to call this routine from a thread different from the thread that is currently running the database operation. But it is not safe to call this routine with a database connection that is closed or might close before sqlite3_interrupt() returns.

If an SQL operation is very nearly finished at the time when sqlite3_interrupt() is called, then it might not have an opportunity to be interrupted and might continue to completion.

An SQL operation that is interrupted will return SQLITE_INTERRUPT. If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that is inside an explicit transaction, then the entire transaction will be rolled back automatically.

The sqlite3_interrupt(D) call is in effect until all currently running SQL statements on database connection D complete. Any new SQL statements that are started after the sqlite3_interrupt() call and before the running statements reaches zero are interrupted as if they had been running prior to the sqlite3_interrupt() call. New SQL statements that are started after the running statement count reaches zero are not effected by the sqlite3_interrupt(). A call to sqlite3_interrupt(D) that occurs when there are no running SQL statements is a no-op and has no effect on SQL statements that are started after the sqlite3_interrupt() call returns.

If the database connection closes while sqlite3_interrupt() is running then bad things will likely happen.

Last Insert Rowid

sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);

Each entry in an SQLite table has a unique 64-bit signed integer key called the "rowid". The rowid is always available as an undeclared column named ROWID, OID, or _ROWID_ as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.

This routine returns the rowid of the most recent successful INSERT into the database from the database connection in the first argument. As of SQLite version 3.7.7, this routines records the last insert rowid of both ordinary tables and virtual tables. If no successful INSERTs have ever occurred on that database connection, zero is returned.

If an INSERT occurs within a trigger or within a virtual table method, then this routine will return the rowid of the inserted row as long as the trigger or virtual table method is running. But once the trigger or virtual table method ends, the value returned by this routine reverts to what it was before the trigger or virtual table method began.

An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.

For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.

This function is accessible to SQL statements via the last_insert_rowid() SQL function.

If a separate thread performs a new INSERT on the same database connection while the sqlite3_last_insert_rowid() function is running and thus changes the last insert rowid, then the value returned by sqlite3_last_insert_rowid() is unpredictable and might not equal either the old or the new last insert rowid.

Run-time Limits

int sqlite3_limit(sqlite3*, int id, int newVal);

This interface allows the size of various constructs to be limited on a connection by connection basis. The first parameter is the database connection whose limit is to be set or queried. The second parameter is one of the limit categories that define a class of constructs to be size limited. The third parameter is the new limit for that construct.

If the new limit is a negative number, the limit is unchanged. For each limit category SQLITE_LIMIT_NAME there is a hard upper bound set at compile-time by a C preprocessor macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to "_MAX_".) Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound.

Regardless of whether or not the limit was changed, the sqlite3_limit() interface returns the prior value of the limit. Hence, to find the current value of a limit without changing it, simply invoke this interface with the third parameter set to -1.

Run-time limits are intended for use in applications that manage both their own internal database and also databases that are controlled by untrusted external sources. An example application might be a web browser that has its own databases for storing history and separate databases controlled by JavaScript applications downloaded off the Internet. The internal databases can be given the large, default limits. Databases managed by external sources can be given much smaller limits designed to prevent a denial of service attack. Developers might also want to use the sqlite3_set_authorizer() interface to further control untrusted SQL. The size of the database created by an untrusted script can be contained using the max_page_count PRAGMA.

New run-time limit categories may be added in future releases.

Load An Extension

int sqlite3_load_extension(
  sqlite3 *db,          /* Load the extension into this database connection */
  const char *zFile,    /* Name of the shared library containing extension */
  const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  char **pzErrMsg       /* Put error message here if not 0 */
);

This interface loads an SQLite extension library from the named file.

The sqlite3_load_extension() interface attempts to load an SQLite extension library contained in the file zFile.

The entry point is zProc. zProc may be 0, in which case the name of the entry point defaults to "sqlite3_extension_init". The sqlite3_load_extension() interface returns SQLITE_OK on success and SQLITE_ERROR if something goes wrong. If an error occurs and pzErrMsg is not 0, then the sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with error message text stored in memory obtained from sqlite3_malloc(). The calling function should free this memory by calling sqlite3_free().

Extension loading must be enabled using sqlite3_enable_load_extension() prior to calling this API, otherwise an error will be returned.

See also the load_extension() SQL function.

Error Logging Interface

void sqlite3_log(int iErrCode, const char *zFormat, ...);

The sqlite3_log() interface writes a message into the error log established by the SQLITE_CONFIG_LOG option to sqlite3_config(). If logging is enabled, the zFormat string and subsequent arguments are used with sqlite3_snprintf() to generate the final output string.

The sqlite3_log() interface is intended for use by extensions such as virtual tables, collating functions, and SQL functions. While there is nothing to prevent an application from calling sqlite3_log(), doing so is considered bad form.

The zFormat string must not be NULL.

To avoid deadlocks and other threading problems, the sqlite3_log() routine will not use dynamically allocated memory. The log message is stored in a fixed-length buffer on the stack. If the log message is longer than a few hundred characters, it will be truncated to the length of the buffer.

Find the next prepared statement

sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);

This interface returns a pointer to the next prepared statement after pStmt associated with the database connection pDb. If pStmt is NULL then this interface returns a pointer to the first prepared statement associated with the database connection pDb. If no prepared statement satisfies the conditions of this routine, it returns NULL.

The database connection pointer D in a call to sqlite3_next_stmt(D,S) must refer to an open database connection and in particular must not be a NULL pointer.

Overload A Function For A Virtual Table

int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);

Virtual tables can provide alternative implementations of functions using the xFindFunction method of the virtual table module. But global versions of those functions must exist in order to be overloaded.

This API makes sure a global version of a function with a particular name and number of parameters exists. If no such function exists before this API is called, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself. Its only purpose is to be a placeholder function that can be overloaded by a virtual table.

Query Progress Callbacks

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

The sqlite3_progress_handler(D,N,X,P) interface causes the callback function X to be invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table() for database connection D. An example use for this interface is to keep a GUI updated during a large query.

The parameter P is passed through as the only parameter to the callback function X. The parameter N is the number of virtual machine instructions that are evaluated between successive invocations of the callback X.

Only a single progress handler may be defined at one time per database connection; setting a new progress handler cancels the old one. Setting parameter X to NULL disables the progress handler. The progress handler is also disabled by setting N to a value less than 1.

If the progress callback returns non-zero, the operation is interrupted. This feature can be used to implement a "Cancel" button on a GUI progress dialog box.

The progress handler callback must not do anything that will modify the database connection that invoked the progress handler. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

Pseudo-Random Number Generator

void sqlite3_randomness(int N, void *P);

SQLite contains a high-quality pseudo-random number generator (PRNG) used to select random ROWIDs when inserting new records into a table that already uses the largest possible ROWID. The PRNG is also used for the build-in random() and randomblob() SQL functions. This interface allows applications to access the same PRNG for other purposes.

A call to this routine stores N bytes of randomness into buffer P.

The first time this routine is invoked (either internally or by the application) the PRNG is seeded using randomness obtained from the xRandomness method of the default sqlite3_vfs object. On all subsequent invocations, the pseudo-randomness is generated internally and without recourse to the sqlite3_vfs xRandomness method.

Attempt To Free Heap Memory

int sqlite3_release_memory(int);

The sqlite3_release_memory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database library. Memory used to cache database pages to improve performance is an example of non-essential memory. sqlite3_release_memory() returns the number of bytes actually freed, which might be more or less than the amount requested. The sqlite3_release_memory() routine is a no-op returning zero if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.

Reset A Prepared Statement Object

int sqlite3_reset(sqlite3_stmt *pStmt);

The sqlite3_reset() function is called to reset a prepared statement object back to its initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind_*() API retain their values. Use sqlite3_clear_bindings() to reset the bindings.

The sqlite3_reset(S) interface resets the prepared statement S back to the beginning of its program.

If the most recent call to sqlite3_step(S) for the prepared statement S returned SQLITE_ROW or SQLITE_DONE, or if sqlite3_step(S) has never before been called on S, then sqlite3_reset(S) returns SQLITE_OK.

If the most recent call to sqlite3_step(S) for the prepared statement S indicated an error, then sqlite3_reset(S) returns an appropriate error code.

The sqlite3_reset(S) interface does not change the values of any bindings on the prepared statement S.

Reset Automatic Extension Loading

void sqlite3_reset_auto_extension(void);

This interface disables all automatic extensions previously registered using sqlite3_auto_extension().

Compile-Time Authorization Callbacks

int sqlite3_set_authorizer(
  sqlite3*,
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  void *pUserData
);

This routine registers an authorizer callback with a particular database connection, supplied in the first argument. The authorizer callback is invoked as SQL statements are being compiled by sqlite3_prepare() or its variants sqlite3_prepare_v2(), sqlite3_prepare16() and sqlite3_prepare16_v2(). At various points during the compilation process, as logic is being created to perform various actions, the authorizer callback is invoked to see if those actions are allowed. The authorizer callback should return SQLITE_OK to allow the action, SQLITE_IGNORE to disallow the specific action but allow the SQL statement to continue to be compiled, or SQLITE_DENY to cause the entire SQL statement to be rejected with an error. If the authorizer callback returns any value other than SQLITE_IGNORE, SQLITE_OK, or SQLITE_DENY then the sqlite3_prepare_v2() or equivalent call that triggered the authorizer will fail with an error message.

When the callback returns SQLITE_OK, that means the operation requested is ok. When the callback returns SQLITE_DENY, the sqlite3_prepare_v2() or equivalent call that triggered the authorizer will fail with an error message explaining that access is denied.

The first parameter to the authorizer callback is a copy of the third parameter to the sqlite3_set_authorizer() interface. The second parameter to the callback is an integer action code that specifies the particular action to be authorized. The third through sixth parameters to the callback are zero-terminated strings that contain additional details about the action to be authorized.

If the action code is SQLITE_READ and the callback returns SQLITE_IGNORE then the prepared statement statement is constructed to substitute a NULL value in place of the table column that would have been read if SQLITE_OK had been returned. The SQLITE_IGNORE return can be used to deny an untrusted user access to individual columns of a table. If the action code is SQLITE_DELETE and the callback returns SQLITE_IGNORE then the DELETE operation proceeds but the truncate optimization is disabled and all rows are deleted individually.

An authorizer is used when preparing SQL statements from an untrusted source, to ensure that the SQL statements do not try to access data they are not allowed to see, or that they do not try to execute malicious statements that damage the database. For example, an application may allow a user to enter arbitrary SQL queries for evaluation by a database. But the application does not want the user to be able to make arbitrary changes to the database. An authorizer could then be put in place while the user-entered SQL is being prepared that disallows everything except SELECT statements.

Applications that need to process SQL from untrusted sources might also consider lowering resource limits using sqlite3_limit() and limiting database size using the max_page_count PRAGMA in addition to using an authorizer.

Only a single authorizer can be in place on a database connection at a time. Each call to sqlite3_set_authorizer overrides the previous call. Disable the authorizer by installing a NULL callback. The authorizer is disabled by default.

The authorizer callback must not do anything that will modify the database connection that invoked the authorizer callback. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

When sqlite3_prepare_v2() is used to prepare a statement, the statement might be re-prepared during sqlite3_step() due to a schema change. Hence, the application should ensure that the correct authorizer callback remains in place during the sqlite3_step().

Note that the authorizer callback is invoked only during sqlite3_prepare() or its variants. Authorization is not performed during statement evaluation in sqlite3_step(), unless as stated in the previous paragraph, sqlite3_step() invokes sqlite3_prepare_v2() to reprepare a statement after a schema change.

Suspend Execution For A Short Time

int sqlite3_sleep(int);

The sqlite3_sleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter.

If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. The number of milliseconds of sleep actually requested from the operating system is returned.

SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. If the xSleep() method of the default VFS is not implemented correctly, or not implemented at all, then the behavior of sqlite3_sleep() may deviate from the description in the previous paragraphs.

Deprecated Soft Heap Limit Interface

void sqlite3_soft_heap_limit(int N);

This is a deprecated version of the sqlite3_soft_heap_limit64() interface. This routine is provided for historical compatibility only. All new applications should use the sqlite3_soft_heap_limit64() interface rather than this one.

Impose A Limit On Heap Size

sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);

The sqlite3_soft_heap_limit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQLITE_NOMEM error. In other words, the soft heap limit is advisory only.

The return value from sqlite3_soft_heap_limit64() is the size of the soft heap limit prior to the call. If the argument N is negative then no change is made to the soft heap limit. Hence, the current size of the soft heap limit can be determined by invoking sqlite3_soft_heap_limit64() with a negative argument.

If the argument N is zero then the soft heap limit is disabled.

The soft heap limit is not enforced in the current implementation if one or more of following conditions are true:

  • The soft heap limit is set to zero.
  • Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) start-time option and the SQLITE_DEFAULT_MEMSTATUS compile-time option.
  • An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE,...).
  • The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) rather than from the heap.

Beginning with SQLite version 3.7.3, the soft heap limit is enforced regardless of whether or not the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option is invoked. With SQLITE_ENABLE_MEMORY_MANAGEMENT, the soft heap limit is enforced on every memory allocation. Without SQLITE_ENABLE_MEMORY_MANAGEMENT, the soft heap limit is only enforced when memory is allocated by the page cache. Testing suggests that because the page cache is the predominate memory user in SQLite, most applications will achieve adequate soft heap limit enforcement without the use of SQLITE_ENABLE_MEMORY_MANAGEMENT.

The circumstances under which SQLite will enforce the soft heap limit may changes in future releases of SQLite.

Retrieving Statement SQL

const char *sqlite3_sql(sqlite3_stmt *pStmt);

This interface can be used to retrieve a saved copy of the original SQL text used to create a prepared statement if that statement was compiled using either sqlite3_prepare_v2() or sqlite3_prepare16_v2().

SQLite Runtime Status

int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);

This interface is used to retrieve runtime status information about the performance of SQLite, and optionally to reset various highwater marks. The first argument is an integer code for the specific parameter to measure. Recognized integer codes are of the form SQLITE_STATUS_.... The current value of the parameter is returned into *pCurrent. The highest recorded value is returned in *pHighwater. If the resetFlag is true, then the highest record value is reset after *pHighwater is written. Some parameters do not record the highest value. For those parameters nothing is written into *pHighwater and the resetFlag is ignored. Other parameters record only the highwater mark and not the current value. For these latter parameters nothing is written into *pCurrent.

The sqlite3_status() routine returns SQLITE_OK on success and a non-zero error code on failure.

This routine is threadsafe but is not atomic. This routine can be called while other threads are running the same or different SQLite interfaces. However the values returned in *pCurrent and *pHighwater reflect the status of SQLite at different points in time and it is possible that another thread might change the parameter in between the times when *pCurrent and *pHighwater are written.

See also: sqlite3_db_status()

Evaluate An SQL Statement

int sqlite3_step(sqlite3_stmt*);

After a prepared statement has been prepared using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() or one of the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(), this function must be called one or more times to evaluate the statement.

The details of the behavior of the sqlite3_step() interface depend on whether the statement was prepared using the newer "v2" interface sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy interface sqlite3_prepare() and sqlite3_prepare16(). The use of the new "v2" interface is recommended for new applications but the legacy interface will continue to be supported.

In the legacy interface, the return value will be either SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. With the "v2" interface, any of the other result codes or extended result codes might be returned as well.

SQLITE_BUSY means that the database engine was unable to acquire the database locks it needs to do its job. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within an explicit transaction then you should rollback the transaction before continuing.

SQLITE_DONE means that the statement has finished executing successfully. sqlite3_step() should not be called again on this virtual machine without first calling sqlite3_reset() to reset the virtual machine back to its initial state.

If the SQL statement being executed returns any data, then SQLITE_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. sqlite3_step() is called again to retrieve the next row of data.

SQLITE_ERROR means that a run-time error (such as a constraint violation) has occurred. sqlite3_step() should not be called again on the VM. More information may be found by calling sqlite3_errmsg(). With the legacy interface, a more specific error code (for example, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, and so forth) can be obtained by calling sqlite3_reset() on the prepared statement. In the "v2" interface, the more specific error code is returned directly by sqlite3_step().

SQLITE_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a prepared statement that has already been finalized or on one that had previously returned SQLITE_ERROR or SQLITE_DONE. Or it could be the case that the same database connection is being used by two or more threads at the same moment in time.

For all versions of SQLite up to and including 3.6.23.1, a call to sqlite3_reset() was required after sqlite3_step() returned anything other than SQLITE_ROW before any subsequent invocation of sqlite3_step(). Failure to reset the prepared statement using sqlite3_reset() would result in an SQLITE_MISUSE return from sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began calling sqlite3_reset() automatically in this circumstance rather than returning SQLITE_MISUSE. This is not considered a compatibility break because any application that ever receives an SQLITE_MISUSE error is broken by definition. The SQLITE_OMIT_AUTORESET compile-time option can be used to restore the legacy behavior.

Goofy Interface Alert: In the legacy interface, the sqlite3_step() API always returns a generic error code, SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE. You must call sqlite3_reset() or sqlite3_finalize() in order to find one of the specific error codes that better describes the error. We admit that this is a goofy design. The problem has been fixed with the "v2" interface. If you prepare all of your SQL statements using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead of the legacy sqlite3_prepare() and sqlite3_prepare16() interfaces, then the more specific error codes are returned directly by sqlite3_step(). The use of the "v2" interface is recommended.

Determine If An SQL Statement Writes The Database

int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);

The sqlite3_stmt_readonly(X) interface returns true (non-zero) if and only if the prepared statement X makes no direct changes to the content of the database file.

Note that application-defined SQL functions or virtual tables might change the database indirectly as a side effect. For example, if an application defines a function "eval()" that calls sqlite3_exec(), then the following SQL statement would change the database file through side-effects:

SELECT eval('DELETE FROM t1') FROM t2;

But because the SELECT statement does not change the database file directly, sqlite3_stmt_readonly() would still return true.

Transaction control statements such as BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE cause sqlite3_stmt_readonly() to return true, since the statements themselves do not actually modify the database but rather they control the timing of when other statements modify the database. The ATTACH and DETACH statements also cause sqlite3_stmt_readonly() to return true since, while those statements change the configuration of a database connection, they do not make changes to the content of the database files on disk.

Prepared Statement Status

int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);

Each prepared statement maintains various SQLITE_STMTSTATUS counters that measure the number of times it has performed specific operations. These counters can be used to monitor the performance characteristics of the prepared statements. For example, if the number of table steps greatly exceeds the number of table searches or result rows, that would tend to indicate that the prepared statement is using a full table scan rather than an index.

This interface is used to retrieve and reset counter values from a prepared statement. The first argument is the prepared statement object to be interrogated. The second argument is an integer code for a specific SQLITE_STMTSTATUS counter to be interrogated. The current value of the requested counter is returned. If the resetFlg is true, then the counter is reset to zero after this interface call returns.

See also: sqlite3_status() and sqlite3_db_status().

String Comparison

int sqlite3_strnicmp(const char *, const char *, int);

The sqlite3_strnicmp() API allows applications and extensions to compare the contents of two buffers containing UTF-8 strings in a case-independent fashion, using the same definition of case independence that SQLite uses internally when comparing identifiers.

Extract Metadata About A Column Of A Table

int sqlite3_table_column_metadata(
  sqlite3 *db,                /* Connection handle */
  const char *zDbName,        /* Database name or NULL */
  const char *zTableName,     /* Table name */
  const char *zColumnName,    /* Column name */
  char const **pzDataType,    /* OUTPUT: Declared data type */
  char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
  int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
  int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
  int *pAutoinc               /* OUTPUT: True if column is auto-increment */
);

This routine returns metadata about a specific column of a specific database table accessible using the database connection handle passed as the first function argument.

The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp", or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm used by the database engine to resolve unqualified table references.

The third and fourth parameters to this function are the table and column name of the desired column, respectively. Neither of these parameters may be NULL.

Metadata is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of metadata is omitted.

Parameter Output
Type 		Description

5th | const char* | Data type
6th | const char* | Name of default collation sequence
7th | int | True if column has a NOT NULL constraint
8th | int | True if column is part of the PRIMARY KEY
9th | int | True if column is AUTOINCREMENT

The memory pointed to by the character pointers returned for the declaration type and collation sequence is valid only until the next call to any SQLite API function.

If the specified table is actually a view, an error code is returned.

If the specified column is "rowid", "oid" or "_rowid_" and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no explicitly declared INTEGER PRIMARY KEY column, then the output parameters are set as follows:

data type: "INTEGER"
collation sequence: "BINARY"
not null: 0
primary key: 1
auto increment: 0

This function may load one or more schemas from database files. If an error occurs during this process, or if the requested table or column cannot be found, an error code is returned and an error message left in the database connection (to be retrieved using sqlite3_errmsg()).

This API is only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol defined.

Testing Interface

int sqlite3_test_control(int op, ...);

The sqlite3_test_control() interface is used to read out internal state of SQLite and to inject faults into SQLite for testing purposes. The first parameter is an operation code that determines the number, meaning, and operation of all subsequent parameters.

This interface is not for use by applications. It exists solely for verifying the correct operation of the SQLite library. Depending on how the SQLite library is compiled, this interface might not exist.

The details of the operation codes, their meanings, the parameters they take, and what they do are all subject to change without notice. Unlike most of the SQLite API, this function is not guaranteed to operate consistently from one release to the next.

Test To See If The Library Is Threadsafe

int sqlite3_threadsafe(void);

The sqlite3_threadsafe() function returns zero if and only if SQLite was compiled mutexing code omitted due to the SQLITE_THREADSAFE compile-time option being set to 0.

SQLite can be compiled with or without mutexes. When the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes are enabled and SQLite is threadsafe. When the SQLITE_THREADSAFE macro is 0, the mutexes are omitted. Without the mutexes, it is not safe to use SQLite concurrently from more than one thread.

Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes. But for maximum safety, mutexes should be enabled. The default behavior is for mutexes to be enabled.

This interface can be used by an application to make sure that the version of SQLite that it is linking against was compiled with the desired setting of the SQLITE_THREADSAFE macro.

This interface only reports on the compile-time mutex setting of the SQLITE_THREADSAFE flag. If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but can be fully or partially disabled using a call to sqlite3_config() with the verbs SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, or SQLITE_CONFIG_MUTEX. The return value of the sqlite3_threadsafe() function shows only the compile-time setting of thread safety, not any run-time changes to that setting made by sqlite3_config(). In other words, the return value from sqlite3_threadsafe() is unchanged by calls to sqlite3_config().

See the threading mode documentation for additional information.

Total Number Of Rows Modified

int sqlite3_total_changes(sqlite3*);

This function returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened. The count returned by sqlite3_total_changes() includes all changes from all trigger contexts and changes made by foreign key actions. However, the count does not include changes used to implement REPLACE constraints, do rollbacks or ABORT processing, or DROP TABLE processing. The count does not include rows of views that fire an INSTEAD OF trigger, though if the INSTEAD OF trigger makes changes of its own, those changes are counted. The sqlite3_total_changes() function counts the changes as soon as the statement that makes them is completed (when the statement handle is passed to sqlite3_reset() or sqlite3_finalize()).

See also the sqlite3_changes() interface, the count_changes pragma, and the total_changes() SQL function.

If a separate thread makes changes on the same database connection while sqlite3_total_changes() is running then the value returned is unpredictable and not meaningful.

Unlock Notification

int sqlite3_unlock_notify(
  sqlite3 *pBlocked,                          /* Waiting connection */
  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
  void *pNotifyArg                            /* Argument to pass to xNotify */
);

When running in shared-cache mode, a database operation may fail with an SQLITE_LOCKED error if the required locks on the shared-cache or individual tables within the shared-cache cannot be obtained. See SQLite Shared-Cache Mode for a description of shared-cache locking. This API may be used to register a callback that SQLite will invoke when the connection currently holding the required lock relinquishes it. This API is only available if the library was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor symbol defined.

See Also: Using the SQLite Unlock Notification Feature.

Shared-cache locks are released when a database connection concludes its current transaction, either by committing it or rolling it back.

When a connection (known as the blocked connection) fails to obtain a shared-cache lock and SQLITE_LOCKED is returned to the caller, the identity of the database connection (the blocking connection) that has locked the required resource is stored internally. After an application receives an SQLITE_LOCKED error, it may call the sqlite3_unlock_notify() method with the blocked connection handle as the first argument to register for a callback that will be invoked when the blocking connections current transaction is concluded. The callback is invoked from within the sqlite3_step or sqlite3_close call that concludes the blocking connections transaction.

If sqlite3_unlock_notify() is called in a multi-threaded application, there is a chance that the blocking connection will have already concluded its transaction by the time sqlite3_unlock_notify() is invoked. If this happens, then the specified callback is invoked immediately, from within the call to sqlite3_unlock_notify().

If the blocked connection is attempting to obtain a write-lock on a shared-cache table, and more than one other connection currently holds a read-lock on the same table, then SQLite arbitrarily selects one of the other connections to use as the blocking connection.

There may be at most one unlock-notify callback registered by a blocked connection. If sqlite3_unlock_notify() is called when the blocked connection already has a registered unlock-notify callback, then the new callback replaces the old. If sqlite3_unlock_notify() is called with a NULL pointer as its second argument, then any existing unlock-notify callback is canceled. The blocked connections unlock-notify callback may also be canceled by closing the blocked connection using sqlite3_close().

The unlock-notify callback is not reentrant. If an application invokes any sqlite3_xxx API functions from within an unlock-notify callback, a crash or deadlock may be the result.

Unless deadlock is detected (see below), sqlite3_unlock_notify() always returns SQLITE_OK.

Callback Invocation Details

When an unlock-notify callback is registered, the application provides a single void* pointer that is passed to the callback when it is invoked. However, the signature of the callback function allows SQLite to pass it an array of void* context pointers. The first argument passed to an unlock-notify callback is a pointer to an array of void* pointers, and the second is the number of entries in the array.

When a blocking connections transaction is concluded, there may be more than one blocked connection that has registered for an unlock-notify callback. If two or more such blocked connections have specified the same callback function, then instead of invoking the callback function multiple times, it is invoked once with the set of void* context pointers specified by the blocked connections bundled together into an array. This gives the application an opportunity to prioritize any actions related to the set of unblocked database connections.

Deadlock Detection

Assuming that after registering for an unlock-notify callback a database waits for the callback to be issued before taking any further action (a reasonable assumption), then using this API may cause the application to deadlock. For example, if connection X is waiting for connection Y's transaction to be concluded, and similarly connection Y is waiting on connection X's transaction, then neither connection will proceed and the system may remain deadlocked indefinitely.

To avoid this scenario, the sqlite3_unlock_notify() performs deadlock detection. If a given call to sqlite3_unlock_notify() would put the system in a deadlocked state, then SQLITE_LOCKED is returned and no unlock-notify callback is registered. The system is said to be in a deadlocked state if connection A has registered for an unlock-notify callback on the conclusion of connection B's transaction, and connection B has itself registered for an unlock-notify callback when connection A's transaction is concluded. Indirect deadlock is also detected, so the system is also considered to be deadlocked if connection B has registered for an unlock-notify callback on the conclusion of connection C's transaction, where connection C is waiting on connection A. Any number of levels of indirection are allowed.

The "DROP TABLE" Exception

When a call to sqlite3_step() returns SQLITE_LOCKED, it is almost always appropriate to call sqlite3_unlock_notify(). There is however, one exception. When executing a "DROP TABLE" or "DROP INDEX" statement, SQLite checks if there are any currently executing SELECT statements that belong to the same connection. If there are, SQLITE_LOCKED is returned. In this case there is no "blocking connection", so invoking sqlite3_unlock_notify() results in the unlock-notify callback being invoked immediately. If the application then re-attempts the "DROP TABLE" or "DROP INDEX" query, an infinite loop might be the result.

One way around this problem is to check the extended error code returned by an sqlite3_step() call. If there is a blocking connection, then the extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in the special "DROP TABLE/INDEX" case, the extended error code is just SQLITE_LOCKED.

Data Change Notification Callbacks

void *sqlite3_update_hook(
  sqlite3*,
  void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  void*
);

The sqlite3_update_hook() interface registers a callback function with the database connection identified by the first argument to be invoked whenever a row is updated, inserted or deleted. Any callback set by a previous call to this function for the same database connection is overridden.

The second argument is a pointer to the function to invoke when a row is updated, inserted or deleted. The first argument to the callback is a copy of the third argument to sqlite3_update_hook(). The second callback argument is one of SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE, depending on the operation that caused the callback to be invoked. The third and fourth arguments to the callback contain pointers to the database and table name containing the affected row. The final callback parameter is the rowid of the row. In the case of an update, this is the rowid after the update takes place.

The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).

In the current implementation, the update hook is not invoked when duplication rows are deleted because of an ON CONFLICT REPLACE clause. Nor is the update hook invoked when rows are deleted using the truncate optimization. The exceptions defined in this paragraph might change in a future release of SQLite.

The update hook implementation must not do anything that will modify the database connection that invoked the update hook. Any actions to modify the database connection must be deferred until after the completion of the sqlite3_step() call that triggered the update hook. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

The sqlite3_update_hook(D,C,P) function returns the P argument from the previous call on the same database connection D, or NULL for the first call on D.

See also the sqlite3_commit_hook() and sqlite3_rollback_hook() interfaces.

Obtain Values For URI Parameters

const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);

This is a utility routine, useful to VFS implementations, that checks to see if a database file was a URI that contained a specific query parameter, and if so obtains the value of the query parameter.

The zFilename argument is the filename pointer passed into the xOpen() method of a VFS implementation. The zParam argument is the name of the query parameter we seek. This routine returns the value of the zParam parameter if it exists. If the parameter does not exist, this routine returns a NULL pointer.

If the zFilename argument to this function is not a pointer that SQLite passed into the xOpen VFS method, then the behavior of this routine is undefined and probably undesirable.

User Data For Functions

void *sqlite3_user_data(sqlite3_context*);

The sqlite3_user_data() interface returns a copy of the pointer that was the pUserData parameter (the 5th parameter) of the sqlite3_create_function() and sqlite3_create_function16() routines that originally registered the application defined function.

This routine must be called from the same thread in which the application-defined function is running.

Virtual Table Interface Configuration

int sqlite3_vtab_config(sqlite3*, int op, ...);

This function may be called by either the xConnect or xCreate method of a virtual table implementation to configure various facets of the virtual table interface.

If this interface is invoked outside the context of an xConnect or xCreate virtual table method then the behavior is undefined.

At present, there is only one option that may be configured using this function. (See SQLITE_VTAB_CONSTRAINT_SUPPORT.) Further options may be added in the future.

Determine The Virtual Table Conflict Policy

int sqlite3_vtab_on_conflict(sqlite3 *);

This function may only be called from within a call to the xUpdate method of a virtual table implementation for an INSERT or UPDATE operation. The value returned is one of SQLITE_ROLLBACK, SQLITE_IGNORE, SQLITE_FAIL, SQLITE_ABORT, or SQLITE_REPLACE, according to the ON CONFLICT mode of the SQL statement that triggered the call to the xUpdate method of the virtual table.

Configure an auto-checkpoint

int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

The sqlite3_wal_autocheckpoint(D,N) is a wrapper around sqlite3_wal_hook() that causes any database on database connection D to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.

The callback registered by this function replaces any existing callback registered using sqlite3_wal_hook(). Likewise, registering a callback using sqlite3_wal_hook() disables the automatic checkpoint mechanism configured by this function.

The wal_autocheckpoint pragma can be used to invoke this interface from SQL.

Every new database connection defaults to having the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT pages. The use of this interface is only necessary if the default setting is found to be suboptimal for a particular application.

Checkpoint a database

int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);

The sqlite3_wal_checkpoint(D,X) interface causes database named X on database connection D to be checkpointed. If X is NULL or an empty string, then a checkpoint is run on all databases of connection D. If the database connection D is not in write-ahead log mode then this interface is a harmless no-op.

The wal_checkpoint pragma can be used to invoke this interface from SQL. The sqlite3_wal_autocheckpoint() interface and the wal_autocheckpoint pragma can be used to cause this interface to be run whenever the WAL reaches a certain size threshold.

See also: sqlite3_wal_checkpoint_v2()

Checkpoint a database

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Database handle */
  const char *zDb,                /* Name of attached database (or NULL) */
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
  int *pnLog,                     /* OUT: Size of WAL log in frames */
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
);

Run a checkpoint operation on WAL database zDb attached to database handle db. The specific operation is determined by the value of the eMode parameter:

SQLITE_CHECKPOINT_PASSIVE
Checkpoint as many frames as possible without waiting for any database readers or writers to finish. Sync the db file if all frames in the log are checkpointed. This mode is the same as calling sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.

SQLITE_CHECKPOINT_FULL
This mode blocks (calls the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This call blocks database writers while it is running, but not database readers.

SQLITE_CHECKPOINT_RESTART
This mode works the same way as SQLITE_CHECKPOINT_FULL, except after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next client to write to the database file restarts the log file from the beginning. This call blocks database writers while it is running, but not database readers.

If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to the total number of checkpointed frames (including any that were already checkpointed when this function is called). *pnLog and *pnCkpt may be populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK. If no values are available because of an error, they are both set to -1 before returning to communicate this to the caller.

All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.

The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQLITE_BUSY is returned in this case.

If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQLITE_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQLITE_BUSY is returned to the caller. If any other error occurs while processing an attached database, processing is abandoned and the error code returned to the caller immediately. If no error (SQLITE_BUSY or otherwise) is encountered while processing the attached databases, SQLITE_OK is returned.

If database zDb is the name of an attached database that is not in WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQLITE_ERROR is returned to the caller.

Write-Ahead Log Commit Hook

void *sqlite3_wal_hook(
  sqlite3*,
  int(*)(void *,sqlite3*,const char*,int),
  void*
);

The sqlite3_wal_hook() function is used to register a callback that will be invoked each time a database connection commits data to a write-ahead log (i.e. whenever a transaction is committed in journal_mode=WAL mode).

The callback is invoked by SQLite after the commit has taken place and the associated write-lock on the database released, so the implementation may read, write or checkpoint the database as required.

The first parameter passed to the callback function when it is invoked is a copy of the third parameter passed to sqlite3_wal_hook() when registering the callback. The second is a copy of the database handle. The third parameter is the name of the database that was written to - either "main" or the name of an ATTACH-ed database. The fourth parameter is the number of pages currently in the write-ahead log file, including those that were just committed.

The callback function should normally return SQLITE_OK. If an error code is returned, that error will propagate back up through the SQLite code base to cause the statement that provoked the callback to report an error, though the commit will have still occurred. If the callback returns SQLITE_ROW or SQLITE_DONE, or if it returns a value that does not correspond to any valid SQLite error code, the results are undefined.

A single database handle may have at most a single write-ahead log callback registered at one time. Calling sqlite3_wal_hook() replaces any previously registered write-ahead log callback. Note that the sqlite3_wal_autocheckpoint() interface and the wal_autocheckpoint pragma both invoke sqlite3_wal_hook() and will those overwrite any prior sqlite3_wal_hook() settings.

Result Codes

#define SQLITE_OK           0   /* Successful result */
/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
/* end-of-error-codes */

Many SQLite functions return an integer result code from the set shown here in order to indicates success or failure.

New error codes may be added in future versions of SQLite.

See also: extended result codes, sqlite3_vtab_on_conflict() result codes.

Flags for the xAccess VFS method

#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
#define SQLITE_ACCESS_READ      2   /* Unused */

These integer constants can be used as the third parameter to the xAccess method of an sqlite3_vfs object. They determine what kind of permissions the xAccess method is looking for. With SQLITE_ACCESS_EXISTS, the xAccess method simply checks whether the file exists. With SQLITE_ACCESS_READWRITE, the xAccess method checks whether the named directory is both readable and writable (in other words, if files can be added, removed, and renamed within the directory). The SQLITE_ACCESS_READWRITE constant is currently used only by the temp_store_directory pragma, though this could change in a future release of SQLite. With SQLITE_ACCESS_READ, the xAccess method checks whether the file is readable. The SQLITE_ACCESS_READ constant is currently unused, though it might be used in a future release of SQLite.

Authorizer Action Codes

/******************************************* 3rd ************ 4th ***********/
#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
#define SQLITE_DELETE                9   /* Table Name      NULL            */
#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
#define SQLITE_INSERT               18   /* Table Name      NULL            */
#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
#define SQLITE_READ                 20   /* Table Name      Column Name     */
#define SQLITE_SELECT               21   /* NULL            NULL            */
#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
#define SQLITE_ATTACH               24   /* Filename        NULL            */
#define SQLITE_DETACH               25   /* Database Name   NULL            */
#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
#define SQLITE_REINDEX              27   /* Index Name      NULL            */
#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
#define SQLITE_COPY                  0   /* No longer used */

The sqlite3_set_authorizer() interface registers a callback function that is invoked to authorize certain SQL statement actions. The second parameter to the callback is an integer code that specifies what action is being authorized. These are the integer action codes that the authorizer callback may be passed.

These action code values signify what kind of operation is to be authorized. The 3rd and 4th parameters to the authorization callback function will be parameters or NULL depending on which of these codes is used as the second parameter. The 5th parameter to the authorizer callback is the name of the database ("main", "temp", etc.) if applicable. The 6th parameter to the authorizer callback is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from top-level SQL code.

Text Encodings

#define SQLITE_UTF8           1
#define SQLITE_UTF16LE        2
#define SQLITE_UTF16BE        3
#define SQLITE_UTF16          4    /* Use native byte order */
#define SQLITE_ANY            5    /* sqlite3_create_function only */
#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */

These constant define integer codes that represent the various text encodings supported by SQLite.

Fundamental Datatypes

#define SQLITE_INTEGER  1
#define SQLITE_FLOAT    2
#define SQLITE_BLOB     4
#define SQLITE_NULL     5
#ifdef SQLITE_TEXT
# undef SQLITE_TEXT
#else
# define SQLITE_TEXT     3
#endif
#define SQLITE3_TEXT     3

Every value in SQLite has one of five fundamental datatypes:

  • 64-bit signed integer
  • 64-bit IEEE floating point number
  • string
  • BLOB
  • NULL

These constants are codes for each of those types.

Note that the SQLITE_TEXT constant was also used in SQLite version 2 for a completely different meaning. Software that links against both SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not SQLITE_TEXT.

Extended Result Codes

#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))

In its default configuration, SQLite API routines return one of 26 integer result codes. However, experience has shown that many of these result codes are too coarse-grained. They do not provide as much information about problems as programmers might like. In an effort to address this, newer versions of SQLite (version 3.3.8 and later) include support for additional result codes that provide more detailed information about errors. The extended result codes are enabled or disabled on a per database connection basis using the sqlite3_extended_result_codes() API.

Some of the available extended result codes are listed here. One may expect the number of extended result codes will be expand over time. Software that uses extended result codes should expect to see new result codes in future releases of SQLite.

The SQLITE_OK result code will never be extended. It will always be exactly zero.

Checkpoint operation parameters

#define SQLITE_CHECKPOINT_PASSIVE 0
#define SQLITE_CHECKPOINT_FULL    1
#define SQLITE_CHECKPOINT_RESTART 2

These constants can be used as the 3rd parameter to sqlite3_wal_checkpoint_v2(). See the sqlite3_wal_checkpoint_v2() documentation for additional information about the meaning and use of each of these values.

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* */
#define SQLITE_CONFIG_URI          17  /* int */

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_limit64()
  • 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 scratch 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 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 two scratch buffers per thread. So N should be set to twice 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 implementation. 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 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. The minimum allocation size is capped at 2**12. Reasonable values for the minimum allocation size are 2**5 through 2**8.

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.

SQLITE_CONFIG_URI
This option takes a single argument of type int. If non-zero, then URI handling is globally enabled. If the parameter is zero, then URI handling is globally disabled. If URI handling is globally enabled, all filenames passed to sqlite3_open(), sqlite3_open_v2(), sqlite3_open16() or specified as part of ATTACH commands are interpreted as URIs, regardless of whether or not the SQLITE_OPEN_URI flag is set when the database connection is opened. If it is globally disabled, filenames are only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the database connection is opened. By default, URI handling is globally disabled. The default value may be changed by compiling with the SQLITE_USE_URI symbol defined.

Database Connection Configuration Options

#define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
#define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
#define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */

These constants are the available integer configuration options that can be passed as the second argument to the sqlite3_db_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_db_config() to make sure that the call worked. The sqlite3_db_config() interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.

SQLITE_DBCONFIG_LOOKASIDE
This option takes three additional arguments that determine the lookaside memory allocator configuration for the database connection. The first argument (the third parameter to sqlite3_db_config() is a pointer to a memory buffer to use for lookaside memory. The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be NULL in which case SQLite will allocate the lookaside buffer itself using sqlite3_malloc(). The second argument is the size of each lookaside buffer slot. The third argument is the number of slots. The size of the buffer in the first argument must be greater than or equal to the product of the second and third arguments. The buffer must be aligned to an 8-byte boundary. If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally rounded down to the next smaller multiple of 8. The lookaside memory configuration for a database connection can only be changed when that connection is not currently using lookaside memory, or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_CONFIG_LOOKASIDE,...) is zero. Any attempt to change the lookaside memory configuration when lookaside memory is in use leaves the configuration unchanged and returns SQLITE_BUSY.

SQLITE_DBCONFIG_ENABLE_FKEY
This option is used to enable or disable the enforcement of foreign key constraints. There should be two additional arguments. The first argument is an integer which is 0 to disable FK enforcement, positive to enable FK enforcement or negative to leave FK enforcement unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether FK enforcement is off or on following this call. The second parameter may be a NULL pointer, in which case the FK enforcement setting is not reported back.

SQLITE_DBCONFIG_ENABLE_TRIGGER
This option is used to enable or disable triggers. There should be two additional arguments. The first argument is an integer which is 0 to disable triggers, positive to enable triggers or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether triggers are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the trigger setting is not reported back.

Authorizer Return Codes

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */

The authorizer callback function must return either SQLITE_OK or one of these two constants in order to signal SQLite whether or not the action is permitted. See the authorizer documentation for additional information.

Note that SQLITE_IGNORE is also used as a return code from the sqlite3_vtab_on_conflict() interface.

Conflict resolution modes

#define SQLITE_ROLLBACK 1
/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
#define SQLITE_FAIL     3
/* #define SQLITE_ABORT 4  // Also an error code */
#define SQLITE_REPLACE  5

These constants are returned by sqlite3_vtab_on_conflict() to inform a virtual table implementation what the ON CONFLICT mode is for the SQL statement being evaluated.

Note that the SQLITE_IGNORE constant is also used as a potential return value from the sqlite3_set_authorizer() callback and that SQLITE_ABORT is also a result code.

Standard File Control Opcodes

#define SQLITE_FCNTL_LOCKSTATE        1
#define SQLITE_GET_LOCKPROXYFILE      2
#define SQLITE_SET_LOCKPROXYFILE      3
#define SQLITE_LAST_ERRNO             4
#define SQLITE_FCNTL_SIZE_HINT        5
#define SQLITE_FCNTL_CHUNK_SIZE       6
#define SQLITE_FCNTL_FILE_POINTER     7
#define SQLITE_FCNTL_SYNC_OMITTED     8
#define SQLITE_FCNTL_WIN32_AV_RETRY   9
#define SQLITE_FCNTL_PERSIST_WAL     10
#define SQLITE_FCNTL_OVERWRITE       11

These integer constants are opcodes for the xFileControl method of the sqlite3_io_methods object and for the sqlite3_file_control() interface.

The SQLITE_FCNTL_LOCKSTATE opcode is used for debugging. This opcode causes the xFileControl method to write the current state of the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE) into an integer that the pArg argument points to. This capability is used during testing and only needs to be supported when SQLITE_TEST is defined.

The SQLITE_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS layer a hint of how large the database file will grow to be during the current transaction. This hint is not guaranteed to be accurate but it is often close. The underlying VFS might choose to preallocate database file space based on this hint in order to help writes to the database file run faster.

The SQLITE_FCNTL_CHUNK_SIZE opcode is used to request that the VFS extends and truncates the database file in chunks of a size specified by the user. The fourth argument to sqlite3_file_control() should point to an integer (type int) containing the new chunk-size to use for the nominated database. Allocating database file space in large chunks (say 1MB at a time), may reduce file-system fragmentation and improve performance on some systems.

The SQLITE_FCNTL_FILE_POINTER opcode is used to obtain a pointer to the sqlite3_file object associated with a particular database connection. See the sqlite3_file_control() documentation for additional information.

The SQLITE_FCNTL_SYNC_OMITTED opcode is generated internally by SQLite and sent to all VFSes in place of a call to the xSync method when the database connection has PRAGMA synchronous set to OFF. Some specialized VFSes need this signal in order to operate correctly when PRAGMA synchronous=OFF is set, but most VFSes do not need this signal and should silently ignore this opcode. Applications should not call sqlite3_file_control() with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.

The SQLITE_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic retry counts and intervals for certain disk I/O operations for the windows VFS in order to work to provide robustness against anti-virus programs. By default, the windows VFS will retry file read, file write, and file delete operations up to 10 times, with a delay of 25 milliseconds before the first retry and with the delay increasing by an additional 25 milliseconds with each subsequent retry. This opcode allows those to values (10 retries and 25 milliseconds of delay) to be adjusted. The values are changed for all database connections within the same process. The argument is a pointer to an array of two integers where the first integer i the new retry count and the second integer is the delay. If either integer is negative, then the setting is not changed but instead the prior value of that setting is written into the array entry, allowing the current retry settings to be interrogated. The zDbName parameter is ignored.

The SQLITE_FCNTL_PERSIST_WAL opcode is used to set or query the persistent Write AHead Log setting. By default, the auxiliary write ahead log and shared memory files used for transaction control are automatically deleted when the latest connection to the database closes. Setting persistent WAL mode causes those files to persist after close. Persisting the files is useful when other processes that do not have write permission on the directory containing the database file want to read the database file, as the WAL and shared memory files must exist in order for the database to be readable. The fourth parameter to sqlite3_file_control() for this opcode should be a pointer to an integer. That integer is 0 to disable persistent WAL mode or 1 to enable persistent WAL mode. If the integer is -1, then it is overwritten with the current WAL persistence setting.

The SQLITE_FCNTL_OVERWRITE opcode is invoked by SQLite after opening a write transaction to indicate that, unless it is rolled back for some reason, the entire database file will be overwritten by the current transaction. This is used by VACUUM operations.

Virtual Table Constraint Operator Codes

#define SQLITE_INDEX_CONSTRAINT_EQ    2
#define SQLITE_INDEX_CONSTRAINT_GT    4
#define SQLITE_INDEX_CONSTRAINT_LE    8
#define SQLITE_INDEX_CONSTRAINT_LT    16
#define SQLITE_INDEX_CONSTRAINT_GE    32
#define SQLITE_INDEX_CONSTRAINT_MATCH 64

These macros defined the allowed values for the sqlite3_index_info.aConstraint[].op field. Each value represents an operator that is part of a constraint term in the wHERE clause of a query that uses a virtual table.

Device Characteristics

#define SQLITE_IOCAP_ATOMIC                 0x00000001
#define SQLITE_IOCAP_ATOMIC512              0x00000002
#define SQLITE_IOCAP_ATOMIC1K               0x00000004
#define SQLITE_IOCAP_ATOMIC2K               0x00000008
#define SQLITE_IOCAP_ATOMIC4K               0x00000010
#define SQLITE_IOCAP_ATOMIC8K               0x00000020
#define SQLITE_IOCAP_ATOMIC16K              0x00000040
#define SQLITE_IOCAP_ATOMIC32K              0x00000080
#define SQLITE_IOCAP_ATOMIC64K              0x00000100
#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800

The xDeviceCharacteristics method of the sqlite3_io_methods object returns an integer which is a vector of the these bit values expressing I/O characteristics of the mass storage device that holds the file that the sqlite3_io_methods refers to.

The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQLITE_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite().

File Locking Levels

#define SQLITE_LOCK_NONE          0
#define SQLITE_LOCK_SHARED        1
#define SQLITE_LOCK_RESERVED      2
#define SQLITE_LOCK_PENDING       3
#define SQLITE_LOCK_EXCLUSIVE     4

SQLite uses one of these integer values as the second argument to calls it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods object.

Mutex Types

#define SQLITE_MUTEX_FAST             0
#define SQLITE_MUTEX_RECURSIVE        1
#define SQLITE_MUTEX_STATIC_MASTER    2
#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
#define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */
#define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */

The sqlite3_mutex_alloc() interface takes a single argument which is one of these integer constants.

The set of static mutexes may change from one SQLite release to the next. Applications that override the built-in mutex logic must be prepared to accommodate additional static mutexes.

Flags For File Open Operations

#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */

These bit values are intended for use in the 3rd parameter to the sqlite3_open_v2() interface and in the 4th parameter to the sqlite3_vfs.xOpen method.

Flags for the xShmLock VFS method

#define SQLITE_SHM_UNLOCK       1
#define SQLITE_SHM_LOCK         2
#define SQLITE_SHM_SHARED       4
#define SQLITE_SHM_EXCLUSIVE    8

These integer constants define the various locking operations allowed by the xShmLock method of sqlite3_io_methods. The following are the only legal combinations of flags to the xShmLock method:

  • SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  • SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE

When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as was given no the corresponding lock.

The xShmLock method can transition between unlocked and SHARED or between unlocked and EXCLUSIVE. It cannot transition between SHARED and EXCLUSIVE.

Compile-Time Library Version Numbers

#define SQLITE_VERSION        "3.7.9"
#define SQLITE_VERSION_NUMBER 3007009
#define SQLITE_SOURCE_ID      "2011-11-01 00:52:41 c7c6050ef060877ebe77b41d959e9df13f8c9b5e"

The SQLITE_VERSION C preprocessor macro in the sqlite3.h header evaluates to a string literal that is the SQLite version in the format "X.Y.Z" where X is the major version number (always 3 for SQLite3) and Y is the minor version number and Z is the release number. The SQLITE_VERSION_NUMBER C preprocessor macro resolves to an integer with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same numbers used in SQLITE_VERSION. The SQLITE_VERSION_NUMBER for any given release of SQLite will also be larger than the release from which it is derived. Either Y will be held constant and Z will be incremented or else Y will be incremented and Z will be reset to zero.

Since version 3.6.18, SQLite source code has been stored in the Fossil configuration management system. The SQLITE_SOURCE_ID macro evaluates to a string which identifies a particular check-in of SQLite within its configuration management system. The SQLITE_SOURCE_ID string contains the date and time of the check-in (UTC) and an SHA1 hash of the entire source tree.

See also: sqlite3_libversion(),
sqlite3_libversion_number(), sqlite3_sourceid(),
sqlite_version() and sqlite_source_id().

Constants Defining Special Destructor Behavior

typedef void (*sqlite3_destructor_type)(void*);
#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)

These are special values for the destructor that is passed in as the final argument to routines like sqlite3_result_blob(). If the destructor argument is SQLITE_STATIC, it means that the content pointer is constant and will never change. It does not need to be destroyed. The SQLITE_TRANSIENT value means that the content will likely change in the near future and that SQLite should make its own private copy of the content before returning.

The typedef is necessary to work around problems in certain C++ compilers. See ticket #2191.

Status Parameters

#define SQLITE_STATUS_MEMORY_USED          0
#define SQLITE_STATUS_PAGECACHE_USED       1
#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
#define SQLITE_STATUS_SCRATCH_USED         3
#define SQLITE_STATUS_SCRATCH_OVERFLOW     4
#define SQLITE_STATUS_MALLOC_SIZE          5
#define SQLITE_STATUS_PARSER_STACK         6
#define SQLITE_STATUS_PAGECACHE_SIZE       7
#define SQLITE_STATUS_SCRATCH_SIZE         8
#define SQLITE_STATUS_MALLOC_COUNT         9

These integer constants designate various run-time status parameters that can be returned by sqlite3_status().

SQLITE_STATUS_MEMORY_USED
This parameter is the current amount of memory checked out using sqlite3_malloc(), either directly or indirectly. The figure includes calls made to sqlite3_malloc() by the application and internal memory usage by the SQLite library. Scratch memory controlled by SQLITE_CONFIG_SCRATCH and auxiliary page-cache memory controlled by SQLITE_CONFIG_PAGECACHE is not included in this parameter. The amount returned is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.

SQLITE_STATUS_MALLOC_SIZE
This parameter records the largest memory allocation request handed to sqlite3_malloc() or sqlite3_realloc() (or their internal equivalents). Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_MALLOC_COUNT
This parameter records the number of separate memory allocations currently checked out.

SQLITE_STATUS_PAGECACHE_USED
This parameter returns the number of pages used out of the pagecache memory allocator that was configured using SQLITE_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.

SQLITE_STATUS_PAGECACHE_OVERFLOW
This parameter returns the number of bytes of page cache allocation which could not be satisfied by the SQLITE_CONFIG_PAGECACHE buffer and where forced to overflow to sqlite3_malloc(). The returned value includes allocations that overflowed because they where too large (they were larger than the "sz" parameter to SQLITE_CONFIG_PAGECACHE) and allocations that overflowed because no space was left in the page cache.

SQLITE_STATUS_PAGECACHE_SIZE
This parameter records the largest memory allocation request handed to pagecache memory allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_SCRATCH_USED
This parameter returns the number of allocations used out of the scratch memory allocator configured using SQLITE_CONFIG_SCRATCH. The value returned is in allocations, not in bytes. Since a single thread may only have one scratch allocation outstanding at time, this parameter also reports the number of threads using scratch memory at the same time.

SQLITE_STATUS_SCRATCH_OVERFLOW
This parameter returns the number of bytes of scratch memory allocation which could not be satisfied by the SQLITE_CONFIG_SCRATCH buffer and where forced to overflow to sqlite3_malloc(). The values returned include overflows because the requested allocation was too larger (that is, because the requested allocation was larger than the "sz" parameter to SQLITE_CONFIG_SCRATCH) and because no scratch buffer slots were available.

SQLITE_STATUS_SCRATCH_SIZE
This parameter records the largest memory allocation request handed to scratch memory allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_PARSER_STACK
This parameter records the deepest parser stack. It is only meaningful if SQLite is compiled with YYTRACKMAXSTACKDEPTH.

New status parameters may be added from time to time.

Synchronization Type Flags

#define SQLITE_SYNC_NORMAL        0x00002
#define SQLITE_SYNC_FULL          0x00003
#define SQLITE_SYNC_DATAONLY      0x00010

When SQLite invokes the xSync() method of an sqlite3_io_methods object it uses a combination of these integer values as the second argument.

When the SQLITE_SYNC_DATAONLY flag is used, it means that the sync operation only needs to flush data to mass storage. Inode information need not be flushed. If the lower four bits of the flag equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. If the lower four bits equal SQLITE_SYNC_FULL, that means to use Mac OS X style fullsync instead of fsync().

Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags with the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL settings. The synchronous pragma determines when calls to the xSync VFS method occur and applies uniformly across all platforms. The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how energetic or rigorous or forceful the sync operations are and only make a difference on Mac OSX for the default SQLite code. (Third-party VFS implementations might also make the distinction between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the operating systems natively supported by SQLite, only Mac OSX cares about the difference.)

Testing Interface Operation Codes

#define SQLITE_TESTCTRL_FIRST                    5
#define SQLITE_TESTCTRL_PRNG_SAVE                5
#define SQLITE_TESTCTRL_PRNG_RESTORE             6
#define SQLITE_TESTCTRL_PRNG_RESET               7
#define SQLITE_TESTCTRL_BITVEC_TEST              8
#define SQLITE_TESTCTRL_FAULT_INSTALL            9
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
#define SQLITE_TESTCTRL_PENDING_BYTE            11
#define SQLITE_TESTCTRL_ASSERT                  12
#define SQLITE_TESTCTRL_ALWAYS                  13
#define SQLITE_TESTCTRL_RESERVE                 14
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
#define SQLITE_TESTCTRL_ISKEYWORD               16
#define SQLITE_TESTCTRL_PGHDRSZ                 17
#define SQLITE_TESTCTRL_SCRATCHMALLOC           18
#define SQLITE_TESTCTRL_LOCALTIME_FAULT         19
#define SQLITE_TESTCTRL_LAST                    19

These constants are the valid operation code parameters used as the first argument to sqlite3_test_control().

These parameters and their meanings are subject to change without notice. These values are for testing purposes only. Applications should not use any of these parameters or the sqlite3_test_control() interface.

Run-Time Limit Categories

#define SQLITE_LIMIT_LENGTH                    0
#define SQLITE_LIMIT_SQL_LENGTH                1
#define SQLITE_LIMIT_COLUMN                    2
#define SQLITE_LIMIT_EXPR_DEPTH                3
#define SQLITE_LIMIT_COMPOUND_SELECT           4
#define SQLITE_LIMIT_VDBE_OP                   5
#define SQLITE_LIMIT_FUNCTION_ARG              6
#define SQLITE_LIMIT_ATTACHED                  7
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
#define SQLITE_LIMIT_VARIABLE_NUMBER           9
#define SQLITE_LIMIT_TRIGGER_DEPTH            10

These constants define various performance limits that can be lowered at run-time using sqlite3_limit(). The synopsis of the meanings of the various limits is shown below. Additional information is available at Limits in SQLite.

SQLITE_LIMIT_LENGTH
The maximum size of any string or BLOB or table row, in bytes.

SQLITE_LIMIT_SQL_LENGTH
The maximum length of an SQL statement, in bytes.

SQLITE_LIMIT_COLUMN
The maximum number of columns in a table definition or in the result set of a SELECT or the maximum number of columns in an index or in an ORDER BY or GROUP BY clause.

SQLITE_LIMIT_EXPR_DEPTH
The maximum depth of the parse tree on any expression.

SQLITE_LIMIT_COMPOUND_SELECT
The maximum number of terms in a compound SELECT statement.

SQLITE_LIMIT_VDBE_OP
The maximum number of instructions in a virtual machine program used to implement an SQL statement. This limit is not currently enforced, though that might be added in some future release of SQLite.

SQLITE_LIMIT_FUNCTION_ARG
The maximum number of arguments on a function.

SQLITE_LIMIT_ATTACHED
The maximum number of attached databases.

SQLITE_LIMIT_LIKE_PATTERN_LENGTH
The maximum length of the pattern argument to the LIKE or GLOB operators.

SQLITE_LIMIT_VARIABLE_NUMBER
The maximum index number of any parameter in an SQL statement.

SQLITE_LIMIT_TRIGGER_DEPTH
The maximum depth of recursion for triggers.

Status Parameters for database connections

#define SQLITE_DBSTATUS_LOOKASIDE_USED       0
#define SQLITE_DBSTATUS_CACHE_USED           1
#define SQLITE_DBSTATUS_SCHEMA_USED          2
#define SQLITE_DBSTATUS_STMT_USED            3
#define SQLITE_DBSTATUS_LOOKASIDE_HIT        4
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
#define SQLITE_DBSTATUS_CACHE_HIT            7
#define SQLITE_DBSTATUS_CACHE_MISS           8
#define SQLITE_DBSTATUS_MAX                  8   /* Largest defined DBSTATUS */

These constants are the available integer "verbs" that can be passed as the second argument to the sqlite3_db_status() interface.

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

SQLITE_DBSTATUS_LOOKASIDE_USED
This parameter returns the number of lookaside memory slots currently checked out.

SQLITE_DBSTATUS_LOOKASIDE_HIT
This parameter returns the number malloc attempts that were satisfied using lookaside memory. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to the amount of memory requested being larger than the lookaside slot size. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to all lookaside memory already being in use. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_CACHE_USED
This parameter returns the approximate number of of bytes of heap memory used by all pager caches associated with the database connection. The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.

SQLITE_DBSTATUS_SCHEMA_USED
This parameter returns the approximate number of of bytes of heap memory used to store the schema for all databases associated with the connection - main, temp, and any ATTACH-ed databases. The full amount of memory used by the schemas is reported, even if the schema memory is shared with other database connections due to shared cache mode being enabled. The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.

SQLITE_DBSTATUS_STMT_USED
This parameter returns the approximate number of of bytes of heap and lookaside memory used by all prepared statements associated with the database connection. The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.

SQLITE_DBSTATUS_CACHE_HIT
This parameter returns the number of pager cache hits that have occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT is always 0.

SQLITE_DBSTATUS_CACHE_MISS
This parameter returns the number of pager cache misses that have occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS is always 0.

Status Parameters for prepared statements

#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
#define SQLITE_STMTSTATUS_SORT              2
#define SQLITE_STMTSTATUS_AUTOINDEX         3

These preprocessor macros define integer codes that name counter values associated with the sqlite3_stmt_status() interface. The meanings of the various counters are as follows:

SQLITE_STMTSTATUS_FULLSCAN_STEP
This is the number of times that SQLite has stepped forward in a table as part of a full table scan. Large numbers for this counter may indicate opportunities for performance improvement through careful use of indices.

SQLITE_STMTSTATUS_SORT
This is the number of sort operations that have occurred. A non-zero value in this counter may indicate an opportunity to improvement performance through careful use of indices.

SQLITE_STMTSTATUS_AUTOINDEX
This is the number of rows inserted into transient indices that were created automatically in order to help joins run faster. A non-zero value in this counter may indicate an opportunity to improvement performance by adding permanent indices that do not need to be reinitialized each time the statement is run.

64-Bit Integer Types

#ifdef SQLITE_INT64_TYPE
  typedef SQLITE_INT64_TYPE sqlite_int64;
  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
#elif defined(_MSC_VER) || defined(__BORLANDC__)
  typedef __int64 sqlite_int64;
  typedef unsigned __int64 sqlite_uint64;
#else
  typedef long long int sqlite_int64;
  typedef unsigned long long int sqlite_uint64;
#endif
typedef sqlite_int64 sqlite3_int64;
typedef sqlite_uint64 sqlite3_uint64;

Because there is no cross-platform way to specify 64-bit integer types SQLite includes typedefs for 64-bit signed and unsigned integers.

The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. The sqlite_int64 and sqlite_uint64 types are supported for backwards compatibility only.

The sqlite3_int64 and sqlite_int64 types can store integer values between -9223372036854775808 and +9223372036854775807 inclusive. The sqlite3_uint64 and sqlite_uint64 types can store integer values between 0 and +18446744073709551615 inclusive.

Virtual Table Object

struct sqlite3_module {
  int iVersion;
  int (*xCreate)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  int (*xDisconnect)(sqlite3_vtab *pVTab);
  int (*xDestroy)(sqlite3_vtab *pVTab);
  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  int (*xClose)(sqlite3_vtab_cursor*);
  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                int argc, sqlite3_value **argv);
  int (*xNext)(sqlite3_vtab_cursor*);
  int (*xEof)(sqlite3_vtab_cursor*);
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  int (*xBegin)(sqlite3_vtab *pVTab);
  int (*xSync)(sqlite3_vtab *pVTab);
  int (*xCommit)(sqlite3_vtab *pVTab);
  int (*xRollback)(sqlite3_vtab *pVTab);
  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
                       void **ppArg);
  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  /* The methods above are in version 1 of the sqlite_module object. Those
  ** below are for version 2 and greater. */
  int (*xSavepoint)(sqlite3_vtab *pVTab, int);
  int (*xRelease)(sqlite3_vtab *pVTab, int);
  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
};

This structure, sometimes called a "virtual table module", defines the implementation of a virtual tables. This structure consists mostly of methods for the module.

A virtual table module is created by filling in a persistent instance of this structure and passing a pointer to that instance to sqlite3_create_module() or sqlite3_create_module_v2(). The registration remains valid until it is replaced by a different module or until the database connection closes. The content of this structure must not change while it is registered with any database connection.

Virtual Table Cursor Object

struct sqlite3_vtab_cursor {
  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  /* Virtual table implementations will typically add additional fields */
};

Every virtual table module implementation uses a subclass of the following structure to describe cursors that point into the virtual table and are used to loop through the virtual table. Cursors are created using the xOpen method of the module and are destroyed by the xClose method. Cursors are used by the xFilter, xNext, xEof, xColumn, and xRowid methods of the module. Each module implementation will define the content of a cursor structure to suit its own needs.

This superclass exists in order to define fields of the cursor that are common to all implementations.

A Handle To An Open BLOB

typedef struct sqlite3_blob sqlite3_blob;

An instance of this object represents an open BLOB on which incremental BLOB I/O can be performed. Objects of this type are created by sqlite3_blob_open() and destroyed by sqlite3_blob_close(). The sqlite3_blob_read() and sqlite3_blob_write() interfaces can be used to read or write small subsections of the BLOB. The sqlite3_blob_bytes() interface returns the size of the BLOB in bytes.

Database Connection Handle

typedef struct sqlite3 sqlite3;

Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3". It is useful to think of an sqlite3 pointer as an object. The sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces are its constructors, and sqlite3_close() is its destructor. There are many other interfaces (such as sqlite3_prepare_v2(), sqlite3_create_function(), and sqlite3_busy_timeout() to name but three) that are methods on an sqlite3 object.

Application Defined Page Cache.

typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
struct sqlite3_pcache_methods {
  void *pArg;
  int (*xInit)(void*);
  void (*xShutdown)(void*);
  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  int (*xPagecount)(sqlite3_pcache*);
  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  void (*xDestroy)(sqlite3_pcache*);
};

The sqlite3_config(SQLITE_CONFIG_PCACHE, ...) interface can register an alternative page cache implementation by passing in an instance of the sqlite3_pcache_methods structure. In many applications, most of the heap memory allocated by SQLite is used for the page cache. By implementing a custom page cache using this API, an application can better control the amount of memory consumed by SQLite, the way in which that memory is allocated and released, and the policies used to determine exactly which parts of a database file are cached and for how long.

The alternative page cache mechanism is an extreme measure that is only needed by the most demanding applications. The built-in page cache is recommended for most uses.

The contents of the sqlite3_pcache_methods structure are copied to an internal buffer by SQLite within the call to sqlite3_config. Hence the application may discard the parameter after the call to sqlite3_config() returns.

The xInit() method is called once for each effective call to sqlite3_initialize() (usually only once during the lifetime of the process). The xInit() method is passed a copy of the sqlite3_pcache_methods.pArg value. The intent of the xInit() method is to set up global data structures required by the custom page cache implementation. If the xInit() method is NULL, then the built-in default page cache is used instead of the application defined page cache.

The xShutdown() method is called by sqlite3_shutdown(). It can be used to clean up any outstanding resources before process shutdown, if required. The xShutdown() method may be NULL.

SQLite automatically serializes calls to the xInit method, so the xInit method need not be threadsafe. The xShutdown method is only called from sqlite3_shutdown() so it does not need to be threadsafe either. All other methods must be threadsafe in multithreaded applications.

SQLite will never invoke xInit() more than once without an intervening call to xShutdown().

SQLite invokes the xCreate() method to construct a new cache instance. SQLite will typically create one cache instance for each open database file, though this is not guaranteed. The first parameter, szPage, is the size in bytes of the pages that must be allocated by the cache. szPage will not be a power of two. szPage will the page size of the database file that is to be cached plus an increment (here called "R") of less than 250. SQLite will use the extra R bytes on each page to store metadata about the underlying database page on disk. The value of R depends on the SQLite version, the target platform, and how SQLite was compiled. R is constant for a particular build of SQLite. Except, there are two distinct values of R when SQLite is compiled with the proprietary ZIPVFS extension. The second argument to xCreate(), bPurgeable, is true if the cache being created will be used to cache database pages of a file stored on disk, or false if it is used for an in-memory database. The cache implementation does not have to do anything special based with the value of bPurgeable; it is purely advisory. On a cache where bPurgeable is false, SQLite will never invoke xUnpin() except to deliberately delete a page. In other words, calls to xUnpin() on a cache with bPurgeable set to false will always have the "discard" flag set to true. Hence, a cache created with bPurgeable false will never contain any unpinned pages.

The xCachesize() method may be called at any time by SQLite to set the suggested maximum cache-size (number of pages stored by) the cache instance passed as the first argument. This is the value configured using the SQLite "PRAGMA cache_size" command. As with the bPurgeable parameter, the implementation is not required to do anything with this value; it is advisory only.

The xPagecount() method must return the number of pages currently stored in the cache, both pinned and unpinned.

The xFetch() method locates a page in the cache and returns a pointer to the page, or a NULL pointer. A "page", in this context, means a buffer of szPage bytes aligned at an 8-byte boundary. The page to be fetched is determined by the key. The minimum key value is 1. After it has been retrieved using xFetch, the page is considered to be "pinned".

If the requested page is already in the page cache, then the page cache implementation must return a pointer to the page buffer with its content intact. If the requested page is not already in the cache, then the cache implementation should use the value of the createFlag parameter to help it determined what action to take:

createFlag | Behaviour when page is not already in cache
0 | Do not allocate a new page. Return NULL.
1 | Allocate a new page if it easy and convenient to do so. Otherwise return NULL.
2 | Make every effort to allocate a new page. Only return NULL if allocating a new page is effectively impossible.

SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite will only use a createFlag of 2 after a prior call with a createFlag of 1 failed. In between the to xFetch() calls, SQLite may attempt to unpin one or more cache pages by spilling the content of pinned pages to disk and synching the operating system disk cache.

xUnpin() is called by SQLite with a pointer to a currently pinned page as its second argument. If the third parameter, discard, is non-zero, then the page must be evicted from the cache. If the discard parameter is zero, then the page may be discarded or retained at the discretion of page cache implementation. The page cache implementation may choose to evict unpinned pages at any time.

The cache must not perform any reference counting. A single call to xUnpin() unpins the page regardless of the number of prior calls to xFetch().

The xRekey() method is used to change the key value associated with the page passed as the second argument. If the cache previously contains an entry associated with newKey, it must be discarded. Any prior cache entry associated with newKey is guaranteed not to be pinned.

When SQLite calls the xTruncate() method, the cache must discard all existing cache entries with page numbers (keys) greater than or equal to the value of the iLimit parameter passed to xTruncate(). If any of these pages are pinned, they are implicitly unpinned, meaning that they can be safely discarded.

The xDestroy() method is used to delete a cache allocated by xCreate(). All resources associated with the specified cache should be freed. After calling the xDestroy() method, SQLite considers the sqlite3_pcache* handle invalid, and will not use it with any other sqlite3_pcache_methods functions.

SQL Statement Object

typedef struct sqlite3_stmt sqlite3_stmt;

An instance of this object represents a single SQL statement. This object is variously known as a "prepared statement" or a "compiled SQL statement" or simply as a "statement".

The life of a statement object goes something like this:

  1. Create the object using sqlite3_prepare_v2() or a related function.
  2. Bind values to host parameters using the sqlite3_bind_*() interfaces.
  3. Run the SQL by calling sqlite3_step() one or more times.
  4. Reset the statement using sqlite3_reset() then go back to step 2. Do this zero or more times.
  5. Destroy the object using sqlite3_finalize().

Refer to documentation on individual methods above for additional information.

Dynamically Typed Value Object

typedef struct Mem sqlite3_value;

SQLite uses the sqlite3_value object to represent all values that can be stored in a database table. SQLite uses dynamic typing for the values it stores. Values stored in sqlite3_value objects can be integers, floating point values, strings, BLOBs, or NULL.

An sqlite3_value object may be either "protected" or "unprotected". Some interfaces require a protected sqlite3_value. Other interfaces will accept either a protected or an unprotected sqlite3_value. Every interface that accepts sqlite3_value arguments specifies whether or not it requires a protected sqlite3_value.

The terms "protected" and "unprotected" refer to whether or not a mutex is held. An internal mutex is held for a protected sqlite3_value object but no mutex is held for an unprotected sqlite3_value object. If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0 and with sqlite3_threadsafe() returning 0) or if SQLite is run in one of reduced mutex modes SQLITE_CONFIG_SINGLETHREAD or SQLITE_CONFIG_MULTITHREAD then there is no distinction between protected and unprotected sqlite3_value objects and they can be used interchangeably. However, for maximum code portability it is recommended that applications still make the distinction between protected and unprotected sqlite3_value objects even when not strictly required.

The sqlite3_value objects that are passed as parameters into the implementation of application-defined SQL functions are protected. The sqlite3_value object returned by sqlite3_column_value() is unprotected. Unprotected sqlite3_value objects may only be used with sqlite3_result_value() and sqlite3_bind_value(). The sqlite3_value_type() family of interfaces require protected sqlite3_value objects.

Deprecated Functions

#ifndef SQLITE_OMIT_DEPRECATED
int sqlite3_aggregate_count(sqlite3_context*);
int sqlite3_expired(sqlite3_stmt*);
int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
int sqlite3_global_recover(void);
void sqlite3_thread_cleanup(void);
int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
#endif

These functions are deprecated. In order to maintain backwards compatibility with older code, these functions continue to be supported. However, new applications should avoid the use of these functions. To help encourage people to avoid using these functions, we are not going to tell you what they do.

Online Backup API.

sqlite3_backup *sqlite3_backup_init(
  sqlite3 *pDest,                        /* Destination database handle */
  const char *zDestName,                 /* Destination database name */
  sqlite3 *pSource,                      /* Source database handle */
  const char *zSourceName                /* Source database name */
);
int sqlite3_backup_step(sqlite3_backup *p, int nPage);
int sqlite3_backup_finish(sqlite3_backup *p);
int sqlite3_backup_remaining(sqlite3_backup *p);
int sqlite3_backup_pagecount(sqlite3_backup *p);

The backup API copies the content of one database into another. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

See Also: Using the SQLite Online Backup API

SQLite holds a write transaction open on the destination database file for the duration of the backup operation. The source database is read-locked only while it is being read; it is not locked continuously for the entire backup operation. Thus, the backup may be performed on a live source database without preventing other database connections from reading or writing to the source database while the backup is underway.

To perform a backup operation:

  1. sqlite3_backup_init() is called once to initialize the backup,
  2. sqlite3_backup_step() is called one or more times to transfer the data between the two databases, and finally
  3. sqlite3_backup_finish() is called to release all resources associated with the backup operation.
There should be exactly one call to sqlite3_backup_finish() for each successful call to sqlite3_backup_init().

sqlite3_backup_init()

The D and N arguments to sqlite3_backup_init(D,N,S,M) are the database connection associated with the destination database and the database name, respectively. The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database. The S and M arguments passed to sqlite3_backup_init(D,N,S,M) identify the database connection and database name of the source database, respectively. The source and destination database connections (parameters S and D) must be different or else sqlite3_backup_init(D,N,S,M) will fail with an error.

If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is returned and an error code and error message are stored in the destination database connection D. The error code and message for the failed call to sqlite3_backup_init() can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), and/or sqlite3_errmsg16() functions. A successful call to sqlite3_backup_init() returns a pointer to an sqlite3_backup object. The sqlite3_backup object may be used with the sqlite3_backup_step() and sqlite3_backup_finish() functions to perform the specified backup operation.

sqlite3_backup_step()

Function sqlite3_backup_step(B,N) will copy up to N pages between the source and destination databases specified by sqlite3_backup object B. If N is negative, all remaining source pages are copied. If sqlite3_backup_step(B,N) successfully copies N pages and there are still more pages to be copied, then the function returns SQLITE_OK. If sqlite3_backup_step(B,N) successfully finishes copying all pages from source to destination, then it returns SQLITE_DONE. If an error occurs while running sqlite3_backup_step(B,N), then an error code is returned. As well as SQLITE_OK and SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX extended error code.

The sqlite3_backup_step() might return SQLITE_READONLY if

  1. the destination database was opened read-only, or
  2. the destination database is using write-ahead-log journaling and the destination and source page sizes differ, or
  3. the destination database is an in-memory database and the destination and source page sizes differ.

If sqlite3_backup_step() cannot obtain a required file-system lock, then the busy-handler function is invoked (if one is specified). If the busy-handler returns non-zero before the lock is available, then SQLITE_BUSY is returned to the caller. In this case the call to sqlite3_backup_step() can be retried later. If the source database connection is being used to write to the source database when sqlite3_backup_step() is called, then SQLITE_LOCKED is returned immediately. Again, in this case the call to sqlite3_backup_step() can be retried later on. If SQLITE_IOERR_XXX, SQLITE_NOMEM, or SQLITE_READONLY is returned, then there is no point in retrying the call to sqlite3_backup_step(). These errors are considered fatal. The application must accept that the backup operation has failed and pass the backup operation handle to the sqlite3_backup_finish() to release associated resources.

The first call to sqlite3_backup_step() obtains an exclusive lock on the destination file. The exclusive lock is not released until either sqlite3_backup_finish() is called or the backup operation is complete and sqlite3_backup_step() returns SQLITE_DONE. Every call to sqlite3_backup_step() obtains a shared lock on the source database that lasts for the duration of the sqlite3_backup_step() call. Because the source database is not locked between calls to sqlite3_backup_step(), the source database may be modified mid-way through the backup process. If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be automatically restarted by the next call to sqlite3_backup_step(). If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is automatically updated at the same time.

sqlite3_backup_finish()

When sqlite3_backup_step() has returned SQLITE_DONE, or when the application wishes to abandon the backup operation, the application should destroy the sqlite3_backup by passing it to sqlite3_backup_finish(). The sqlite3_backup_finish() interfaces releases all resources associated with the sqlite3_backup object. If sqlite3_backup_step() has not yet returned SQLITE_DONE, then any active write-transaction on the destination database is rolled back. The sqlite3_backup object is invalid and may not be used following a call to sqlite3_backup_finish().

The value returned by sqlite3_backup_finish is SQLITE_OK if no sqlite3_backup_step() errors occurred, regardless or whether or not sqlite3_backup_step() completed. If an out-of-memory condition or IO error occurred during any prior sqlite3_backup_step() call on the same sqlite3_backup object, then sqlite3_backup_finish() returns the corresponding error code.

A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is not a permanent error and does not affect the return value of sqlite3_backup_finish().

sqlite3_backup_remaining() and sqlite3_backup_pagecount()

Each call to sqlite3_backup_step() sets two values inside the sqlite3_backup object: the number of pages still to be backed up and the total number of pages in the source database file. The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces retrieve these two values, respectively.

The values returned by these functions are only updated by sqlite3_backup_step(). If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.

Concurrent Usage of Database Handles

The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized. If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.

However, the application must guarantee that the destination database connection is not passed to any other API (by any thread) after sqlite3_backup_init() is called and before the corresponding call to sqlite3_backup_finish(). SQLite does not currently check to see if the application incorrectly accesses the destination database connection and so no error code is reported, but the operations may malfunction nevertheless. Use of the destination database connection while a backup is in progress might also also cause a mutex deadlock.

If running in shared cache mode, the application must guarantee that the shared cache used by the destination database is not accessed while the backup is running. In practice this means that the application must guarantee that the disk file being backed up to is not accessed by any connection within the process, not just the specific connection that was passed to sqlite3_backup_init().

The sqlite3_backup object itself is partially threadsafe. Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() APIs are not strictly speaking threadsafe. If they are invoked at the same time as another thread is invoking sqlite3_backup_step() it is possible that they return invalid values.

Collation Needed Callbacks

int sqlite3_collation_needed(
  sqlite3*,
  void*,
  void(*)(void*,sqlite3*,int eTextRep,const char*)
);
int sqlite3_collation_needed16(
  sqlite3*,
  void*,
  void(*)(void*,sqlite3*,int eTextRep,const void*)
);

To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database connection to be invoked whenever an undefined collation sequence is required.

If the function is registered using the sqlite3_collation_needed() API, then it is passed the names of undefined collation sequences as strings encoded in UTF-8. If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. A call to either function replaces the existing collation-needed callback.

When the callback is invoked, the first argument passed is a copy of the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). The second argument is the database connection. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, or SQLITE_UTF16LE, indicating the most desirable form of the collation sequence function required. The fourth parameter is the name of the required collation sequence.

The callback function should register the desired collation using sqlite3_create_collation(), sqlite3_create_collation16(), or sqlite3_create_collation_v2().

Source Of Data In A Query Result

const char *sqlite3_column_database_name(sqlite3_stmt*,int);
const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
const char *sqlite3_column_table_name(sqlite3_stmt*,int);
const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);

These routines provide a means to determine the database, table, and table column that is the origin of a particular result column in SELECT statement. The name of the database or table or column can be returned as either a UTF-8 or UTF-16 string. The _database_ routines return the database name, the _table_ routines return the table name, and the origin_ routines return the column name. The returned string is valid until the prepared statement is destroyed using sqlite3_finalize() or until the statement is automatically reprepared by the first call to sqlite3_step() for a particular run or until the same information is requested again in a different encoding.

The names returned are the original un-aliased names of the database, table, and column.

The first argument to these interfaces is a prepared statement. These functions return information about the Nth result column returned by the statement, where N is the second function argument. The left-most column is column 0 for these routines.

If the Nth column returned by the statement is an expression or subquery and is not a column value, then all of these functions return NULL. These routine might also return NULL if a memory allocation error occurs. Otherwise, they return the name of the attached database, table, or column that query result column was extracted from.

As with all other SQLite APIs, those whose names end with "16" return UTF-16 encoded strings and the other functions return UTF-8.

These APIs are only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol.

If two or more threads call one or more of these routines against the same prepared statement and column at the same time then the results are undefined.

If two or more threads call one or more column metadata interfaces for the same prepared statement and result column at the same time then the results are undefined.

Declared Datatype Of A Query Result

const char *sqlite3_column_decltype(sqlite3_stmt*,int);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

The first parameter is a prepared statement. If this statement is a SELECT statement and the Nth column of the returned result set of that SELECT is a table column (not an expression or subquery) then the declared type of the table column is returned. If the Nth column of the result set is an expression or subquery, then a NULL pointer is returned. The returned string is always UTF-8 encoded.

For example, given the database schema:

CREATE TABLE t1(c1 VARIANT);

and the following statement to be compiled:

SELECT c1 + 1, c1 FROM t1;

this routine would return the string "VARIANT" for the second result column (i==1), and a NULL pointer for the first result column (i==0).

SQLite uses dynamic run-time typing. So just because a column is declared to contain a particular type does not mean that the data stored in that column is of the declared type. SQLite is strongly typed, but the typing is dynamic not static. Type is associated with individual values, not with the containers used to hold those values.

Column Names In A Result Set

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

These routines return the name assigned to a particular column in the result set of a SELECT statement. The sqlite3_column_name() interface returns a pointer to a zero-terminated UTF-8 string and sqlite3_column_name16() returns a pointer to a zero-terminated UTF-16 string. The first parameter is the prepared statement that implements the SELECT statement. The second parameter is the column number. The leftmost column is number 0.

The returned string pointer is valid until either the prepared statement is destroyed by sqlite3_finalize() or until the statement is automatically reprepared by the first call to sqlite3_step() for a particular run or until the next call to sqlite3_column_name() or sqlite3_column_name16() on the same column.

If sqlite3_malloc() fails during the processing of either routine (for example during a conversion from UTF-8 to UTF-16) then a NULL pointer is returned.

The name of a result column is the value of the "AS" clause for that column, if there is an AS clause. If there is no AS clause then the name of the column is unspecified and may change from one release of SQLite to the next.

Commit And Rollback Notification Callbacks

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

The sqlite3_commit_hook() interface registers a callback function to be invoked whenever a transaction is committed. Any callback set by a previous call to sqlite3_commit_hook() for the same database connection is overridden. The sqlite3_rollback_hook() interface registers a callback function to be invoked whenever a transaction is rolled back. Any callback set by a previous call to sqlite3_rollback_hook() for the same database connection is overridden. The pArg argument is passed through to the callback. If the callback on a commit hook function returns non-zero, then the commit is converted into a rollback.

The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions return the P argument from the previous call of the same function on the same database connection D, or NULL for the first call for each function on D.

The callback implementation must not do anything that will modify the database connection that invoked the callback. Any actions to modify the database connection must be deferred until after the completion of the sqlite3_step() call that triggered the commit or rollback hook in the first place. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

Registering a NULL function disables the callback.

When the commit hook callback routine returns zero, the COMMIT operation is allowed to continue normally. If the commit hook returns non-zero, then the COMMIT is converted into a ROLLBACK. The rollback hook is invoked on a rollback that results from a commit hook returning non-zero, just as it would be with any other rollback.

For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. The rollback callback is not invoked if a transaction is automatically rolled back because the database connection is closed.

See also the sqlite3_update_hook() interface.

Run-Time Library Compilation Options Diagnostics

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
int sqlite3_compileoption_used(const char *zOptName);
const char *sqlite3_compileoption_get(int N);
#endif

The sqlite3_compileoption_used() function returns 0 or 1 indicating whether the specified option was defined at compile time. The SQLITE_ prefix may be omitted from the option name passed to sqlite3_compileoption_used().

The sqlite3_compileoption_get() function allows iterating over the list of options that were defined at compile time by returning the N-th compile time option string. If N is out of range, sqlite3_compileoption_get() returns a NULL pointer. The SQLITE_ prefix is omitted from any strings returned by sqlite3_compileoption_get().

Support for the diagnostic functions sqlite3_compileoption_used() and sqlite3_compileoption_get() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.

See also: SQL functions sqlite_compileoption_used() and sqlite_compileoption_get() and the compile_options pragma.

Determine If An SQL Statement Is Complete

int sqlite3_complete(const char *sql);
int sqlite3_complete16(const void *sql);

These routines are useful during command-line input to determine if the currently entered text seems to form a complete SQL statement or if additional input is needed before sending the text into SQLite for parsing. These routines return 1 if the input string appears to be a complete SQL statement. A statement is judged to be complete if it ends with a semicolon token and is not a prefix of a well-formed CREATE TRIGGER statement. Semicolons that are embedded within string literals or quoted identifier names or comments are not independent tokens (they are part of the token in which they are embedded) and thus do not count as a statement terminator. Whitespace and comments that follow the final semicolon are ignored.

These routines return 0 if the statement is incomplete. If a memory allocation fails, then SQLITE_NOMEM is returned.

These routines do not parse the SQL statements thus will not detect syntactically incorrect SQL.

If SQLite has not been initialized using sqlite3_initialize() prior to invoking sqlite3_complete16() then sqlite3_initialize() is invoked automatically by sqlite3_complete16(). If that initialization fails, then the return value from sqlite3_complete16() will be non-zero regardless of whether or not the input SQL is complete.

The input to sqlite3_complete() must be a zero-terminated UTF-8 string.

The input to sqlite3_complete16() must be a zero-terminated UTF-16 string in native byte order.

Define New Collating Sequences

int sqlite3_create_collation(
  sqlite3*,
  const char *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);
int sqlite3_create_collation_v2(
  sqlite3*,
  const char *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*),
  void(*xDestroy)(void*)
);
int sqlite3_create_collation16(
  sqlite3*,
  const void *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);

These functions add, remove, or modify a collation associated with the database connection specified as the first argument.

The name of the collation is a UTF-8 string for sqlite3_create_collation() and sqlite3_create_collation_v2() and a UTF-16 string in native byte order for sqlite3_create_collation16(). Collation names that compare equal according to sqlite3_strnicmp() are considered to be the same name.

The third argument (eTextRep) must be one of the constants:

  • SQLITE_UTF8,
  • SQLITE_UTF16LE,
  • SQLITE_UTF16BE,
  • SQLITE_UTF16, or
  • SQLITE_UTF16_ALIGNED.
The eTextRep argument determines the encoding of strings passed to the collating function callback, xCallback. The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED values for eTextRep force strings to be UTF16 with native byte order. The SQLITE_UTF16_ALIGNED value for eTextRep forces strings to begin on an even byte address.

The fourth argument, pArg, is an application data pointer that is passed through as the first argument to the collating function callback.

The fifth argument, xCallback, is a pointer to the collating function. Multiple collating functions can be registered using the same name but with different eTextRep parameters and SQLite will use whichever function requires the least amount of data transformation. If the xCallback argument is NULL then the collating function is deleted. When all collating functions having the same name are deleted, that collation is no longer usable.

The collating function callback is invoked with a copy of the pArg application data pointer and with two strings in the encoding specified by the eTextRep argument. The collating function must return an integer that is negative, zero, or positive if the first string is less than, equal to, or greater than the second, respectively. A collating function must always return the same answer given the same inputs. If two or more collating functions are registered to the same collation name (using different eTextRep values) then all must give an equivalent answer when invoked with equivalent strings. The collating function must obey the following properties for all strings A, B, and C:

  1. If A==B then B==A.
  2. If A==B and B==C then A==C.
  3. If A<B THEN B>A.
  4. If A<B and B<C then A<C.

If a collating function fails any of the above constraints and that collating function is registered and used, then the behavior of SQLite is undefined.

The sqlite3_create_collation_v2() works like sqlite3_create_collation() with the addition that the xDestroy callback is invoked on pArg when the collating function is deleted. Collating functions are deleted when they are overridden by later calls to the collation creation functions or when the database connection is closed using sqlite3_close().

The xDestroy callback is not called if the sqlite3_create_collation_v2() function fails. Applications that invoke sqlite3_create_collation_v2() with a non-NULL xDestroy argument should check the return code and dispose of the application data pointer themselves rather than expecting SQLite to deal with it for them. This is different from every other SQLite interface. The inconsistency is unfortunate but cannot be changed without breaking backwards compatibility.

See also: sqlite3_collation_needed() and sqlite3_collation_needed16().

Register A Virtual Table Implementation

int sqlite3_create_module(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData          /* Client data for xCreate/xConnect */
);
int sqlite3_create_module_v2(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData,         /* Client data for xCreate/xConnect */
  void(*xDestroy)(void*)     /* Module destructor function */
);

These routines are used to register a new virtual table module name. Module names must be registered before creating a new virtual table using the module and before using a preexisting virtual table for the module.

The module name is registered on the database connection specified by the first parameter. The name of the module is given by the second parameter. The third parameter is a pointer to the implementation of the virtual table module. The fourth parameter is an arbitrary client data pointer that is passed through into the xCreate and xConnect methods of the virtual table module when a new virtual table is be being created or reinitialized.

The sqlite3_create_module_v2() interface has a fifth parameter which is a pointer to a destructor for the pClientData. SQLite will invoke the destructor function (if it is not NULL) when SQLite no longer needs the pClientData pointer. The destructor will also be invoked if the call to sqlite3_create_module_v2() fails. The sqlite3_create_module() interface is equivalent to sqlite3_create_module_v2() with a NULL destructor.

Error Codes And Messages

int sqlite3_errcode(sqlite3 *db);
int sqlite3_extended_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);

The sqlite3_errcode() interface returns the numeric result code or extended result code for the most recent failed sqlite3_* API call associated with a database connection. If a prior API call failed but the most recent API call succeeded, the return value from sqlite3_errcode() is undefined. The sqlite3_extended_errcode() interface is the same except that it always returns the extended result code even when extended result codes are disabled.

The sqlite3_errmsg() and sqlite3_errmsg16() return English-language text that describes the error, as either UTF-8 or UTF-16 respectively. Memory to hold the error message string is managed internally. The application does not need to worry about freeing the result. However, the error string might be overwritten or deallocated by subsequent calls to other SQLite interface functions.

When the serialized threading mode is in use, it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to these interfaces. When that happens, the second error will be reported since these interfaces always report the most recent result. To avoid this, each thread can obtain exclusive use of the database connection D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) after all calls to the interfaces listed here are completed.

If an interface fails with SQLITE_MISUSE, that means the interface was invoked incorrectly by the application. In that case, the error code and message may or may not be set.

Memory Allocation Subsystem

void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);

The SQLite core uses these three routines for all of its own internal memory allocation needs. "Core" in the previous sentence does not include operating-system specific VFS implementation. The Windows VFS uses native malloc() and free() for some operations.

The sqlite3_malloc() routine returns a pointer to a block of memory at least N bytes in length, where N is the parameter. If sqlite3_malloc() is unable to obtain sufficient free memory, it returns a NULL pointer. If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() returns a NULL pointer.

Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() or sqlite3_realloc() releases that memory so that it might be reused. The sqlite3_free() routine is a no-op if is called with a NULL pointer. Passing a NULL pointer to sqlite3_free() is harmless. After being freed, memory should neither be read nor written. Even reading previously freed memory might result in a segmentation fault or other severe error. Memory corruption, a segmentation fault, or other severe error might result if sqlite3_free() is called with a non-NULL pointer that was not obtained from sqlite3_malloc() or sqlite3_realloc().

The sqlite3_realloc() interface attempts to resize a prior memory allocation to be at least N bytes, where N is the second parameter. The memory allocation to be resized is the first parameter. If the first parameter to sqlite3_realloc() is a NULL pointer then its behavior is identical to calling sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). If the second parameter to sqlite3_realloc() is zero or negative then the behavior is exactly the same as calling sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). sqlite3_realloc() returns a pointer to a memory allocation of at least N bytes in size or NULL if sufficient memory is unavailable. If M is the size of the prior allocation, then min(N,M) bytes of the prior allocation are copied into the beginning of buffer returned by sqlite3_realloc() and the prior allocation is freed. If sqlite3_realloc() returns NULL, then the prior allocation is not freed.

The memory returned by sqlite3_malloc() and sqlite3_realloc() is always aligned to at least an 8 byte boundary, or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC compile-time option is used.

In SQLite version 3.5.0 and 3.5.1, it was possible to define the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in implementation of these routines to be omitted. That capability is no longer provided. Only built-in memory allocators can be used.

The Windows OS interface layer calls the system malloc() and free() directly when converting filenames between the UTF-8 encoding used by SQLite and whatever filename encoding is used by the particular Windows installation. Memory allocation errors are detected, but they are reported back as SQLITE_CANTOPEN or SQLITE_IOERR rather than SQLITE_NOMEM.

The pointer arguments to sqlite3_free() and sqlite3_realloc() must be either NULL or else pointers obtained from a prior invocation of sqlite3_malloc() or sqlite3_realloc() that have not yet been released.

The application must not read or write any part of a block of memory after it has been released using sqlite3_free() or sqlite3_realloc().

Convenience Routines For Running Queries

int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);
void sqlite3_free_table(char **result);

This is a legacy interface that is preserved for backwards compatibility. Use of this interface is not recommended.

Definition: A result table is memory data structure created by the sqlite3_get_table() interface. A result table records the complete query results from one or more queries.

The table conceptually has a number of rows and columns. But these numbers are not part of the result table itself. These numbers are obtained separately. Let N be the number of rows and M be the number of columns.

A result table is an array of pointers to zero-terminated UTF-8 strings. There are (N+1)*M elements in the array. The first M pointers point to zero-terminated strings that contain the names of the columns. The remaining entries all point to query results. NULL values result in NULL pointers. All other values are in their UTF-8 zero-terminated string representation as returned by sqlite3_column_text().

A result table might consist of one or more memory allocations. It is not safe to pass a result table directly to sqlite3_free(). A result table should be deallocated using sqlite3_free_table().

As an example of the result table format, suppose a query result is as follows:

Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21

There are two column (M==2) and three rows (N==3). Thus the result table has 8 entries. Suppose the result table is stored in an array names azResult. Then azResult holds this content:

azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";

The sqlite3_get_table() function evaluates one or more semicolon-separated SQL statements in the zero-terminated UTF-8 string of its 2nd parameter and returns a result table to the pointer given in its 3rd parameter.

After the application has finished with the result from sqlite3_get_table(), it must pass the result table pointer to sqlite3_free_table() in order to release the memory that was malloced. Because of the way the sqlite3_malloc() happens within sqlite3_get_table(), the calling function must not try to call sqlite3_free() directly. Only sqlite3_free_table() is able to release the memory properly and safely.

The sqlite3_get_table() interface is implemented as a wrapper around sqlite3_exec(). The sqlite3_get_table() routine does not have access to any internal data structures of SQLite. It uses only the public interface defined here. As a consequence, errors that occur in the wrapper layer outside of the internal sqlite3_exec() call are not reflected in subsequent calls to sqlite3_errcode() or sqlite3_errmsg().

Function Auxiliary Data

void *sqlite3_get_auxdata(sqlite3_context*, int N);
void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

The following two functions may be used by scalar SQL functions to associate metadata with argument values. If the same value is passed to multiple invocations of the same SQL function during query execution, under some circumstances the associated metadata may be preserved. This may be used, for example, to add a regular-expression matching scalar function. The compiled version of the regular expression is stored as metadata associated with the SQL value passed as the regular expression pattern. The compiled regular expression can be reused on multiple invocations of the same function so that the original pattern string does not need to be recompiled on each invocation.

The sqlite3_get_auxdata() interface returns a pointer to the metadata associated by the sqlite3_set_auxdata() function with the Nth argument value to the application-defined function. If no metadata has been ever been set for the Nth argument of the function, or if the corresponding function parameter has changed since the meta-data was set, then sqlite3_get_auxdata() returns a NULL pointer.

The sqlite3_set_auxdata() interface saves the metadata pointed to by its 3rd parameter as the metadata for the N-th argument of the application-defined function. Subsequent calls to sqlite3_get_auxdata() might return this data, if it has not been destroyed. If it is not NULL, SQLite will invoke the destructor function given by the 4th parameter to sqlite3_set_auxdata() on the metadata when the corresponding function parameter changes or when the SQL statement completes, whichever comes first.

SQLite is free to call the destructor and drop metadata on any parameter of any function at any time. The only guarantee is that the destructor will be called before the metadata is dropped.

In practice, metadata is preserved between function calls for expressions that are constant at compile time. This includes literal values and parameters.

These routines must be called from the same thread in which the SQL function is running.

Initialize The SQLite Library

int sqlite3_initialize(void);
int sqlite3_shutdown(void);
int sqlite3_os_init(void);
int sqlite3_os_end(void);

The sqlite3_initialize() routine initializes the SQLite library. The sqlite3_shutdown() routine deallocates any resources that were allocated by sqlite3_initialize(). These routines are designed to aid in process initialization and shutdown on embedded systems. Workstation applications using SQLite normally do not need to invoke either of these routines.

A call to sqlite3_initialize() is an "effective" call if it is the first time sqlite3_initialize() is invoked during the lifetime of the process, or if it is the first time sqlite3_initialize() is invoked following a call to sqlite3_shutdown(). Only an effective call of sqlite3_initialize() does any initialization. All other calls are harmless no-ops.

A call to sqlite3_shutdown() is an "effective" call if it is the first call to sqlite3_shutdown() since the last sqlite3_initialize(). Only an effective call to sqlite3_shutdown() does any deinitialization. All other valid calls to sqlite3_shutdown() are harmless no-ops.

The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() is not. The sqlite3_shutdown() interface must only be called from a single thread. All open database connections must be closed and all other SQLite resources must be deallocated prior to invoking sqlite3_shutdown().

Among other things, sqlite3_initialize() will invoke
sqlite3_os_init().  Similarly, sqlite3_shutdown()
will invoke sqlite3_os_end().

The sqlite3_initialize() routine returns SQLITE_OK on success. If for some reason, sqlite3_initialize() is unable to initialize the library (perhaps it is unable to allocate a needed resource such as a mutex) it returns an error code other than SQLITE_OK.

The sqlite3_initialize() routine is called internally by many other SQLite interfaces so that an application usually does not need to invoke sqlite3_initialize() directly. For example, sqlite3_open() calls sqlite3_initialize() so the SQLite library will be automatically initialized when sqlite3_open() is called if it has not be initialized already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT compile-time option, then the automatic calls to sqlite3_initialize() are omitted and the application must call sqlite3_initialize() directly prior to using any other SQLite interface. For maximum portability, it is recommended that applications always invoke sqlite3_initialize() directly prior to using any other SQLite interface. Future releases of SQLite may require this. In other words, the behavior exhibited when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the default behavior in some future release of SQLite.

The sqlite3_os_init() routine does operating-system specific initialization of the SQLite library. The sqlite3_os_end() routine undoes the effect of sqlite3_os_init(). Typical tasks performed by these routines include allocation or deallocation of static resources, initialization of global variables, setting up a default sqlite3_vfs module, or setting up a default configuration using sqlite3_config().

The application should never invoke either sqlite3_os_init() or sqlite3_os_end() directly. The application should only invoke sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() interface is called automatically by sqlite3_initialize() and sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate implementations for sqlite3_os_init() and sqlite3_os_end() are built into SQLite when it is compiled for Unix, Windows, or OS/2. When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time option) the application must supply a suitable implementation for sqlite3_os_init() and sqlite3_os_end(). An application-supplied implementation of sqlite3_os_init() or sqlite3_os_end() must return SQLITE_OK on success and some other error code upon failure.

Run-Time Library Version Numbers

SQLITE_EXTERN const char sqlite3_version[];
const char *sqlite3_libversion(void);
const char *sqlite3_sourceid(void);
int sqlite3_libversion_number(void);

These interfaces provide the same information as the SQLITE_VERSION, SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros but are associated with the library instead of the header file. Cautious programmers might include assert() statements in their application to verify that values returned by these interfaces match the macros in the header, and thus insure that the application is compiled with matching library and header files.

assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

The sqlite3_version[] string constant contains the text of SQLITE_VERSION macro. The sqlite3_libversion() function returns a pointer to the to the sqlite3_version[] string constant. The sqlite3_libversion() function is provided for use in DLLs since DLL users usually do not have direct access to string constants within the DLL. The sqlite3_libversion_number() function returns an integer equal to SQLITE_VERSION_NUMBER. The sqlite3_sourceid() function returns a pointer to a string constant whose value is the same as the SQLITE_SOURCE_ID C preprocessor macro.

See also: sqlite_version() and sqlite_source_id().

Memory Allocator Statistics

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

SQLite provides these two interfaces for reporting on the status of the sqlite3_malloc(), sqlite3_free(), and sqlite3_realloc() routines, which form the built-in memory allocation subsystem.

The sqlite3_memory_used() routine returns the number of bytes of memory currently outstanding (malloced but not freed). The sqlite3_memory_highwater() routine returns the maximum value of sqlite3_memory_used() since the high-water mark was last reset. The values returned by sqlite3_memory_used() and sqlite3_memory_highwater() include any overhead added by SQLite in its implementation of sqlite3_malloc(), but not overhead added by the any underlying system library routines that sqlite3_malloc() may call.

The memory high-water mark is reset to the current value of sqlite3_memory_used() if and only if the parameter to sqlite3_memory_highwater() is true. The value returned by sqlite3_memory_highwater(1) is the high-water mark prior to the reset.

Formatted String Printing Functions

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);

These routines are work-alikes of the "printf()" family of functions from the standard C library.

The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results into memory obtained from sqlite3_malloc(). The strings returned by these two routines should be released by sqlite3_free(). Both routines return a NULL pointer if sqlite3_malloc() is unable to allocate enough memory to hold the resulting string.

The sqlite3_snprintf() routine is similar to "snprintf()" from the standard C library. The result is written into the buffer supplied as the second parameter whose size is given by the first parameter. Note that the order of the first two parameters is reversed from snprintf(). This is an historical accident that cannot be fixed without breaking backwards compatibility. Note also that sqlite3_snprintf() returns a pointer to its buffer instead of the number of characters actually written into the buffer. We admit that the number of characters written would be a more useful return value but we cannot change the implementation of sqlite3_snprintf() now without breaking compatibility.

As long as the buffer size is greater than zero, sqlite3_snprintf() guarantees that the buffer is always zero-terminated. The first parameter "n" is the total size of the buffer, including space for the zero terminator. So the longest string that can be completely written will be n-1 characters.

The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().

These routines all implement some additional formatting options that are useful for constructing SQL statements. All of the usual printf() formatting options apply. In addition, there is are "%q", "%Q", and "%z" options.

The %q option works like %s in that it substitutes a null-terminated string from the argument list. But %q also doubles every '\'' character. %q is designed for use inside a string literal. By doubling each '\'' character it escapes that character and allows it to be inserted into the string.

For example, assume the string variable zText contains text as follows:

char *zText = "It's a happy day!";

One can use this text in an SQL statement as follows:

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);

Because the %q format string is used, the '\'' character in zText is escaped and the SQL generated is as follows:

INSERT INTO table1 VALUES('It''s a happy day!')

This is correct. Had we used %s instead of %q, the generated SQL would have looked like this:

INSERT INTO table1 VALUES('It's a happy day!');

This second example is an SQL syntax error. As a general rule you should always use %q instead of %s when inserting text into a string literal.

The %Q option works like %q except it also adds single quotes around the outside of the total string. Additionally, if the parameter in the argument list is a NULL pointer, %Q substitutes the text "NULL" (without single quotes). So, for example, one could say:

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);

The code above will render a correct SQL statement in the zSQL variable even if the zText variable is a NULL pointer.

The "%z" formatting option works like "%s" but with the addition that after the string has been read and copied into the result, sqlite3_free() is called on the input string.

Mutexes

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);

The SQLite core uses these routines for thread synchronization. Though they are intended for internal use by SQLite, code that links against SQLite is permitted to use any of these routines.

The SQLite source code contains multiple implementations of these mutex routines. An appropriate implementation is selected automatically at compile-time. The following implementations are available in the SQLite core:

  • SQLITE_MUTEX_OS2
  • SQLITE_MUTEX_PTHREAD
  • SQLITE_MUTEX_W32
  • SQLITE_MUTEX_NOOP

The SQLITE_MUTEX_NOOP implementation is a set of routines that does no real locking and is appropriate for use in a single-threaded application. The SQLITE_MUTEX_OS2, SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations are appropriate for use on OS/2, Unix, and Windows.

If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex implementation is included with the library. In this case the application must supply a custom mutex implementation using the SQLITE_CONFIG_MUTEX option of the sqlite3_config() function before calling sqlite3_initialize() or any other public sqlite3_ function that calls sqlite3_initialize().

The sqlite3_mutex_alloc() routine allocates a new mutex and returns a pointer to it. If it returns NULL that means that a mutex could not be allocated. SQLite will unwind its stack and return an error. The argument to sqlite3_mutex_alloc() is one of these integer constants:

  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_MUTEX_STATIC_LRU
  • SQLITE_MUTEX_STATIC_LRU2

The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) cause sqlite3_mutex_alloc() to create a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but not necessarily so when SQLITE_MUTEX_FAST is used. The mutex implementation does not need to make a distinction between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. SQLite will only request a recursive mutex in cases where it really needs one. If a faster non-recursive mutex implementation is available on the host platform, the mutex subsystem might return such a mutex in response to SQLITE_MUTEX_FAST.

The other allowed parameters to sqlite3_mutex_alloc() (anything other than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer to a static preexisting mutex. Six static mutexes are used by the current version of SQLite. Future versions of SQLite may add additional static mutexes. Static mutexes are for internal use by SQLite only. Applications that use SQLite mutexes should use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE.

Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns a different mutex on every call. But for the static mutex types, the same mutex is returned on every call that has the same type number.

The sqlite3_mutex_free() routine deallocates a previously allocated dynamic mutex. SQLite is careful to deallocate every dynamic mutex that it allocates. The dynamic mutexes must not be in use when they are deallocated. Attempting to deallocate a static mutex results in undefined behavior. SQLite never deallocates a static mutex.

The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt to enter a mutex. If another thread is already within the mutex, sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. In such cases the, mutex must be exited an equal number of times before another thread can enter. If the same thread tries to enter any other kind of mutex more than once, the behavior is undefined. SQLite will never exhibit such behavior in its own use of mutexes.

Some systems (for example, Windows 95) do not support the operation implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. The SQLite core only ever uses sqlite3_mutex_try() as an optimization so this is acceptable behavior.

The sqlite3_mutex_leave() routine exits a mutex that was previously entered by the same thread. The behavior is undefined if the mutex is not currently entered by the calling thread or is not currently allocated. SQLite will never do either.

If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or sqlite3_mutex_leave() is a NULL pointer, then all three routines behave as no-ops.

See also: sqlite3_mutex_held() and sqlite3_mutex_notheld().

Mutex Verification Routines

#ifndef NDEBUG
int sqlite3_mutex_held(sqlite3_mutex*);
int sqlite3_mutex_notheld(sqlite3_mutex*);
#endif

The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended for use inside assert() statements. The SQLite core never uses these routines except inside an assert() and applications are advised to follow the lead of the core. The SQLite core only provides implementations for these routines when it is compiled with the SQLITE_DEBUG flag. External mutex implementations are only required to provide these routines if SQLITE_DEBUG is defined and if NDEBUG is not defined.

These routines should return true if the mutex in their argument is held or not held, respectively, by the calling thread.

The implementation is not required to provided versions of these routines that actually work. If the implementation does not provide working versions of these routines, it should at least provide stubs that always return true so that one does not get spurious assertion failures.

If the argument to sqlite3_mutex_held() is a NULL pointer then the routine should return 1. This seems counter-intuitive since clearly the mutex cannot be held if it does not exist. But the reason the mutex does not exist is because the build is not using mutexes. And we do not want the assert() containing the call to sqlite3_mutex_held() to fail, so a non-zero return is the appropriate thing to do. The sqlite3_mutex_notheld() interface should also return 1 when given a NULL pointer.

Opening A New Database Connection

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the sqlite3 object, a NULL will be written into *ppDb instead of a pointer to the sqlite3 object. If the database is opened (and/or created) successfully, then SQLITE_OK is returned. Otherwise an error code is returned. The sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.

The default encoding for the database will be UTF-8 if sqlite3_open() or sqlite3_open_v2() is called and UTF-16 in the native byte order if sqlite3_open16() is used.

Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close() when it is no longer required.

The sqlite3_open_v2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to sqlite3_open_v2() can take one of the following three values, optionally combined with the SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, SQLITE_OPEN_PRIVATECACHE, and/or SQLITE_OPEN_URI flags:

SQLITE_OPEN_READONLY
The database is opened in read-only mode. If the database does not already exist, an error is returned.

SQLITE_OPEN_READWRITE
The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
The database is opened for reading and writing, and is created if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().

If the 3rd parameter to sqlite3_open_v2() is not one of the combinations shown above optionally combined with other SQLITE_OPEN_* bits then the behavior is undefined.

If the SQLITE_OPEN_NOMUTEX flag is set, then the database connection opens in the multi-thread threading mode as long as the single-thread mode has not been set at compile-time or start-time. If the SQLITE_OPEN_FULLMUTEX flag is set then the database connection opens in the serialized threading mode unless single-thread was previously selected at compile-time or start-time. The SQLITE_OPEN_SHAREDCACHE flag causes the database connection to be eligible to use shared cache mode, regardless of whether or not shared cache is enabled using sqlite3_enable_shared_cache(). The SQLITE_OPEN_PRIVATECACHE flag causes the database connection to not participate in shared cache mode even if it is enabled.

The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.

If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

URI Filenames

If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQLITE_OPEN_URI flag is set in the fourth argument to sqlite3_open_v2(), or if it has been enabled globally using the SQLITE_CONFIG_URI option with the sqlite3_config() method or by the SQLITE_USE_URI compile-time option. As of SQLite version 3.7.7, URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "URI filenames" for additional information.

URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.

SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").

The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite interprets the following three query parameters:

  • vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If sqlite3_open_v2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to sqlite3_open_v2().

  • mode: The mode parameter may be set to either "ro", "rw" or "rwc". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQLITE_OPEN_READONLY flag had been set in the third argument to sqlite3_prepare_v2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If sqlite3_open_v2() is used, it is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed as the third parameter.

  • cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to sqlite3_open_v2(). Setting the cache parameter to "private" is equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. If sqlite3_open_v2() is used and the "cache" parameter is present in a URI filename, its value overrides any behaviour requested by setting SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.

Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "query parameters with special meaning to SQLite" for additional information.

URI filename examples

URI filenames | Results
file:data.db | Open the file "data.db" in the current directory.
file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db".
file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames.
file:data.db?mode=ro&cache=private | Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache.
file:/home/fred/data.db?vfs=unix-nolock | Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter.

URI hexadecimal escape sequences (%HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.

Note to Windows users: The encoding used for the filename argument of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2().

Tracing And Profiling Functions

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
void *sqlite3_profile(sqlite3*,
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);

These routines register callback functions that can be used for tracing and profiling the execution of SQL statements.

The callback function registered by sqlite3_trace() is invoked at various times when an SQL statement is being run by sqlite3_step(). The sqlite3_trace() callback is invoked with a UTF-8 rendering of the SQL statement text as the statement first begins executing. Additional sqlite3_trace() callbacks might occur as each triggered subprogram is entered. The callbacks for triggers contain a UTF-8 SQL comment that identifies the trigger.

The callback function registered by sqlite3_profile() is invoked as each SQL statement finishes. The profile callback contains the original statement text and an estimate of wall-clock time of how long that statement took to run. The profile callback time is in units of nanoseconds, however the current implementation is only capable of millisecond resolution so the six least significant digits in the time are meaningless. Future versions of SQLite might provide greater resolution on the profiler callback. The sqlite3_profile() function is considered experimental and is subject to change in future versions of SQLite.

Setting The Result Of An SQL Function

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_zeroblob(sqlite3_context*, int n);

These routines are used by the xFunc or xFinal callbacks that implement SQL functions and aggregates. See sqlite3_create_function() and sqlite3_create_function16() for additional information.

These functions work very much like the parameter binding family of functions used to bind values to host parameters in prepared statements. Refer to the SQL parameter documentation for additional information.

The sqlite3_result_blob() interface sets the result from an application-defined function to be the BLOB whose content is pointed to by the second parameter and which is N bytes long where N is the third parameter.

The sqlite3_result_zeroblob() interfaces set the result of the application-defined function to be a BLOB containing all zero bytes and N bytes in size, where N is the value of the 2nd parameter.

The sqlite3_result_double() interface sets the result from an application-defined function to be a floating point value specified by its 2nd argument.

The sqlite3_result_error() and sqlite3_result_error16() functions cause the implemented SQL function to throw an exception. SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() as the text of an error message. SQLite interprets the error message string from sqlite3_result_error() as UTF-8. SQLite interprets the string from sqlite3_result_error16() as UTF-16 in native byte order. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is negative then SQLite takes as the error message all text up through the first zero character. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is non-negative then SQLite takes that many bytes (not characters) from the 2nd parameter as the error message. The sqlite3_result_error() and sqlite3_result_error16() routines make a private copy of the error message text before they return. Hence, the calling function can deallocate or modify the text after they return without harm. The sqlite3_result_error_code() function changes the error code returned by SQLite as a result of an error in a function. By default, the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() or sqlite3_result_error16() resets the error code to SQLITE_ERROR.

The sqlite3_result_toobig() interface causes SQLite to throw an error indicating that a string or BLOB is too long to represent.

The sqlite3_result_nomem() interface causes SQLite to throw an error indicating that a memory allocation failed.

The sqlite3_result_int() interface sets the return value of the application-defined function to be the 32-bit signed integer value given in the 2nd argument. The sqlite3_result_int64() interface sets the return value of the application-defined function to be the 64-bit signed integer value given in the 2nd argument.

The sqlite3_result_null() interface sets the return value of the application-defined function to be NULL.

The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces set the return value of the application-defined function to be a text string which is represented as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 big endian, respectively. SQLite takes the text result from the application from the 2nd parameter of the sqlite3_result_text* interfaces. If the 3rd parameter to the sqlite3_result_text* interfaces is negative, then SQLite takes result text from the 2nd parameter through the first zero character. If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, then as many bytes (not characters) of the text pointed to by the 2nd parameter are taken as the application-defined function result. If the 3rd parameter is non-negative, then it must be the byte offset into the string where the NUL terminator would appear if the string where NUL terminated. If any NUL characters occur in the string at a byte offset that is less than the value of the 3rd parameter, then the resulting string will contain embedded NULs and the result of expressions operating on strings with embedded NULs is undefined. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that function as the destructor on the text or BLOB result when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite assumes that the text or BLOB result is in constant space and does not copy the content of the parameter nor call a destructor on the content when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_TRANSIENT then SQLite makes a copy of the result into space obtained from from sqlite3_malloc() before it returns.

The sqlite3_result_value() interface sets the result of the application-defined function to be a copy the unprotected sqlite3_value object specified by the 2nd parameter. The sqlite3_result_value() interface makes a copy of the sqlite3_value so that the sqlite3_value specified in the parameter may change or be deallocated after sqlite3_result_value() returns without harm. A protected sqlite3_value object may always be used where an unprotected sqlite3_value object is required, so either kind of sqlite3_value object can be used with this interface.

If these routines are called from within the different thread than the one containing the application-defined function that received the sqlite3_context pointer, the results are undefined.

Obtaining SQL Function Parameter Values

const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
const void *sqlite3_value_text16be(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);

The C-language implementation of SQL functions and aggregates uses this set of interface routines to access the parameter values on the function or aggregate.

The xFunc (for scalar functions) or xStep (for aggregates) parameters to sqlite3_create_function() and sqlite3_create_function16() define callbacks that implement the SQL functions and aggregates. The 3rd parameter to these callbacks is an array of pointers to protected sqlite3_value objects. There is one sqlite3_value object for each parameter to the SQL function. These routines are used to extract values from the sqlite3_value objects.

These routines work only with protected sqlite3_value objects. Any attempt to use these routines on an unprotected sqlite3_value object results in undefined behavior.

These routines work just like the corresponding column access functions except that these routines take a single protected sqlite3_value object pointer instead of a sqlite3_stmt* pointer and an integer column number.

The sqlite3_value_text16() interface extracts a UTF-16 string in the native byte-order of the host machine. The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces extract UTF-16 strings as big-endian and little-endian respectively.

The sqlite3_value_numeric_type() interface attempts to apply numeric affinity to the value. This means that an attempt is made to convert the value to an integer or floating point. If such a conversion is possible without loss of information (in other words, if the value is a string that looks like a number) then the conversion is performed. Otherwise no conversion occurs. The datatype after conversion is returned.

Please pay particular attention to the fact that the pointer returned from sqlite3_value_blob(), sqlite3_value_text(), or sqlite3_value_text16() can be invalidated by a subsequent call to sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text(), or sqlite3_value_text16().

These routines must be called from the same thread as the SQL function that supplied the sqlite3_value* parameters.

Virtual File System Objects

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
int sqlite3_vfs_unregister(sqlite3_vfs*);

A virtual filesystem (VFS) is an sqlite3_vfs object that SQLite uses to interact with the underlying operating system. Most SQLite builds come with a single default VFS that is appropriate for the host computer. New VFSes can be registered and existing VFSes can be unregistered. The following interfaces are provided.

The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. Names are case sensitive. Names are zero-terminated UTF-8 strings. If there is no match, a NULL pointer is returned. If zVfsName is NULL then the default VFS is returned.

New VFSes are registered with sqlite3_vfs_register(). Each new VFS becomes the default VFS if the makeDflt flag is set. The same VFS can be registered multiple times without injury. To make an existing VFS into the default VFS, register it again with the makeDflt flag set. If two different VFSes with the same name are registered, the behavior is undefined. If a VFS is registered with a name that is NULL or an empty string, then the behavior is undefined.

Unregister a VFS with the sqlite3_vfs_unregister() interface. If the default VFS is unregistered, another VFS is chosen as the default. The choice for the new VFS is arbitrary.

Binding Values To Prepared Statements

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

In the SQL statement text input to sqlite3_prepare_v2() and its variants, literals may be replaced by a parameter that matches one of following templates:

  • ?
  • ?NNN
  • :VVV
  • @VVV
  • $VVV

In the templates above, NNN represents an integer literal, and VVV represents an alphanumeric identifier. The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the sqlite3_bind_*() routines defined here.

The first argument to the sqlite3_bind_*() routines is always a pointer to the sqlite3_stmt object returned from sqlite3_prepare_v2() or its variants.

The second argument is the index of the SQL parameter to be set. The leftmost SQL parameter has an index of 1. When the same named SQL parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence. The index for named parameters can be looked up using the sqlite3_bind_parameter_index() API if desired. The index for "?NNN" parameters is the value of NNN. The NNN value must be between 1 and the sqlite3_limit() parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value: 999).

The third argument is the value to bind to the parameter.

In those routines that have a fourth argument, its value is the number of bytes in the parameter. To be clear: the value is the number of bytes in the value, not the number of characters. If the fourth parameter is negative, the length of the string is the number of bytes up to the first zero terminator. If a non-negative fourth parameter is provided to sqlite3_bind_text() or sqlite3_bind_text16() then that parameter must be the byte offset where the NUL terminator would occur assuming the string were NUL terminated. If any NUL characters occur at byte offsets less than the value of the fourth parameter then the resulting string value will contain embedded NULs. The result of expressions involving strings with embedded NULs is undefined.

The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and sqlite3_bind_text16() is a destructor used to dispose of the BLOB or string after SQLite has finished with it. The destructor is called to dispose of the BLOB or string even if the call to sqlite3_bind_blob(), sqlite3_bind_text(), or sqlite3_bind_text16() fails. If the fifth argument is the special value SQLITE_STATIC, then SQLite assumes that the information is in static, unmanaged space and does not need to be freed. If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its own private copy of the data immediately, before the sqlite3_bind_*() routine returns.

The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is filled with zeroes. A zeroblob uses a fixed amount of memory (just an integer to hold its size) while it is being processed. Zeroblobs are intended to serve as placeholders for BLOBs whose content is later written using incremental BLOB I/O routines. A negative value for the zeroblob results in a zero-length BLOB.

If any of the sqlite3_bind_*() routines are called with a NULL pointer for the prepared statement or with a prepared statement for which sqlite3_step() has been called more recently than sqlite3_reset(), then the call will return SQLITE_MISUSE. If any sqlite3_bind_() routine is passed a prepared statement that has been finalized, the result is undefined and probably harmful.

Bindings are not cleared by the sqlite3_reset() routine. Unbound parameters are interpreted as NULL.

The sqlite3_bind_* routines return SQLITE_OK on success or an error code if anything goes wrong. SQLITE_RANGE is returned if the parameter index is out of range. SQLITE_NOMEM is returned if malloc() fails.

See also: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name(), and sqlite3_bind_parameter_index().

Compiling An SQL Statement

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open(), sqlite3_open_v2() or sqlite3_open16(). The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() use UTF-16.

If the nByte argument is less than zero, then zSql is read up to the first zero terminator. If nByte is non-negative, then it is the maximum number of bytes read from zSql. When nByte is non-negative, the zSql string ends at either the first '\000' or '\u0000' character or the nByte-th byte, whichever comes first. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to be gained by passing an nByte parameter that is equal to the number of bytes in the input string including the nul-terminator bytes as this saves SQLite from having to make a copy of the input string.

If pzTail is not NULL then *pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compile the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.

*ppStmt is left pointing to a compiled prepared statement that can be executed using sqlite3_step(). If there is an error, *ppStmt is set to NULL. If the input text contains no SQL (if the input is an empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting the compiled SQL statement using sqlite3_finalize() after it has finished with it. ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQLITE_OK; otherwise an error code is returned.

The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are recommended for all new programs. The two older interfaces are retained for backwards compatibility, but their use is discouraged. In the "v2" interfaces, the prepared statement that is returned (the sqlite3_stmt object) contains a copy of the original SQL text. This causes the sqlite3_step() interface to behave differently in three ways:

  1. If the database schema changes, instead of returning SQLITE_SCHEMA as it always used to do, sqlite3_step() will automatically recompile the SQL statement and try to run it again.

  2. When an error occurs, sqlite3_step() will return one of the detailed error codes or extended error codes. The legacy behavior was that sqlite3_step() would only return a generic SQLITE_ERROR result code and the application would have to make a second call to sqlite3_reset() in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

  3. If the specific value bound to host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first sqlite3_step() call following any change to the bindings of that parameter. The specific value of WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT3 compile-time option is enabled. the

Create Or Redefine SQL Functions

int sqlite3_create_function(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function16(
  sqlite3 *db,
  const void *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function_v2(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*),
  void(*xDestroy)(void*)
);

These functions (collectively known as "function creation routines") are used to add SQL functions or aggregates or to redefine the behavior of existing SQL functions or aggregates. The only differences between these routines are the text encoding expected for the second parameter (the name of the function being created) and the presence or absence of a destructor callback for the application data pointer.

The first parameter is the database connection to which the SQL function is to be added. If an application uses more than one database connection then application-defined SQL functions must be added to each database connection separately.

The second parameter is the name of the SQL function to be created or redefined. The length of the name is limited to 255 bytes in a UTF-8 representation, exclusive of the zero-terminator. Note that the name length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. Any attempt to create a function with a longer name will result in SQLITE_MISUSE being returned.

The third parameter (nArg) is the number of arguments that the SQL function or aggregate takes. If this parameter is -1, then the SQL function or aggregate may take any number of arguments between 0 and the limit set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG). If the third parameter is less than -1 or greater than 127 then the behavior is undefined.

The fourth parameter, eTextRep, specifies what text encoding this SQL function prefers for its parameters. Every SQL function implementation must be able to work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be more efficient with one encoding than another. An application may invoke sqlite3_create_function() or sqlite3_create_function16() multiple times with the same function but with different values of eTextRep. When multiple implementations of the same function are available, SQLite will pick the one that involves the least amount of data conversion. If there is only a single implementation which does not care what text encoding is used, then the fourth argument should be SQLITE_ANY.

The fifth parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using sqlite3_user_data().

The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are pointers to C-language functions that implement the SQL function or aggregate. A scalar SQL function requires an implementation of the xFunc callback only; NULL pointers must be passed as the xStep and xFinal parameters. An aggregate SQL function requires an implementation of xStep and xFinal and NULL pointer must be passed for xFunc. To delete an existing SQL function or aggregate, pass NULL pointers for all three function callbacks.

If the ninth parameter to sqlite3_create_function_v2() is not NULL, then it is destructor for the application data pointer. The destructor is invoked when the function is deleted, either by being overloaded or when the database connection closes. The destructor is also invoked if the call to sqlite3_create_function_v2() fails. When the destructor callback of the tenth parameter is invoked, it is passed a single argument which is a copy of the application data pointer which was the fifth parameter to sqlite3_create_function_v2().

It is permitted to register multiple implementations of the same functions with the same name but with either differing numbers of arguments or differing preferred text encodings. SQLite will use the implementation that most closely matches the way in which the SQL function is used. A function implementation with a non-negative nArg parameter is a better match than a function implementation with a negative nArg. A function where the preferred text encoding matches the database encoding is a better match than a function where the encoding is different. A function where the encoding difference is between UTF16le and UTF16be is a closer match than a function where the encoding difference is between UTF8 and UTF16.

Built-in functions may be overloaded by new application-defined functions.

An application-defined function is permitted to call other SQLite interfaces. However, such calls must not close the database connection nor finalize or reset the prepared statement in which the function is running.

Test For Auto-Commit Mode

int sqlite3_get_autocommit(sqlite3*);

The sqlite3_get_autocommit() interface returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively. Autocommit mode is on by default. Autocommit mode is disabled by a BEGIN statement. Autocommit mode is re-enabled by a COMMIT or ROLLBACK.

If certain kinds of errors occur on a statement within a multi-statement transaction (errors including SQLITE_FULL, SQLITE_IOERR, SQLITE_NOMEM, SQLITE_BUSY, and SQLITE_INTERRUPT) then the transaction might be rolled back automatically. The only way to find out whether SQLite automatically rolled back the transaction after an error is to use this function.

If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined.

Result Values From A Query

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

These routines form the "result set" interface.

These routines return information about a single column of the current result row of a query. In every case the first argument is a pointer to the prepared statement that is being evaluated (the sqlite3_stmt* that was returned from sqlite3_prepare_v2() or one of its variants) and the second argument is the index of the column for which information should be returned. The leftmost column of the result set has the index 0. The number of columns in the result can be determined using sqlite3_column_count().

If the SQL statement does not currently point to a valid row, or if the column index is out of range, the result is undefined. These routines may only be called when the most recent call to sqlite3_step() has returned SQLITE_ROW and neither sqlite3_reset() nor sqlite3_finalize() have been called subsequently. If any of these routines are called after sqlite3_reset() or sqlite3_finalize() or after sqlite3_step() has returned something other than SQLITE_ROW, the results are undefined. If sqlite3_step() or sqlite3_reset() or sqlite3_finalize() are called from a different thread while any of these routines are pending, then the results are undefined.

The sqlite3_column_type() routine returns the datatype code for the initial data type of the result column. The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. The value returned by sqlite3_column_type() is only meaningful if no type conversions have occurred as described below. After a type conversion, the value returned by sqlite3_column_type() is undefined. Future versions of SQLite may change the behavior of sqlite3_column_type() following a type conversion.

If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() routine returns the number of bytes in that BLOB or string. If the result is a UTF-16 string, then sqlite3_column_bytes() converts the string to UTF-8 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf() to convert that value to a UTF-8 string and returns the number of bytes in that string. If the result is NULL, then sqlite3_column_bytes() returns zero.

If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() routine returns the number of bytes in that BLOB or string. If the result is a UTF-8 string, then sqlite3_column_bytes16() converts the string to UTF-16 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes16() uses sqlite3_snprintf() to convert that value to a UTF-16 string and returns the number of bytes in that string. If the result is NULL, then sqlite3_column_bytes16() returns zero.

The values returned by sqlite3_column_bytes() and sqlite3_column_bytes16() do not include the zero terminators at the end of the string. For clarity: the values returned by sqlite3_column_bytes() and sqlite3_column_bytes16() are the number of bytes in the string, not the number of characters.

Strings returned by sqlite3_column_text() and sqlite3_column_text16(), even empty strings, are always zero terminated. The return value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.

The object returned by sqlite3_column_value() is an unprotected sqlite3_value object. An unprotected sqlite3_value object may only be used with sqlite3_bind_value() and sqlite3_result_value(). If the unprotected sqlite3_value object returned by sqlite3_column_value() is used in any other way, including calls to routines like sqlite3_value_int(), sqlite3_value_text(), or sqlite3_value_bytes(), then the behavior is undefined.

These routines attempt to convert the value where appropriate. For example, if the internal representation is FLOAT and a text result is requested, sqlite3_snprintf() is used internally to perform the conversion automatically. The following table details the conversions that are applied:

Internal
Type 		Requested
Type 		Conversion

NULL | INTEGER | Result is 0
NULL | FLOAT | Result is 0.0
NULL | TEXT | Result is NULL pointer
NULL | BLOB | Result is NULL pointer
INTEGER | FLOAT | Convert from integer to float
INTEGER | TEXT | ASCII rendering of the integer
INTEGER | BLOB | Same as INTEGER->TEXT
FLOAT | INTEGER | Convert from float to integer
FLOAT | TEXT | ASCII rendering of the float
FLOAT | BLOB | Same as FLOAT->TEXT
TEXT | INTEGER | Use atoi()
TEXT | FLOAT | Use atof()
TEXT | BLOB | No change
BLOB | INTEGER | Convert to TEXT then use atoi()
BLOB | FLOAT | Convert to TEXT then use atof()
BLOB | TEXT | Add a zero terminator if needed

The table above makes reference to standard C library functions atoi() and atof(). SQLite does not really use these functions. It has its own equivalent internal routines. The atoi() and atof() names are used in the table for brevity and because they are familiar to most C programmers.

Note that when type conversions occur, pointers returned by prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() may be invalidated. Type conversions and pointer invalidations might occur in the following cases:

  • The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string.
  • The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16.
  • The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() is called. The content must be converted to UTF-8.

Conversions between UTF-16be and UTF-16le are always done in place and do not invalidate a prior pointer, though of course the content of the buffer that the prior pointer references will have been modified. Other kinds of conversion are done in place when it is possible, but sometimes they are not possible and in those cases prior pointers are invalidated.

The safest and easiest to remember policy is to invoke these routines in one of the following ways:

  • sqlite3_column_text() followed by sqlite3_column_bytes()
  • sqlite3_column_blob() followed by sqlite3_column_bytes()
  • sqlite3_column_text16() followed by sqlite3_column_bytes16()

In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), or sqlite3_column_text16() first to force the result into the desired format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to find the size of the result. Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().

The pointers returned are valid until a type conversion occurs as described above, or until sqlite3_step() or sqlite3_reset() or sqlite3_finalize() is called. The memory space used to hold strings and BLOBs is freed automatically. Do not pass the pointers returned sqlite3_column_blob(), sqlite3_column_text(), etc. into sqlite3_free().

If a memory allocation error occurs during the evaluation of any of these routines, a default value is returned. The default value is either the integer 0, the floating point number 0.0, or a NULL pointer. Subsequent calls to sqlite3_errcode() will return SQLITE_NOMEM.

Enable Or Disable Shared Pager Cache

int sqlite3_enable_shared_cache(int);

This routine enables or disables the sharing of the database cache and schema data structures between connections to the same database. Sharing is enabled if the argument is true and disabled if the argument is false.

Cache sharing is enabled and disabled for an entire process. This is a change as of SQLite version 3.5.0. In prior versions of SQLite, sharing was enabled or disabled for each thread separately.

The cache sharing mode set by this interface effects all subsequent calls to sqlite3_open(), sqlite3_open_v2(), and sqlite3_open16(). Existing database connections continue use the sharing mode that was in effect at the time they were opened.

This routine returns SQLITE_OK if shared cache was enabled or disabled successfully. An error code is returned otherwise.

Shared cache is disabled by default. But this might change in future releases of SQLite. Applications that care about shared cache setting should set it explicitly.

See Also: SQLite Shared-Cache Mode


Release History Of SQLite

Choose any three.
About Sitemap Documentation Download License News Support

Release History

This page provides a high-level summary of changes to SQLite. For more detail, refer the Fossil checkin logs at http://www.sqlite.org/src/timeline and http://www.sqlite.org/src/timeline?t=release

2011 November 1 (3.7.9)

  • If a search token (on the right-hand side of the MATCH operator) in FTS4 begins with "^" then that token must be the first in its field of the document. ** Potentially Incompatible Change **
  • Added options SQLITE_DBSTATUS_CACHE_HIT and SQLITE_DBSTATUS_CACHE_MISS to the sqlite3_db_status() interface.
  • Removed support for SQLITE_ENABLE_STAT2, replacing it with the much more capable SQLITE_ENABLE_STAT3 option.
  • Enhancements to the sqlite3_analyzer utility program, including the --pageinfo and --stats options and support for multiplexed databases.
  • Enhance the sqlite3_data_count() interface so that it can be used to determine if SQLITE_DONE has been seen on the prepared statement.
  • Added the SQLITE_FCNTL_OVERWRITE file-control by which the SQLite core indicates to the VFS that the current transaction will overwrite the entire database file.
  • Increase the default lookaside memory allocator allocation size from 100 to 128 bytes.
  • Enhanced the query planner so that it can factor terms in and out of OR expressions in the WHERE clause in an effort to find better indices.
  • Added the SQLITE_DIRECT_OVERFLOW_READ compile-time option, causing overflow pages to be read directly from the database file, bypassing the page cache.
  • Remove limits on the magnitude of precision and width value in the format specifiers of the sqlite3_mprintf() family of string rendering routines.
  • Fix a bug that prevent ALTER TABLE ... RENAME from working on some virtual tables in a database with a UTF16 encoding.
  • Fix a bug in ASCII-to-float conversion that causes slow performance and incorrect results when converting numbers with ridiculously large exponents.
  • Fix a bug that causes incorrect results in aggregate queries that use multiple aggregate functions whose arguments contain complicated expressions that differ only in the case of string literals contained within those expressions.
  • Fix a bug that prevented the page_count and quick_check pragmas from working correctly if their names were capitalized.
  • Fix a bug that caused VACUUM to fail if the count_changes pragma was engaged.
  • Fix a bug in virtual table implementation that causes a crash if an FTS4 table is dropped inside a transaction and a SAVEPOINT occurs afterwards.
  • SQLITE_SOURCE_ID: "2011-11-01 00:52:41 c7c6050ef060877ebe77b41d959e9df13f8c9b5e"
  • SHA1 for sqlite3.c: becd16877f4f9b281b91c97e106089497d71bb47

2011 September 19 (3.7.8)

  • Orders of magnitude performance improvement for CREATE INDEX on very large tables.
  • Improved the windows VFS to better defend against interference from anti-virus software.
  • Improved query plan optimization when the DISTINCT keyword is present.
  • Allow more system calls to be overridden in the unix VFS - to provide better support for chromium sandboxes.
  • Increase the default size of a lookahead cache line from 100 to 128 bytes.
  • Enhancements to the test_quota.c module so that it can track preexisting files.
  • Bug fix: Virtual tables now handle IS NOT NULL constraints correctly.
  • Bug fixes: Correctly handle nested correlated subqueries used with indices in a WHERE clause.
  • SQLITE_SOURCE_ID: "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177"
  • SHA1 for sqlite3.c: bfcd74a655636b592c5dba6d0d5729c0f8e3b4de

2011 June 28 (3.7.7.1)

  • Fix a bug causing PRAGMA case_sensitive_like statements compiled using sqlite3_prepare() to fail with an SQLITE_SCHEMA error.
  • SQLITE_SOURCE_ID: "2011-06-28 17:39:05 af0d91adf497f5f36ec3813f04235a6e195a605f"
  • SHA1 for sqlite3.c: d47594b8a02f6cf58e91fb673e96cb1b397aace0

2011 June 24 (3.7.7)

  • Add support for URI filenames
  • Add the sqlite3_vtab_config() interface in support of ON CONFLICT clauses with virtual tables.
  • Add the xSavepoint, xRelease and xRollbackTo methods in virtual tables in support of SAVEPOINT for virtual tables.
  • Update the built-in FTS3/FTS4 and RTREE virtual tables to support ON CONFLICT clauses and REPLACE.
  • Avoid unnecessary reparsing of the database schema.
  • Added support for the FTS4 prefix option and the FTS4 order option.
  • Allow WAL-mode databases to be opened read-only as long as there is an existing read/write connection.
  • Added support for short filenames.
  • SQLITE_SOURCE_ID: "2011-06-23 19:49:22 4374b7e83ea0a3fbc3691f9c0c936272862f32f2"
  • SHA1 for sqlite3.c: 5bbe79e206ae5ffeeca760dbd0d66862228db551

2011 May 19 (3.7.6.3)

  • Fix a problem with WAL mode which could cause transactions to silently rollback if the cache_size is set very small (less than 10) and SQLite comes under memory pressure.

2011 April 17 (3.7.6.2)

  • Fix the function prototype for the open(2) system call to agree with POSIX. Without this fix, pthreads does not work correctly on NetBSD.
  • SQLITE_SOURCE_ID: "2011-04-17 17:25:17 154ddbc17120be2915eb03edc52af1225eb7cb5e"
  • SHA1 for sqlite3.c: 806577fd524dd5f3bfd8d4d27392ed2752bc9701

2011 April 14 (3.7.6.1)

  • Fix a bug in 3.7.6 that only appears if the SQLITE_FCNTL_SIZE_HINT file control is used with a build of SQLite that makes use of the HAVE_POSIX_FALLOCATE compile-time option and which has SQLITE_ENABLE_LOCKING_MODE turned off.
  • SQLITE_SOURCE_ID: "2011-04-13 14:40:25 a35e83eac7b185f4d363d7fa51677f2fdfa27695"
  • SHA1 for sqlite3.c: b81bfa27d3e09caf3251475863b1ce6dd9f6ab66

2011 April 12 (3.7.6)

  • Added the sqlite3_wal_checkpoint_v2() interface and enhanced the wal_checkpoint pragma to support blocking checkpoints.
  • Improvements to the query planner so that it makes better estimates of plan costs and hence does a better job of choosing the right plan, especially when SQLITE_ENABLE_STAT2 is used.
  • Fix a bug which prevented deferred foreign key constraints from being enforced when sqlite3_finalize() was not called by one statement with a failed foreign key constraint prior to another statement with foreign key constraints running.
  • Integer arithmetic operations that would have resulted in overflow are now performed using floating-point instead.
  • Increased the version number on the VFS object to 3 and added new methods xSetSysCall, xGetSysCall, and xNextSysCall used for doing full-coverage testing.
  • Increase the maximum value of SQLITE_MAX_ATTACHED from 30 to 62 (though the default value remains at 10).
  • Enhancements to FTS4:
    1. Added the fts4aux table
    2. Added support for compressed FTS4 content
  • Enhance the ANALYZE command to support the name of an index as its argument, in order to analyze just that one index.
  • Added the "unix-excl" built-in VFS on unix and unix-like platforms.
  • SQLITE_SOURCE_ID: "2011-04-12 01:58:40 f9d43fa363d54beab6f45db005abac0a7c0c47a7"
  • SHA1 for sqlite3.c: f38df08547efae0ff4343da607b723f588bbd66b

2011 February 01 (3.7.5)

  • Added the sqlite3_vsnprintf() interface.
  • Added the SQLITE_DBSTATUS_LOOKASIDE_HIT, SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE, and SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL options for the sqlite3_db_status() interface.
  • Added the SQLITE_OMIT_AUTORESET compile-time option.
  • Added the SQLITE_DEFAULT_FOREIGN_KEYS compile-time option.
  • Updates to sqlite3_stmt_readonly() so that its result is well-defined for all prepared statements and so that it works with VACUUM.
  • Added the "-heap" option to the command-line shell
  • Fix a bug involving frequent changes in and out of WAL mode and VACUUM that could (in theory) cause database corruption.
  • Enhance the sqlite3_trace() mechanism so that nested SQL statements such as might be generated by virtual tables are shown but are shown in comments and without parameter expansion. This greatly improves tracing output when using the FTS3/4 and/or RTREE virtual tables.
  • Change the xFileControl() methods on all built-in VFSes to return SQLITE_NOTFOUND instead of SQLITE_ERROR for an unrecognized operation code.
  • The SQLite core invokes the SQLITE_FCNTL_SYNC_OMITTED file control to the VFS in place of a call to xSync if the database has PRAGMA synchronous set to OFF.

2010 December 08 (3.7.4)

  • Added the sqlite3_blob_reopen() interface to allow an existing sqlite3_blob object to be rebound to a new row.
  • Use the new sqlite3_blob_reopen() interface to improve the performance of FTS.
  • VFSes that do not support shared memory are allowed to access WAL databases if PRAGMA locking_mode is set to EXCLUSIVE.
  • Enhancements to EXPLAIN QUERY PLAN.
  • Added the sqlite3_stmt_readonly() interface.
  • Added PRAGMA checkpoint_fullfsync.
  • Added the SQLITE_FCNTL_FILE_POINTER option to sqlite3_file_control().
  • Added support for FTS4 and enhancements to the FTS matchinfo() function.
  • Added the test_superlock.c module which provides example code for obtaining an exclusive lock to a rollback or WAL database.
  • Added the test_multiplex.c module which provides an example VFS that provides multiplexing (sharding) of a DB, splitting it over multiple files of fixed size.
  • A very obscure bug associated with the or optimization was fixed.

2010 October 08 (3.7.3)

  • Added the sqlite3_create_function_v2() interface that includes a destructor callback.
  • Added support for custom r-tree queries using application-supplied callback routines to define the boundary of the query region.
  • The default page cache strives more diligently to avoid using memory beyond what is allocated to it by SQLITE_CONFIG_PAGECACHE. Or if using page cache is allocating from the heap, it strives to avoid going over the sqlite3_soft_heap_limit64(), even if SQLITE_ENABLE_MEMORY_MANAGEMENT is not set.
  • Added the sqlite3_soft_heap_limit64() interface as a replacement for sqlite3_soft_heap_limit().
  • The ANALYZE command now gathers statistics on tables even if they have no indices.
  • Tweaks to the query planner to help it do a better job of finding the most efficient query plan for each query.
  • Enhanced the internal text-to-numeric conversion routines so that they work with UTF8 or UTF16, thereby avoiding some UTF16-to-UTF8 text conversions.
  • Fix a problem that was causing excess memory usage with large WAL transactions in win32 systems.
  • The interface between the VDBE and B-Tree layer is enhanced such that the VDBE provides hints to the B-Tree layer letting the B-Tree layer know when it is safe to use hashing instead of B-Trees for transient tables.
  • Miscellaneous documentation enhancements.

2010 August 24 (3.7.2)

  • Fix an old and very obscure bug that can lead to corruption of the database free-page list when incremental_vacuum is used.

2010 August 23 (3.7.1)

  • Added new commands SQLITE_DBSTATUS_SCHEMA_USED and SQLITE_DBSTATUS_STMT_USED to the sqlite3_db_status() interface, in order to report out the amount of memory used to hold the schema and prepared statements of a connection.
  • Increase the maximum size of a database pages from 32KiB to 64KiB.
  • Use the LIKE optimization even if the right-hand side string contains no wildcards.
  • Added the SQLITE_FCNTL_CHUNK_SIZE verb to the sqlite3_file_control() interface for both unix and windows, to cause database files to grow in large chunks in order to reduce disk fragmentation.
  • Fixed a bug in the query planner that caused performance regressions relative to 3.6.23.1 on some complex joins.
  • Fixed a typo in the OS/2 backend.
  • Refactored the pager module.
  • The SQLITE_MAX_PAGE_SIZE compile-time option is now silently ignored. The maximum page size is hard-coded at 65536 bytes.

2010 August 04 (3.7.0.1)

  • Fix a potential database corruption bug that can occur if version 3.7.0 and version 3.6.23.1 alternately write to the same database file. Ticket [51ae9cad317a1]
  • Fix a performance regression related to the query planner enhancements of version 3.7.0.

2010 July 22 (3.7.0)

  • Added support for write-ahead logging.
  • Query planner enhancement - automatic transient indices are created when doing so reduces the estimated query time.
  • Query planner enhancement - the ORDER BY becomes a no-op if the query also contains a GROUP BY clause that forces the correct output order.
  • Add the SQLITE_DBSTATUS_CACHE_USED verb for sqlite3_db_status().
  • The logical database size is now stored in the database header so that bytes can be appended to the end of the database file without corrupting it and so that SQLite will work correctly on systems that lack support for ftruncate().

2010 March 30 (3.6.23.1)

  • Fix a bug in the offsets() function of FTS3
  • Fix a missing "sync" that when omitted could lead to database corruption if a power failure or OS crash occurred just as a ROLLBACK operation was finishing.

2010 March 09 (3.6.23)

  • Added the secure_delete pragma.
  • Added the sqlite3_compileoption_used() and
    sqlite3_compileoption_get() interfaces as well as the
    compile_options pragma and the sqlite_compileoption_used() and
    sqlite_compileoption_get() SQL functions.
  • Added the sqlite3_log() interface together with the SQLITE_CONFIG_LOG verb to sqlite3_config(). The ".log" command is added to the Command Line Interface.
  • Improvements to FTS3.
  • Improvements and bug-fixes in support for SQLITE_OMIT_FLOATING_POINT.
  • The integrity_check pragma is enhanced to detect out-of-order rowids.
  • The ".genfkey" operator has been removed from the Command Line Interface.
  • Updates to the co-hosted Lemon LALR(1) parser generator. (These updates did not affect SQLite.)
  • Various minor bug fixes and performance enhancements.

2010 Jan 06 (3.6.22)

  • Fix bugs that can (rarely) lead to incorrect query results when the CAST or OR operators are used in the WHERE clause of a query.
  • Continuing enhancements and improvements to FTS3.
  • Other miscellaneous bug fixes.

2009 Dec 07 (3.6.21)

  • The SQL output resulting from sqlite3_trace() is now modified to include the values of bound parameters.
  • Performance optimizations targeting a specific use case from a single high-profile user of SQLite. A 12% reduction in the number of CPU operations is achieved (as measured by Valgrind). Actual performance improvements in practice may vary depending on workload. Changes include:
    • The ifnull() and coalesce() SQL functions are now implemented using in-line VDBE code rather than calling external functions, so that unused arguments need never be evaluated.
    • The substr() SQL function does not bother to measure the length its entire input string if it is only computing a prefix
    • Unnecessary OP_IsNull, OP_Affinity, and OP_MustBeInt VDBE opcodes are suppressed
    • Various code refactorizations for performance
  • The FTS3 extension has undergone a major rework and cleanup. New FTS3 documentation is now available.
  • The SQLITE_SECURE_DELETE compile-time option fixed to make sure that content is deleted even when the truncate optimization applies.
  • Improvements to "dot-command" handling in the Command Line Interface.
  • Other minor bug fixes and documentation enhancements.

2009 Nov 4 (3.6.20)

  • Optimizer enhancement: prepared statements are automatically re-compiled when a binding on the RHS of a LIKE operator changes or when any range constraint changes under SQLITE_ENABLE_STAT2.
  • Various minor bug fixes and documentation enhancements.

2009 Oct 30 (3.6.16.1)

  • A small patch to version 3.6.16 to fix the OP_If bug.

2009 Oct 14 (3.6.19)

  • Added support for foreign key constraints. Foreign key constraints are disabled by default. Use the foreign_keys pragma to turn them on.
  • Generalized the IS and IS NOT operators to take arbitrary expressions on their right-hand side.
  • The TCL Interface has been enhanced to use the Non-Recursive Engine (NRE) interface to the TCL interpreter when linked against TCL 8.6 or later.
  • Fix a bug introduced in 3.6.18 that can lead to a segfault when an attempt is made to write on a read-only database.

2009 Sep 11 (3.6.18)

  • Versioning of the SQLite source code has transitioned from CVS to Fossil.
  • Query planner enhancements.
  • The SQLITE_ENABLE_STAT2 compile-time option causes the ANALYZE command to collect a small histogram of each index, to help SQLite better select among competing range query indices.
  • Recursive triggers can be enabled using the PRAGMA recursive_triggers statement.
  • Delete triggers fire when rows are removed due to a REPLACE conflict resolution. This feature is only enabled when recursive triggers are enabled.
  • Added the SQLITE_OPEN_SHAREDCACHE and SQLITE_OPEN_PRIVATECACHE flags for sqlite3_open_v2() used to override the global shared cache mode settings for individual database connections.
  • Added improved version identification features: C-Preprocessor macro SQLITE_SOURCE_ID, C/C++ interface sqlite3_sourceid(), and SQL function sqlite_source_id().
  • Obscure bug fix on triggers ([efc02f9779]).

2009 Aug 10 (3.6.17)

  • Expose the sqlite3_strnicmp() interface for use by extensions and applications.
  • Remove the restriction on virtual tables and shared cache mode. Virtual tables and shared cache can now be used at the same time.
  • Many code simplifications and obscure bug fixes in support of providing 100% branch test coverage.

2009 June 27 (3.6.16)

  • Fix a bug (ticket #3929) that occasionally causes INSERT or UPDATE operations to fail on an indexed table that has a self-modifying trigger.
  • Other minor bug fixes and performance optimizations.

2009 June 15 (3.6.15)

  • Refactor the internal representation of SQL expressions so that they use less memory on embedded platforms.
  • Reduce the amount of stack space used
  • Fix an 64-bit alignment bug on HP/UX and Sparc
  • The sqlite3_create_function() family of interfaces now return SQLITE_MISUSE instead of SQLITE_ERROR when passed invalid parameter combinations.
  • When new tables are created using CREATE TABLE ... AS SELECT ... the datatype of the columns is the simplified SQLite datatype (TEXT, INT, REAL, NUMERIC, or BLOB) instead of a copy of the original datatype from the source table.
  • Resolve race conditions when checking for a hot rollback journal.
  • The sqlite3_shutdown() interface frees all mutexes under windows.
  • Enhanced robustness against corrupt database files
  • Continuing improvements to the test suite and fixes to obscure bugs and inconsistencies that the test suite improvements are uncovering.

2009 May 25 (3.6.14.2)

  • Fix a code generator bug introduced in version 3.6.14. This bug can cause incorrect query results under obscure circumstances. Ticket #3879.

2009 May 19 (3.6.14.1)

  • Fix a bug in group_concat(), ticket #3841
  • Fix a performance bug in the pager cache, ticket #3844
  • Fix a bug in the sqlite3_backup implementation that can lead to a corrupt backup database. Ticket #3858.

2009 May 7 (3.6.14)

  • Added the optional asynchronous VFS module.
  • Enhanced the query optimizer so that virtual tables are able to make use of OR and IN operators in the WHERE clause.
  • Speed improvements in the btree and pager layers.
  • Added the SQLITE_HAVE_ISNAN compile-time option which will cause the isnan() function from the standard math library to be used instead of SQLite's own home-brew NaN checker.
  • Countless minor bug fixes, documentation improvements, new and improved test cases, and code simplifications and cleanups.

2009 April 13 (3.6.13)

  • Fix a bug in version 3.6.12 that causes a segfault when running a count(*) on the sqlite_master table of an empty database. Ticket #3774.
  • Fix a bug in version 3.6.12 that causes a segfault that when inserting into a table using a DEFAULT value where there is a function as part of the DEFAULT value expression. Ticket #3791.
  • Fix data structure alignment issues on Sparc. Ticket #3777.
  • Other minor bug fixes.

2009 March 31 (3.6.12)

  • Fixed a bug that caused database corruption when an incremental_vacuum is rolled back in an in-memory database. Ticket #3761.
  • Added the sqlite3_unlock_notify() interface.
  • Added the reverse_unordered_selects pragma.
  • The default page size on windows is automatically adjusted to match the capabilities of the underlying filesystem.
  • Add the new ".genfkey" command in the CLI for generating triggers to implement foreign key constraints.
  • Performance improvements for "count(*)" queries.
  • Reduce the amount of heap memory used, especially by TRIGGERs.

2009 Feb 18 (3.6.11)

  • Added the hot-backup interface.
  • Added new commands ".backup" and ".restore" to the CLI.
  • Added new methods backup and restore to the TCL interface.
  • Improvements to the syntax bubble diagrams
  • Various minor bug fixes

2009 Jan 15 (3.6.10)

  • Fix a cache coherency problem that could lead to database corruption. Ticket #3584.

2009 Jan 14 (3.6.9)

  • Fix two bugs, which when combined might result in incorrect query results. Both bugs were harmless by themselves; only when they team up do they cause problems. Ticket #3581.

2009 Jan 12 (3.6.8)

  • Added support for nested transactions
  • Enhanced the query optimizer so that it is able to use multiple indices to efficiently process OR-connected constraints in a WHERE clause.
  • Added support for parentheses in FTS3 query patterns using the SQLITE_ENABLE_FTS3_PARENTHESIS compile-time option.

2008 Dec 16 (3.6.7)

  • Reorganize the Unix interface in os_unix.c
  • Added support for "Proxy Locking" on Mac OS X.
  • Changed the prototype of the sqlite3_auto_extension() interface in a way that is backwards compatible but which might cause warnings in new builds of applications that use that interface.
  • Changed the signature of the xDlSym method of the sqlite3_vfs object in a way that is backwards compatible but which might cause compiler warnings.
  • Added superfluous casts and variable initializations in order to suppress nuisance compiler warnings.
  • Fixes for various minor bugs.

2008 Nov 26 (3.6.6.2)

  • Fix a bug in the b-tree delete algorithm that seems like it might be able to cause database corruption. The bug was first introduced in version 3.6.6 by check-in [5899] on 2008-11-13.
  • Fix a memory leak that can occur following a disk I/O error.

2008 Nov 22 (3.6.6.1)

  • Fix a bug in the page cache that can lead database corruption following a rollback. This bug was first introduced in version 3.6.4.
  • Two other very minor bug fixes

2008 Nov 19 (3.6.6)

  • Fix a #define that prevented memsys5 from compiling
  • Fix a problem in the virtual table commit mechanism that was causing a crash in FTS3. Ticket #3497.
  • Add the application-defined page cache
  • Added built-in support for VxWorks

2008 Nov 12 (3.6.5)

  • Add the MEMORY option to the journal_mode pragma.
  • Added the sqlite3_db_mutex() interface.
  • Added the SQLITE_OMIT_TRUNCATE_OPTIMIZATION compile-time option.
  • Fixed the truncate optimization so that sqlite3_changes() and sqlite3_total_changes() interfaces and the count_changes pragma return the correct values.
  • Added the sqlite3_extended_errcode() interface.
  • The COMMIT command now succeeds even if there are pending queries. It returns SQLITE_BUSY if there are pending incremental BLOB I/O requests.
  • The error code is changed to SQLITE_BUSY (instead of SQLITE_ERROR) when an attempt is made to ROLLBACK while one or more queries are still pending.
  • Drop all support for the experimental memory allocators memsys4 and memsys6.
  • Added the SQLITE_ZERO_MALLOC compile-time option.

2008 Oct 15 (3.6.4)

  • Add option support for LIMIT and ORDER BY clauses on DELETE and UPDATE statements. Only works if SQLite is compiled with SQLITE_ENABLE_UPDATE_DELETE_LIMIT.
  • Added the sqlite3_stmt_status() interface for performance monitoring.
  • Add the INDEXED BY clause.
  • The LOCKING_STYLE extension is now enabled by default on Mac OS X
  • Added the TRUNCATE option to PRAGMA journal_mode
  • Performance enhancements to tree balancing logic in the B-Tree layer.
  • Added the source code and documentation for the genfkey program for automatically generating triggers to enforce foreign key constraints.
  • Added the SQLITE_OMIT_TRUNCATE_OPTIMIZATION compile-time option.
  • The SQL language documentation is converted to use syntax diagrams instead of BNF.
  • Other minor bug fixes

2008 Sep 22 (3.6.3)

  • Fix for a bug in the SELECT DISTINCT logic that was introduced by the prior version.
  • Other minor bug fixes

2008 Aug 30 (3.6.2)

  • Split the pager subsystem into separate pager and pcache subsystems.
  • Factor out identifier resolution procedures into separate files.
  • Bug fixes

2008 Aug 6 (3.6.1)

  • Added the lookaside memory allocator for a speed improvement in excess of 15% on some workloads. (Your mileage may vary.)
  • Added the SQLITE_CONFIG_LOOKASIDE verb to sqlite3_config() to control the default lookaside configuration.
  • Added verbs SQLITE_STATUS_PAGECACHE_SIZE and SQLITE_STATUS_SCRATCH_SIZE to the sqlite3_status() interface.
  • Modified SQLITE_CONFIG_PAGECACHE and SQLITE_CONFIG_SCRATCH to remove the "+4" magic number in the buffer size computation.
  • Added the sqlite3_db_config() and sqlite3_db_status() interfaces for controlling and monitoring the lookaside allocator separately on each database connection.
  • Numerous other performance enhancements
  • Miscellaneous minor bug fixes

2008 July 16 (3.6.0 beta)

  • Modifications to the virtual file system interface to support a wider range of embedded systems. See 35to36.html for additional information. *** Potentially incompatible change ***
  • All C-preprocessor macros used to control compile-time options now begin with the prefix "SQLITE_". This may require changes to applications that compile SQLite using their own makefiles and with custom compile-time options, hence we mark this as a *** Potentially incompatible change ***
  • The SQLITE_MUTEX_APPDEF compile-time option is no longer supported. Alternative mutex implementations can now be added at run-time using the sqlite3_config() interface with the SQLITE_CONFIG_MUTEX verb. *** Potentially incompatible change ***
  • The handling of IN and NOT IN operators that contain a NULL on their right-hand side expression is brought into compliance with the SQL standard and with other SQL database engines. This is a bug fix, but as it has the potential to break legacy applications that depend on the older buggy behavior, we mark that as a *** Potentially incompatible change ***
  • The result column names generated for compound subqueries have been simplified to show only the name of the column of the original table and omit the table name. This makes SQLite operate more like other SQL database engines.
  • Added the sqlite3_config() interface for doing run-time configuration of the entire SQLite library.
  • Added the sqlite3_status() interface used for querying run-time status information about the overall SQLite library and its subsystems.
  • Added the sqlite3_initialize() and sqlite3_shutdown() interfaces.
  • The SQLITE_OPEN_NOMUTEX option was added to sqlite3_open_v2().
  • Added the PRAGMA page_count command.
  • Added the sqlite3_next_stmt() interface.
  • Added a new R*Tree virtual table

2008 May 14 (3.5.9)

  • Added experimental support for the journal_mode PRAGMA and persistent journal.
  • Journal mode PERSIST is the default behavior in exclusive locking mode.
  • Fix a performance regression on LEFT JOIN (see ticket #3015) that was mistakenly introduced in version 3.5.8.
  • Performance enhancement: Reengineer the internal routines used to interpret and render variable-length integers.
  • Fix a buffer-overrun problem in sqlite3_mprintf() which occurs when a string without a zero-terminator is passed to "%.*s".
  • Always convert IEEE floating point NaN values into NULL during processing. (Ticket #3060)
  • Make sure that when a connection blocks on a RESERVED lock that it is able to continue after the lock is released. (Ticket #3093)
  • The "configure" scripts should now automatically configure Unix systems for large file support. Improved error messages for when large files are encountered and large file support is disabled.
  • Avoid cache pages leaks following disk-full or I/O errors
  • And, many more minor bug fixes and performance enhancements....

2008 Apr 16 (3.5.8)

  • Expose SQLite's internal pseudo-random number generator (PRNG) via the sqlite3_randomness() interface
  • New interface sqlite3_context_db_handle() that returns the database connection handle that has invoked an application-defined SQL function.
  • New interface sqlite3_limit() allows size and length limits to be set on a per-connection basis and at run-time.
  • Improved crash-robustness: write the database page size into the rollback journal header.
  • Allow the VACUUM command to change the page size of a database file.
  • The xAccess() method of the VFS is allowed to return -1 to signal a memory allocation error.
  • Performance improvement: The OP_IdxDelete opcode uses unpacked records, obviating the need for one OP_MakeRecord opcode call for each index record deleted.
  • Performance improvement: Constant subexpressions are factored out of loops.
  • Performance improvement: Results of OP_Column are reused rather than issuing multiple OP_Column opcodes.
  • Fix a bug in the RTRIM collating sequence.
  • Fix a bug in the SQLITE_SECURE_DELETE option that was causing Firefox crashes. Make arrangements to always test SQLITE_SECURE_DELETE prior to each release.
  • Other miscellaneous performance enhancements.
  • Other miscellaneous minor bug fixes.

2008 Mar 17 (3.5.7)

  • Fix a bug (ticket #2927) in the register allocation for compound selects - introduced by the new VM code in version 3.5.5.
  • ALTER TABLE uses double-quotes instead of single-quotes for quoting filenames.
  • Use the WHERE clause to reduce the size of a materialized VIEW in an UPDATE or DELETE statement. (Optimization)
  • Do not apply the flattening optimization if the outer query is an aggregate and the inner query contains ORDER BY. (Ticket #2943)
  • Additional OS/2 updates
  • Added an experimental power-of-two, first-fit memory allocator.
  • Remove all instances of sprintf() from the code
  • Accept "Z" as the zulu timezone at the end of date strings
  • Fix a bug in the LIKE optimizer that occurs when the last character before the first wildcard is an upper-case "Z"
  • Added the "bitvec" object for keeping track of which pages have been journalled. Improves speed and reduces memory consumption, especially for large database files.
  • Get the SQLITE_ENABLE_LOCKING_STYLE macro working again on Mac OS X.
  • Store the statement journal in the temporary file directory instead of collocated with the database file.
  • Many improvements and cleanups to the configure script

2008 Feb 6 (3.5.6)

  • Fix a bug (ticket #2913) that prevented virtual tables from working in a LEFT JOIN. The problem was introduced into shortly before the 3.5.5 release.
  • Bring the OS/2 porting layer up-to-date.
  • Add the new sqlite3_result_error_code() API and use it in the implementation of ATTACH so that proper error codes are returned when an ATTACH fails.

2008 Jan 31 (3.5.5)

  • Convert the underlying virtual machine to be a register-based machine rather than a stack-based machine. The only user-visible change is in the output of EXPLAIN.
  • Add the build-in RTRIM collating sequence.

2007 Dec 14 (3.5.4)

  • Fix a critical bug in UPDATE or DELETE that occurs when an OR REPLACE clause or a trigger causes rows in the same table to be deleted as side effects. (See ticket #2832.) The most likely result of this bug is a segmentation fault, though database corruption is a possibility.
  • Bring the processing of ORDER BY into compliance with the SQL standard for case where a result alias and a table column name are in conflict. Correct behavior is to prefer the result alias. Older versions of SQLite incorrectly picked the table column. (See ticket #2822.)
  • The VACUUM command preserves the setting of the legacy_file_format pragma. (Ticket #2804.)
  • Productize and officially support the group_concat() SQL function.
  • Better optimization of some IN operator expressions.
  • Add the ability to change the auto_vacuum status of a database by setting the auto_vaccum pragma and VACUUMing the database.
  • Prefix search in FTS3 is much more efficient.
  • Relax the SQL statement length restriction in the CLI so that the ".dump" output of databases with very large BLOBs and strings can be played back to recreate the database.
  • Other small bug fixes and optimizations.

2007 Nov 27 (3.5.3)

  • Move website and documentation files out of the source tree into a separate CM system.
  • Fix a long-standing bug in INSERT INTO ... SELECT ... statements where the SELECT is compound.
  • Fix a long-standing bug in RAISE(IGNORE) as used in BEFORE triggers.
  • Fixed the operator precedence for the ~ operator.
  • On Win32, do not return an error when attempting to delete a file that does not exist.
  • Allow collating sequence names to be quoted.
  • Modify the TCL interface to use sqlite3_prepare_v2().
  • Fix multiple bugs that can occur following a malloc() failure.
  • sqlite3_step() returns SQLITE_MISUSE instead of crashing when called with a NULL parameter.
  • FTS3 now uses the SQLite memory allocator exclusively. The FTS3 amalgamation can now be appended to the SQLite amalgamation to generate a super-amalgamation containing both.
  • The DISTINCT keyword now will sometimes use an INDEX if an appropriate index is available and the optimizer thinks its use might be advantageous.

2007 Nov 05 (3.5.2)

  • Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time option.
  • Always open files using FILE_FLAG_RANDOM_ACCESS under Windows.
  • The 3rd parameter of the built-in SUBSTR() function is now optional.
  • Bug fix: do not invoke the authorizer when reparsing the schema after a schema change.
  • Added the experimental malloc-free memory allocator in mem3.c.
  • Virtual machine stores 64-bit integer and floating point constants in binary instead of text for a performance boost.
  • Fix a race condition in test_async.c.
  • Added the ".timer" command to the CLI

2007 Oct 04 (3.5.1)

  • Nota Bene: We are not using terms "alpha" or "beta" on this release because the code is stable and because if we use those terms, nobody will upgrade. However, we still reserve the right to make incompatible changes to the new VFS interface in future releases.
  • Fix a bug in the handling of SQLITE_FULL errors that could lead to database corruption. Ticket #2686.
  • The test_async.c drive now does full file locking and works correctly when used simultaneously by multiple processes on the same database.
  • The CLI ignores whitespace (including comments) at the end of lines
  • Make sure the query optimizer checks dependencies on all terms of a compound SELECT statement. Ticket #2640.
  • Add demonstration code showing how to build a VFS for a raw mass storage without a filesystem.
  • Added an output buffer size parameter to the xGetTempname() method of the VFS layer.
  • Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset when a new transaction is started.

2007 Sep 04 (3.5.0) alpha

  • Redesign the OS interface layer. See 34to35.html for details. *** Potentially incompatible change ***
  • The sqlite3_release_memory(), sqlite3_soft_heap_limit(), and sqlite3_enable_shared_cache() interfaces now work cross all threads in the process, not just the single thread in which they are invoked. *** Potentially incompatible change ***
  • Added the sqlite3_open_v2() interface.
  • Reimplemented the memory allocation subsystem and made it replaceable at compile-time.
  • Created a new mutex subsystem and made it replicable at compile-time.
  • The same database connection may now be used simultaneously by separate threads.

2007 August 13 (3.4.2)

  • Fix a database corruption bug that might occur if a ROLLBACK command is executed in auto-vacuum mode and a very small sqlite3_soft_heap_limit is set. Ticket #2565.
  • Add the ability to run a full regression test with a small sqlite3_soft_heap_limit.
  • Fix other minor problems with using small soft heap limits.
  • Work-around for GCC bug 32575.
  • Improved error detection of misused aggregate functions.
  • Improvements to the amalgamation generator script so that all symbols are prefixed with either SQLITE_PRIVATE or SQLITE_API.

2007 July 20 (3.4.1)

  • Fix a bug in VACUUM that can lead to database corruption if two processes are connected to the database at the same time and one VACUUMs then the other then modifies the database.
  • The expression "+column" is now considered the same as "column" when computing the collating sequence to use on the expression.
  • In the TCL language interface, "@variable" instead of "$variable" always binds as a blob.
  • Added PRAGMA freelist_count for determining the current size of the freelist.
  • The PRAGMA auto_vacuum=incremental setting is now persistent.
  • Add FD_CLOEXEC to all open files under Unix.
  • Fix a bug in the min()/max() optimization when applied to descending indices.
  • Make sure the TCL language interface works correctly with 64-bit integers on 64-bit machines.
  • Allow the value -9223372036854775808 as an integer literal in SQL statements.
  • Add the capability of "hidden" columns in virtual tables.
  • Use the macro SQLITE_PRIVATE (defaulting to "static") on all internal functions in the amalgamation.
  • Add pluggable tokenizers and ICU tokenization support to FTS2
  • Other minor bug fixes and documentation enhancements

2007 June 18 (3.4.0)

  • Fix a bug that can lead to database corruption if an SQLITE_BUSY error occurs in the middle of an explicit transaction and that transaction is later committed. Ticket #2409. See the CorruptionFollowingBusyError wiki page for details.
  • Fix a bug that can lead to database corruption if autovacuum mode is on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement which itself follows a cache overflow inside a transaction. See ticket #2418.
  • Added explicit upper bounds on the sizes and quantities of things SQLite can process. This change might cause compatibility problems for applications that use SQLite in the extreme, which is why the current release is 3.4.0 instead of 3.3.18.
  • Added support for Incremental BLOB I/O.
  • Added the sqlite3_bind_zeroblob() API and the zeroblob() SQL function.
  • Added support for Incremental Vacuum.
  • Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to support ARM7 processors with goofy endianness.
  • Removed all instances of sprintf() and strcpy() from the core library.
  • Added support for International Components for Unicode (ICU) to the full-text search extensions.

  • In the Windows OS driver, reacquire a SHARED lock if an attempt to acquire an EXCLUSIVE lock fails. Ticket #2354
  • Fix the REPLACE() function so that it returns NULL if the second argument is an empty string. Ticket #2324.
  • Document the hazards of type conversions in sqlite3_column_blob() and related APIs. Fix unnecessary type conversions. Ticket #2321.
  • Internationalization of the TRIM() function. Ticket #2323
  • Use memmove() instead of memcpy() when moving between memory regions that might overlap. Ticket #2334
  • Fix an optimizer bug involving subqueries in a compound SELECT that has both an ORDER BY and a LIMIT clause. Ticket #2339.
  • Make sure the sqlite3_snprintf() interface does not zero-terminate the buffer if the buffer size is less than 1. Ticket #2341
  • Fix the built-in printf logic so that it prints "NaN" not "Inf" for floating-point NaNs. Ticket #2345
  • When converting BLOB to TEXT, use the text encoding of the main database. Ticket #2349
  • Keep the full precision of integers (if possible) when casting to NUMERIC. Ticket #2364
  • Fix a bug in the handling of UTF16 codepoint 0xE000
  • Consider explicit collate clauses when matching WHERE constraints to indices in the query optimizer. Ticket #2391
  • Fix the query optimizer to correctly handle constant expressions in the ON clause of a LEFT JOIN. Ticket #2403
  • Fix the query optimizer to handle rowid comparisons to NULL correctly. Ticket #2404
  • Fix many potential segfaults that could be caused by malicious SQL statements.

2007 April 25 (3.3.17)

  • When the "write_version" value of the database header is larger than what the library understands, make the database read-only instead of unreadable.
  • Other minor bug fixes

2007 April 18 (3.3.16)

  • Fix a bug that caused VACUUM to fail if NULLs appeared in a UNIQUE column.
  • Reinstate performance improvements that were added in Version 3.3.14 but regressed in Version 3.3.15.
  • Fix problems with the handling of ORDER BY expressions on compound SELECT statements in subqueries.
  • Fix a potential segfault when destroying locks on WinCE in a multi-threaded environment.
  • Documentation updates.

2007 April 9 (3.3.15)

  • Fix a bug introduced in 3.3.14 that caused a rollback of CREATE TEMP TABLE to leave the database connection wedged.
  • Fix a bug that caused an extra NULL row to be returned when a descending query was interrupted by a change to the database.
  • The FOR EACH STATEMENT clause on a trigger now causes a syntax error. It used to be silently ignored.
  • Fix an obscure and relatively harmless problem that might have caused a resource leak following an I/O error.
  • Many improvements to the test suite. Test coverage now exceeded 98%

2007 April 2 (3.3.14)

  • Fix a bug (ticket #2273) that could cause a segfault when the IN operator is used one one term of a two-column index and the right-hand side of the IN operator contains a NULL.
  • Added a new OS interface method for determining the sector size of underlying media: sqlite3OsSectorSize().
  • A new algorithm for statements of the form INSERT INTO table1 SELECT * FROM table2 is faster and reduces fragmentation. VACUUM uses statements of this form and thus runs faster and defragments better.
  • Performance enhancements through reductions in disk I/O:
    • Do not read the last page of an overflow chain when deleting the row - just add that page to the freelist.
    • Do not store pages being deleted in the rollback journal.
    • Do not read in the (meaningless) content of pages extracted from the freelist.
    • Do not flush the page cache (and thus avoiding a cache refill) unless another process changes the underlying database file.
    • Truncate rather than delete the rollback journal when committing a transaction in exclusive access mode, or when committing the TEMP database.
  • Added support for exclusive access mode using "PRAGMA locking_mode=EXCLUSIVE"
  • Use heap space instead of stack space for large buffers in the pager - useful on embedded platforms with stack-space limitations.
  • Add a makefile target "sqlite3.c" that builds an amalgamation containing the core SQLite library C code in a single file.
  • Get the library working correctly when compiled with GCC option "-fstrict-aliasing".
  • Removed the vestigal SQLITE_PROTOCOL error.
  • Improvements to test coverage, other minor bugs fixed, memory leaks plugged, code refactored and/or recommended in places for easier reading.

2007 February 13 (3.3.13)

  • Add a "fragmentation" measurement in the output of sqlite3_analyzer.
  • Add the COLLATE operator used to explicitly set the collating sequence used by an expression. This feature is considered experimental pending additional testing.
  • Allow up to 64 tables in a join - the old limit was 32.
  • Added two new experimental functions: randomBlob() and hex(). Their intended use is to facilitate generating UUIDs.
  • Fix a problem where PRAGMA count_changes was causing incorrect results for updates on tables with triggers
  • Fix a bug in the ORDER BY clause optimizer for joins where the left-most table in the join is constrained by a UNIQUE index.
  • Fixed a bug in the "copy" method of the TCL interface.
  • Bug fixes in fts1 and fts2 modules.

2007 January 27 (3.3.12)

  • Fix another bug in the IS NULL optimization that was added in version 3.3.9.
  • Fix an assertion fault that occurred on deeply nested views.
  • Limit the amount of output that PRAGMA integrity_check generates.
  • Minor syntactic changes to support a wider variety of compilers.

2007 January 22 (3.3.11)

  • Fix another bug in the implementation of the new sqlite3_prepare_v2() API. We'll get it right eventually...
  • Fix a bug in the IS NULL optimization that was added in version 3.3.9 - the bug was causing incorrect results on certain LEFT JOINs that included in the WHERE clause an IS NULL constraint for the right table of the LEFT JOIN.
  • Make AreFileApisANSI() a no-op macro in WinCE since WinCE does not support this function.

2007 January 9 (3.3.10)

  • Fix bugs in the implementation of the new sqlite3_prepare_v2() API that can lead to segfaults.
  • Fix 1-second round-off errors in the strftime() function
  • Enhance the Windows OS layer to provide detailed error codes
  • Work around a win2k problem so that SQLite can use single-character database file names
  • The user_version and schema_version pragmas correctly set their column names in the result set
  • Documentation updates

2007 January 4 (3.3.9)

  • Fix bugs in pager.c that could lead to database corruption if two processes both try to recover a hot journal at the same instant
  • Added the sqlite3_prepare_v2() API.
  • Fixed the ".dump" command in the command-line shell to show indices, triggers and views again.
  • Change the table_info pragma so that it returns NULL for the default value if there is no default value
  • Support for non-ASCII characters in win95 filenames
  • Query optimizer enhancements:
    • Optimizer does a better job of using indices to satisfy ORDER BY clauses that sort on the integer primary key
    • Use an index to satisfy an IS NULL operator in the WHERE clause
    • Fix a bug that was causing the optimizer to miss an OR optimization opportunity
    • The optimizer has more freedom to reorder tables in the FROM clause even in there are LEFT joins.
  • Extension loading supported added to WinCE
  • Allow constraint names on the DEFAULT clause in a table definition
  • Added the ".bail" command to the command-line shell
  • Make CSV (comma separate value) output from the command-line shell more closely aligned to accepted practice
  • Experimental FTS2 module added
  • Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies
  • VACUUM uses a temporary file in the official TEMP folder, not in the same directory as the original database
  • The prefix on temporary filenames on Windows is changed from "sqlite" to "etilqs".

2006 October 9 (3.3.8)

  • Support for full text search using the FTS1 module (beta)
  • Added Mac OS X locking patches (beta - disabled by default)
  • Introduce extended error codes and add error codes for various kinds of I/O errors.
  • Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW
  • Fix the regression test suite so that it works with Tcl8.5
  • Enhance sqlite3_set_authorizer() to provide notification of calls to SQL functions.
  • Added experimental API: sqlite3_auto_extension()
  • Various minor bug fixes

2006 August 12 (3.3.7)

  • Added support for virtual tables (beta)
  • Added support for dynamically loaded extensions (beta)
  • The sqlite3_interrupt() routine can be called for a different thread
  • Added the MATCH operator.
  • The default file format is now 1.

2006 June 6 (3.3.6)

  • Plays better with virus scanners on Windows
  • Faster :memory: databases
  • Fix an obscure segfault in UTF-8 to UTF-16 conversions
  • Added driver for OS/2
  • Correct column meta-information returned for aggregate queries
  • Enhanced output from EXPLAIN QUERY PLAN
  • LIMIT 0 now works on subqueries
  • Bug fixes and performance enhancements in the query optimizer
  • Correctly handle NULL filenames in ATTACH and DETACH
  • Improved syntax error messages in the parser
  • Fix type coercion rules for the IN operator

2006 April 5 (3.3.5)

  • CHECK constraints use conflict resolution algorithms correctly.
  • The SUM() function throws an error on integer overflow.
  • Choose the column names in a compound query from the left-most SELECT instead of the right-most.
  • The sqlite3_create_collation() function honors the SQLITE_UTF16_ALIGNED flag.
  • SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite old data with zeros.
  • Detect integer overflow in abs().
  • The random() function provides 64 bits of randomness instead of only 32 bits.
  • Parser detects and reports automaton stack overflow.
  • Change the round() function to return REAL instead of TEXT.
  • Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to contain aggregate subqueries.
  • Skip over leading spaces in text to numeric conversions.
  • Various minor bug and documentation typo fixes and performance enhancements.

2006 February 11 (3.3.4)

  • Fix a blunder in the Unix mutex implementation that can lead to deadlock on multithreaded systems.
  • Fix an alignment problem on 64-bit machines
  • Added the fullfsync pragma.
  • Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs to give incorrect results.
  • The SUM function detects integer overflow and converts to accumulating an approximate result using floating point numbers
  • Host parameter names can begin with '@' for compatibility with SQL Server.
  • Other miscellaneous bug fixes

2006 January 31 (3.3.3)

  • Removed support for an ON CONFLICT clause on CREATE INDEX - it never worked correctly so this should not present any backward compatibility problems.
  • Authorizer callback now notified of ALTER TABLE ADD COLUMN commands
  • After any changes to the TEMP database schema, all prepared statements are invalidated and must be recreated using a new call to sqlite3_prepare()
  • Other minor bug fixes in preparation for the first stable release of version 3.3

2006 January 24 (3.3.2 beta)

  • Bug fixes and speed improvements. Improved test coverage.
  • Changes to the OS-layer interface: mutexes must now be recursive.
  • Discontinue the use of thread-specific data for out-of-memory exception handling

2006 January 16 (3.3.1 alpha)

  • Countless bug fixes
  • Speed improvements
  • Database connections can now be used by multiple threads, not just the thread in which they were created.

2006 January 10 (3.3.0 alpha)

  • CHECK constraints
  • IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.
  • DESC indices
  • More efficient encoding of boolean values resulting in smaller database files
  • More aggressive SQLITE_OMIT_FLOATING_POINT
  • Separate INTEGER and REAL affinity
  • Added a virtual function layer for the OS interface
  • "exists" method added to the TCL interface
  • Improved response to out-of-memory errors
  • Database cache can be optionally shared between connections in the same thread
  • Optional READ UNCOMMITTED isolation (instead of the default isolation level of SERIALIZABLE) and table level locking when database connections share a common cache.

2005 December 19 (3.2.8)

  • Fix an obscure bug that can cause database corruption under the following unusual circumstances: A large INSERT or UPDATE statement which is part of an even larger transaction fails due to a uniqueness constraint but the containing transaction commits.

2005 December 19 (2.8.17)

  • Fix an obscure bug that can cause database corruption under the following unusual circumstances: A large INSERT or UPDATE statement which is part of an even larger transaction fails due to a uniqueness contraint but the containing transaction commits.

2005 September 24 (3.2.7)

  • GROUP BY now considers NULLs to be equal again, as it should
  • Now compiles on Solaris and OpenBSD and other Unix variants that lack the fdatasync() function
  • Now compiles on MSVC++6 again
  • Fix uninitialized variables causing malfunctions for various obscure queries
  • Correctly compute a LEFT OUTER JOINs that is constrained on the left table only

2005 September 17 (3.2.6)

  • Fix a bug that can cause database corruption if a VACUUM (or autovacuum) fails and is rolled back on a database that is larger than 1GiB
  • LIKE optimization now works for columns with COLLATE NOCASE
  • ORDER BY and GROUP BY now use bounded memory
  • Added support for COUNT(DISTINCT expr)
  • Change the way SUM() handles NULL values in order to comply with the SQL standard
  • Use fdatasync() instead of fsync() where possible in order to speed up commits slightly
  • Use of the CROSS keyword in a join turns off the table reordering optimization
  • Added the experimental and undocumented EXPLAIN QUERY PLAN capability
  • Use the unicode API in Windows

2005 August 27 (3.2.5)

  • Fix a bug effecting DELETE and UPDATE statements that changed more than 40960 rows.
  • Change the makefile so that it no longer requires GNUmake extensions
  • Fix the --enable-threadsafe option on the configure script
  • Fix a code generator bug that occurs when the left-hand side of an IN operator is constant and the right-hand side is a SELECT statement
  • The PRAGMA synchronous=off statement now disables syncing of the master journal file in addition to the normal rollback journals

2005 August 24 (3.2.4)

  • Fix a bug introduced in the previous release that can cause a segfault while generating code for complex WHERE clauses.
  • Allow floating point literals to begin or end with a decimal point.

2005 August 21 (3.2.3)

  • Added support for the CAST operator
  • Tcl interface allows BLOB values to be transferred to user-defined functions
  • Added the "transaction" method to the Tcl interface
  • Allow the DEFAULT value of a column to call functions that have constant operands
  • Added the ANALYZE command for gathering statistics on indices and using those statistics when picking an index in the optimizer
  • Remove the limit (formerly 100) on the number of terms in the WHERE clause
  • The right-hand side of the IN operator can now be a list of expressions instead of just a list of constants
  • Rework the optimizer so that it is able to make better use of indices
  • The order of tables in a join is adjusted automatically to make better use of indices
  • The IN operator is now a candidate for optimization even if the left-hand side is not the left-most term of the index. Multiple IN operators can be used with the same index.
  • WHERE clause expressions using BETWEEN and OR are now candidates for optimization
  • Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE compile-time option to set its default value to "on".
  • Use indices to help with GLOB expressions and LIKE expressions too when the case_sensitive_like pragma is enabled
  • Added support for grave-accent quoting for compatibility with MySQL
  • Improved test coverage
  • Dozens of minor bug fixes

2005 June 13 (3.2.2)

  • Added the sqlite3_db_handle() API
  • Added the sqlite3_get_autocommit() API
  • Added a REGEXP operator to the parser. There is no function to back up this operator in the standard build but users can add their own using sqlite3_create_function()
  • Speed improvements and library footprint reductions.
  • Fix byte alignment problems on 64-bit architectures.
  • Many, many minor bug fixes and documentation updates.

2005 March 29 (3.2.1)

  • Fix a memory allocation error in the new ADD COLUMN comment.
  • Documentation updates

2005 March 21 (3.2.0)

  • Added support for ALTER TABLE ADD COLUMN.
  • Added support for the "T" separator in ISO-8601 date/time strings.
  • Improved support for Cygwin.
  • Numerous bug fixes and documentation updates.

2005 March 16 (3.1.6)

  • Fix a bug that could cause database corruption when inserting record into tables with around 125 columns.
  • sqlite3_step() is now much more likely to invoke the busy handler and less likely to return SQLITE_BUSY.
  • Fix memory leaks that used to occur after a malloc() failure.

2005 March 11 (3.1.5)

  • The ioctl on Mac OS X to control syncing to disk is F_FULLFSYNC, not F_FULLSYNC. The previous release had it wrong.

2005 March 10 (3.1.4)

  • Fix a bug in autovacuum that could cause database corruption if a CREATE UNIQUE INDEX fails because of a constraint violation. This problem only occurs if the new autovacuum feature introduced in version 3.1 is turned on.
  • The F_FULLSYNC ioctl (currently only supported on Mac OS X) is disabled if the synchronous pragma is set to something other than "full".
  • Add additional forward compatibility to the future version 3.2 database file format.
  • Fix a bug in WHERE clauses of the form (rowid<'2')
  • New SQLITE_OMIT_... compile-time options added
  • Updates to the man page
  • Remove the use of strcasecmp() from the shell
  • Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init

2005 February 19 (3.1.3)

  • Fix a problem with VACUUM on databases from which tables containing AUTOINCREMENT have been dropped.
  • Add forward compatibility to the future version 3.2 database file format.
  • Documentation updates

2005 February 15 (3.1.2)

  • Fix a bug that can lead to database corruption if there are two open connections to the same database and one connection does a VACUUM and the second makes some change to the database.
  • Allow "?" parameters in the LIMIT clause.
  • Fix VACUUM so that it works with AUTOINCREMENT.
  • Fix a race condition in AUTOVACUUM that can lead to corrupt databases
  • Add a numeric version number to the sqlite3.h include file.
  • Other minor bug fixes and performance enhancements.

2005 February 15 (2.8.16)

  • Fix a bug that can lead to database corruption if there are two open connections to the same database and one connection does a VACUUM and the second makes some change to the database.
  • Correctly handle quoted names in CREATE INDEX statements.
  • Fix a naming conflict between sqlite.h and sqlite3.h.
  • Avoid excess heap usage when copying expressions.
  • Other minor bug fixes.

2005 February 1 (3.1.1 BETA)

  • Automatic caching of prepared statements in the TCL interface
  • ATTACH and DETACH as well as some other operations cause existing prepared statements to expire.
  • Numerous minor bug fixes

2005 January 21 (3.1.0 ALPHA)

  • Autovacuum support added
  • CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added
  • Support for the EXISTS clause added.
  • Support for correlated subqueries added.
  • Added the ESCAPE clause on the LIKE operator.
  • Support for ALTER TABLE ... RENAME TABLE ... added
  • AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY
  • Many SQLITE_OMIT_ macros inserts to omit features at compile-time and reduce the library footprint.
  • The REINDEX command was added.
  • The engine no longer consults the main table if it can get all the information it needs from an index.
  • Many nuisance bugs fixed.

2004 October 11 (3.0.8)

  • Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.
  • Allow new user-defined functions to be created when there are already one or more precompiled SQL statements.
  • Fix portability problems for MinGW/MSYS.
  • Fix a byte alignment problem on 64-bit Sparc machines.
  • Fix the ".import" command of the shell so that it ignores \r characters at the end of lines.
  • The "csv" mode option in the shell puts strings inside double-quotes.
  • Fix typos in documentation.
  • Convert array constants in the code to have type "const".
  • Numerous code optimizations, specially optimizations designed to make the code footprint smaller.

2004 September 18 (3.0.7)

  • The BTree module allocates large buffers using malloc() instead of off of the stack, in order to play better on machines with limited stack space.
  • Fixed naming conflicts so that versions 2.8 and 3.0 can be linked and used together in the same ANSI-C source file.
  • New interface: sqlite3_bind_parameter_index()
  • Add support for wildcard parameters of the form: "?nnn"
  • Fix problems found on 64-bit systems.
  • Removed encode.c file (containing unused routines) from the version 3.0 source tree.
  • The sqlite3_trace() callbacks occur before each statement is executed, not when the statement is compiled.
  • Makefile updates and miscellaneous bug fixes.

2004 September 02 (3.0.6 beta)

  • Better detection and handling of corrupt database files.
  • The sqlite3_step() interface returns SQLITE_BUSY if it is unable to commit a change because of a lock
  • Combine the implementations of LIKE and GLOB into a single pattern-matching subroutine.
  • Miscellaneous code size optimizations and bug fixes

2004 August 29 (3.0.5 beta)

  • Support for ":AAA" style bind parameter names.
  • Added the new sqlite3_bind_parameter_name() interface.
  • Support for TCL variable names embedded in SQL statements in the TCL bindings.
  • The TCL bindings transfer data without necessarily doing a conversion to a string.
  • The database for TEMP tables is not created until it is needed.
  • Add the ability to specify an alternative temporary file directory using the "sqlite_temp_directory" global variable.
  • A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy handler to be called when there is contention for a RESERVED lock.
  • Various bug fixes and optimizations

2004 August 8 (3.0.4 beta)

  • CREATE TABLE and DROP TABLE now work correctly as prepared statements.
  • Fix a bug in VACUUM and UNIQUE indices.
  • Add the ".import" command to the command-line shell.
  • Fix a bug that could cause index corruption when an attempt to delete rows of a table is blocked by a pending query.
  • Library size optimizations.
  • Other minor bug fixes.

2004 July 22 (2.8.15)

  • This is a maintenance release only. Various minor bugs have been fixed and some portability enhancements are added.

2004 July 22 (3.0.3 beta)

  • The second beta release for SQLite 3.0.
  • Add support for "PRAGMA page_size" to adjust the page size of the database.
  • Various bug fixes and documentation updates.

2004 June 30 (3.0.2 beta)

  • The first beta release for SQLite 3.0.

2004 June 22 (3.0.1 alpha)

  • *** Alpha Release - Research And Testing Use Only ***
  • Lots of bug fixes.

2004 June 18 (3.0.0 alpha)

  • *** Alpha Release - Research And Testing Use Only ***
  • Support for internationalization including UTF-8, UTF-16, and user defined collating sequences.
  • New file format that is 25% to 35% smaller for typical use.
  • Improved concurrency.
  • Atomic commits for ATTACHed databases.
  • Remove cruft from the APIs.
  • BLOB support.
  • 64-bit rowids.
  • More information.

2004 June 9 (2.8.14)

  • Fix the min() and max() optimizer so that it works when the FROM clause consists of a subquery.
  • Ignore extra whitespace at the end of of "." commands in the shell.
  • Bundle sqlite_encode_binary() and sqlite_decode_binary() with the library.
  • The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.
  • Code changes to compile cleanly using OpenWatcom.
  • Fix VDBE stack overflow problems with INSTEAD OF triggers and NULLs in IN operators.
  • Add the global variable sqlite_temp_directory which if set defines the directory in which temporary files are stored.
  • sqlite_interrupt() plays well with VACUUM.
  • Other minor bug fixes.

2004 March 8 (2.8.13)

  • Refactor parts of the code in order to make the code footprint smaller. The code is now also a little bit faster.
  • sqlite_exec() is now implemented as a wrapper around sqlite_compile() and sqlite_step().
  • The built-in min() and max() functions now honor the difference between NUMERIC and TEXT datatypes. Formerly, min() and max() always assumed their arguments were of type NUMERIC.
  • New HH:MM:SS modifier to the built-in date/time functions.
  • Experimental sqlite_last_statement_changes() API added. Fixed the last_insert_rowid() function so that it works correctly with triggers.
  • Add functions prototypes for the database encryption API.
  • Fix several nuisance bugs.

2004 February 8 (2.8.12)

  • Fix a bug that will might corrupt the rollback journal if a power failure or external program halt occurs in the middle of a COMMIT. The corrupt journal can lead to database corruption when it is rolled back.
  • Reduce the size and increase the speed of various modules, especially the virtual machine.
  • Allow "<expr> IN <table>" as a shorthand for "<expr> IN (SELECT * FROM <table>".
  • Optimizations to the sqlite_mprintf() routine.
  • Make sure the MIN() and MAX() optimizations work within subqueries.

2004 January 14 (2.8.11)

  • Fix a bug in how the IN operator handles NULLs in subqueries. The bug was introduced by the previous release.

2004 January 13 (2.8.10)

  • Fix a potential database corruption problem on Unix caused by the fact that all POSIX advisory locks are cleared whenever you close() a file. The work around it to embargo all close() calls while locks are outstanding.
  • Performance enhancements on some corner cases of COUNT(*).
  • Make sure the in-memory backend response sanely if malloc() fails.
  • Allow sqlite_exec() to be called from within user-defined SQL functions.
  • Improved accuracy of floating-point conversions using "long double".
  • Bug fixes in the experimental date/time functions.

2004 January 5 (2.8.9)

  • Fix a 32-bit integer overflow problem that could result in corrupt indices in a database if large negative numbers (less than -2147483648) were inserted into an indexed numeric column.
  • Fix a locking problem on multi-threaded Linux implementations.
  • Always use "." instead of "," as the decimal point even if the locale requests ",".
  • Added UTC to localtime conversions to the experimental date/time functions.
  • Bug fixes to date/time functions.

2003 December 17 (2.8.8)

  • Fix a critical bug introduced into 2.8.0 which could cause database corruption.
  • Fix a problem with 3-way joins that do not use indices
  • The VACUUM command now works with the non-callback API
  • Improvements to the "PRAGMA integrity_check" command

2003 December 4 (2.8.7)

  • Added experimental sqlite_bind() and sqlite_reset() APIs.
  • If the name of the database is an empty string, open a new database in a temporary file that is automatically deleted when the database is closed.
  • Performance enhancements in the lemon-generated parser
  • Experimental date/time functions revised.
  • Disallow temporary indices on permanent tables.
  • Documentation updates and typo fixes
  • Added experimental sqlite_progress_handler() callback API
  • Removed support for the Oracle8 outer join syntax.
  • Allow GLOB and LIKE operators to work as functions.
  • Other minor documentation and makefile changes and bug fixes.

2003 August 21 (2.8.6)

  • Moved the CVS repository to www.sqlite.org
  • Update the NULL-handling documentation.
  • Experimental date/time functions added.
  • Bug fix: correctly evaluate a view of a view without segfaulting.
  • Bug fix: prevent database corruption if you dropped a trigger that had the same name as a table.
  • Bug fix: allow a VACUUM (without segfaulting) on an empty database after setting the EMPTY_RESULT_CALLBACKS pragma.
  • Bug fix: if an integer value will not fit in a 32-bit int, store it in a double instead.
  • Bug fix: Make sure the journal file directory entry is committed to disk before writing the database file.

2003 July 22 (2.8.5)

  • Make LIMIT work on a compound SELECT statement.
  • LIMIT 0 now shows no rows. Use LIMIT -1 to see all rows.
  • Correctly handle comparisons between an INTEGER PRIMARY KEY and a floating point number.
  • Fix several important bugs in the new ATTACH and DETACH commands.
  • Updated the NULL-handling document.
  • Allow NULL arguments in sqlite_compile() and sqlite_step().
  • Many minor bug fixes

2003 June 29 (2.8.4)

  • Enhanced the "PRAGMA integrity_check" command to verify indices.
  • Added authorization hooks for the new ATTACH and DETACH commands.
  • Many documentation updates
  • Many minor bug fixes

2003 June 4 (2.8.3)

  • Fix a problem that will corrupt the indices on a table if you do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that contains an INTEGER PRIMARY KEY plus one or more indices.
  • Fix a bug in Windows locking code so that locks work correctly when simultaneously accessed by Win95 and WinNT systems.
  • Add the ability for INSERT and UPDATE statements to refer to the "rowid" (or "_rowid_" or "oid") columns.
  • Other important bug fixes

2003 May 17 (2.8.2)

  • Fix a problem that will corrupt the database file if you drop a table from the main database that has a TEMP index.

2003 May 16 (2.8.1)

  • Reactivated the VACUUM command that reclaims unused disk space in a database file.
  • Added the ATTACH and DETACH commands to allow interacting with multiple database files at the same time.
  • Added support for TEMP triggers and indices.
  • Added support for in-memory databases.
  • Removed the experimental sqlite_open_aux_file(). Its function is subsumed in the new ATTACH command.
  • The precedence order for ON CONFLICT clauses was changed so that ON CONFLICT clauses on BEGIN statements have a higher precedence than ON CONFLICT clauses on constraints.
  • Many, many bug fixes and compatibility enhancements.

2003 Feb 16 (2.8.0)

  • Modified the journal file format to make it more resistant to corruption that can occur after an OS crash or power failure.
  • Added a new C/C++ API that does not use callback for returning data.

2003 Jan 25 (2.7.6)

  • Performance improvements. The library is now much faster.
  • Added the sqlite_set_authorizer() API. Formal documentation has not been written - see the source code comments for instructions on how to use this function.
  • Fix a bug in the GLOB operator that was preventing it from working with upper-case letters.
  • Various minor bug fixes.

2002 Dec 27 (2.7.5)

  • Fix an uninitialized variable in pager.c which could (with a probability of about 1 in 4 billion) result in a corrupted database.

2002 Dec 17 (2.7.4)

  • Database files can now grow to be up to 2^41 bytes. The old limit was 2^31 bytes.
  • The optimizer will now scan tables in the reverse if doing so will satisfy an ORDER BY ... DESC clause.
  • The full pathname of the database file is now remembered even if a relative path is passed into sqlite_open(). This allows the library to continue operating correctly after a chdir().
  • Speed improvements in the VDBE.
  • Lots of little bug fixes.

2002 Oct 30 (2.7.3)

  • Various compiler compatibility fixes.
  • Fix a bug in the "expr IN ()" operator.
  • Accept column names in parentheses.
  • Fix a problem with string memory management in the VDBE
  • Fix a bug in the "table_info" pragma"
  • Export the sqlite_function_type() API function in the Windows DLL
  • Fix locking behavior under Windows
  • Fix a bug in LEFT OUTER JOIN

2002 Sep 25 (2.7.2)

  • Prevent journal file overflows on huge transactions.
  • Fix a memory leak that occurred when sqlite_open() failed.
  • Honor the ORDER BY and LIMIT clause of a SELECT even if the result set is used for an INSERT.
  • Do not put write locks on the file used to hold TEMP tables.
  • Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.
  • Fix a problem that was causing poor performance when many thousands of SQL statements were executed by a single sqlite_exec() call.

2002 Aug 31 (2.7.1)

  • Fix a bug in the ORDER BY logic that was introduced in version 2.7.0
  • C-style comments are now accepted by the tokenizer.
  • INSERT runs a little faster when the source is a SELECT statement.

2002 Aug 25 (2.7.0)

  • Make a distinction between numeric and text values when sorting. Text values sort according to memcmp(). Numeric values sort in numeric order.
  • Allow multiple simultaneous readers under Windows by simulating the reader/writers locks that are missing from Win95/98/ME.
  • An error is now returned when trying to start a transaction if another transaction is already active.

2002 Aug 12 (2.6.3)

  • Add the ability to read both little-endian and big-endian databases. So a database created under SunOS or Mac OS X can be read and written under Linux or Windows and vice versa.
  • Convert to the new website: http://www.sqlite.org/
  • Allow transactions to span Linux Threads
  • Bug fix in the processing of the ORDER BY clause for GROUP BY queries

2002 Jly 30 (2.6.2)

  • Text files read by the COPY command can now have line terminators of LF, CRLF, or CR.
  • SQLITE_BUSY is handled correctly if encountered during database initialization.
  • Fix to UPDATE triggers on TEMP tables.
  • Documentation updates.

2002 Jly 19 (2.6.1)

  • Include a static string in the library that responds to the RCS "ident" command and which contains the library version number.
  • Fix an assertion failure that occurred when deleting all rows of a table with the "count_changes" pragma turned on.
  • Better error reporting when problems occur during the automatic 2.5.6 to 2.6.0 database format upgrade.

2002 Jly 17 (2.6.0)

  • Change the format of indices to correct a design flaw the originated with version 2.1.0. *** This is an incompatible file format change *** When version 2.6.0 or later of the library attempts to open a database file created by version 2.5.6 or earlier, it will automatically and irreversibly convert the file format. Make backup copies of older database files before opening them with version 2.6.0 of the library.

2002 Jly 7 (2.5.6)

  • Fix more problems with rollback. Enhance the test suite to exercise the rollback logic extensively in order to prevent any future problems.

2002 Jly 6 (2.5.5)

  • Fix a bug which could cause database corruption during a rollback. This bugs was introduced in version 2.4.0 by the freelist optimization of checkin [410].
  • Fix a bug in aggregate functions for VIEWs.
  • Other minor changes and enhancements.

2002 Jly 1 (2.5.4)

  • Make the "AS" keyword optional again.
  • The datatype of columns now appear in the 4th argument to the callback.
  • Added the sqlite_open_aux_file() API, though it is still mostly undocumented and untested.
  • Added additional test cases and fixed a few bugs that those test cases found.

2002 Jun 24 (2.5.3)

  • Bug fix: Database corruption can occur due to the optimization that was introduced in version 2.4.0 (check-in [410]). The problem should now be fixed. The use of versions 2.4.0 through 2.5.2 is not recommended.

2002 Jun 24 (2.5.2)

  • Added the new SQLITE_TEMP_MASTER table which records the schema for temporary tables in the same way that SQLITE_MASTER does for persistent tables.
  • Added an optimization to UNION ALL
  • Fixed a bug in the processing of LEFT OUTER JOIN
  • The LIMIT clause now works on subselects
  • ORDER BY works on subselects
  • There is a new TypeOf() function used to determine if an expression is numeric or text.
  • Autoincrement now works for INSERT from a SELECT.

2002 Jun 19 (2.5.1)

  • The query optimizer now attempts to implement the ORDER BY clause using an index. Sorting is still used if not suitable index is available.

2002 Jun 17 (2.5.0)

  • Added support for row triggers.
  • Added SQL-92 compliant handling of NULLs.
  • Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.
  • Double-quoted strings interpreted as column names not text literals.
  • Parse (but do not implement) foreign keys.
  • Performance improvements in the parser, pager, and WHERE clause code generator.
  • Make the LIMIT clause work on subqueries. (ORDER BY still does not work, though.)
  • Added the "%Q" expansion to sqlite_*_printf().
  • Bug fixes too numerous to mention (see the change log).

2002 May 09 (2.4.12)

  • Added logic to detect when the library API routines are called out of sequence.

2002 May 08 (2.4.11)

  • Bug fix: Column names in the result set were not being generated correctly for some (rather complex) VIEWs. This could cause a segfault under certain circumstances.

2002 May 02 (2.4.10)

  • Bug fix: Generate correct column headers when a compound SELECT is used as a subquery.
  • Added the sqlite_encode_binary() and sqlite_decode_binary() functions to the source tree. But they are not yet linked into the library.
  • Documentation updates.
  • Export the sqlite_changes() function from Windows DLLs.
  • Bug fix: Do not attempt the subquery flattening optimization on queries that lack a FROM clause. To do so causes a segfault.

2002 Apr 21 (2.4.9)

  • Fix a bug that was causing the precompiled binary of SQLITE.EXE to report "out of memory" under Windows 98.

2002 Apr 20 (2.4.8)

  • Make sure VIEWs are created after their corresponding TABLEs in the output of the .dump command in the shell.
  • Speed improvements: Do not do synchronous updates on TEMP tables.
  • Many improvements and enhancements to the shell.
  • Make the GLOB and LIKE operators functions that can be overridden by a programmer. This allows, for example, the LIKE operator to be changed to be case sensitive.

2002 Apr 06 (2.4.7)

  • Add the ability to put TABLE.* in the column list of a SELECT statement.
  • Permit SELECT statements without a FROM clause.
  • Added the last_insert_rowid() SQL function.
  • Do not count rows where the IGNORE conflict resolution occurs in the row count.
  • Make sure functions expressions in the VALUES clause of an INSERT are correct.
  • Added the sqlite_changes() API function to return the number of row that changed in the most recent operation.

2002 Apr 02 (2.4.6)

  • Bug fix: Correctly handle terms in the WHERE clause of a join that do not contain a comparison operator.

2002 Apr 01 (2.4.5)

  • Bug fix: Correctly handle functions that appear in the WHERE clause of a join.
  • When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand value when it is a pointer to a structure rather than a pointer to a string.
  • When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert the NULL value into a unique key automatically.

2002 Mar 24 (2.4.4)

  • Allow "VIEW" to be a column name
  • Added support for CASE expressions (patch from Dan Kennedy)
  • Added RPMS to the delivery (patches from Doug Henry)
  • Fix typos in the documentation
  • Cut over configuration management to a new CVS repository with its own CVSTrac bug tracking system.

2002 Mar 22 (2.4.3)

  • Fix a bug in SELECT that occurs when a compound SELECT is used as a subquery in the FROM of a SELECT.
  • The sqlite_get_table() function now returns an error if you give it two or more SELECTs that return different numbers of columns.

2002 Mar 14 (2.4.2)

  • Bug fix: Fix an assertion failure that occurred when ROWID was a column in a SELECT statement on a view.
  • Bug fix: Fix an uninitialized variable in the VDBE that would could an assert failure.
  • Make the os.h header file more robust in detecting when the compile is for Windows and when it is for Unix.

2002 Mar 13 (2.4.1)

  • Using an unnamed subquery in a FROM clause would cause a segfault.
  • The parser now insists on seeing a semicolon or the end of input before executing a statement. This avoids an accidental disaster if the WHERE keyword is misspelled in an UPDATE or DELETE statement.

2002 Mar 10 (2.4.0)

  • Change the name of the sanity_check PRAGMA to integrity_check and make it available in all compiles.
  • SELECT min() or max() of an indexed column with no WHERE or GROUP BY clause is handled as a special case which avoids a complete table scan.
  • Automatically generated ROWIDs are now sequential.
  • Do not allow dot-commands of the command-line shell to occur in the middle of a real SQL command.
  • Modifications to the "lemon" parser generator so that the parser tables are 4 times smaller.
  • Added support for user-defined functions implemented in C.
  • Added support for new functions: coalesce(), lower(), upper(), and random()
  • Added support for VIEWs.
  • Added the subquery flattening optimizer.
  • Modified the B-Tree and Pager modules so that disk pages that do not contain real data (free pages) are not journaled and are not written from memory back to the disk when they change. This does not impact database integrity, since the pages contain no real data, but it does make large INSERT operations about 2.5 times faster and large DELETEs about 5 times faster.
  • Made the CACHE_SIZE pragma persistent
  • Added the SYNCHRONOUS pragma
  • Fixed a bug that was causing updates to fail inside of transactions when the database contained a temporary table.

2002 Feb 18 (2.3.3)

  • Allow identifiers to be quoted in square brackets, for compatibility with MS-Access.
  • Added support for sub-queries in the FROM clause of a SELECT.
  • More efficient implementation of sqliteFileExists() under Windows. (by Joel Luscy)
  • The VALUES clause of an INSERT can now contain expressions, including scalar SELECT clauses.
  • Added support for CREATE TABLE AS SELECT
  • Bug fix: Creating and dropping a table all within a single transaction was not working.

2002 Feb 14 (2.3.2)

  • Bug fix: There was an incorrect assert() in pager.c. The real code was all correct (as far as is known) so everything should work OK if you compile with -DNDEBUG=1. When asserts are not disabled, there could be a fault.

2002 Feb 13 (2.3.1)

  • Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was set and you did a query that used a rowid, like this: "SELECT rowid, * FROM ...".

2002 Jan 30 (2.3.0)

  • Fix a serious bug in the INSERT command which was causing data to go into the wrong columns if the data source was a SELECT and the INSERT clauses specified its columns in some order other than the default.
  • Added the ability to resolve constraint conflicts is ways other than an abort and rollback. See the documentation on the "ON CONFLICT" clause for details.
  • Temporary files are now automatically deleted by the operating system when closed. There are no more dangling temporary files on a program crash. (If the OS crashes, fsck will delete the file after reboot under Unix. I do not know what happens under Windows.)
  • NOT NULL constraints are honored.
  • The COPY command puts NULLs in columns whose data is '\N'.
  • In the COPY command, backslash can now be used to escape a newline.
  • Added the SANITY_CHECK pragma.

2002 Jan 28 (2.2.5)

  • Important bug fix: the IN operator was not working if either the left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.
  • Do not escape the backslash '\' character in the output of the sqlite command-line access program.

2002 Jan 22 (2.2.4)

  • The label to the right of an AS in the column list of a SELECT can now be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or HAVING clauses.
  • Fix a bug in the -separator command-line option to the sqlite command.
  • Fix a problem with the sort order when comparing upper-case strings against characters greater than 'Z' but less than 'a'.
  • Report an error if an ORDER BY or GROUP BY expression is constant.

2002 Jan 16 (2.2.3)

  • Fix warning messages in VC++ 7.0. (Patches from nicolas352001)
  • Make the library thread-safe. (The code is there and appears to work but has not been stressed.)
  • Added the new sqlite_last_insert_rowid() API function.

2002 Jan 13 (2.2.2)

  • Bug fix: An assertion was failing when a temporary table with an index had the same name as a permanent table created by a separate process.
  • Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an index could fail.

2002 Jan 9 (2.2.1)

  • Bug fix: An attempt to delete a single row of a table with a WHERE clause of "ROWID=x" when no such rowid exists was causing an error.
  • Bug fix: Passing in a NULL as the 3rd parameter to sqlite_open() would sometimes cause a coredump.
  • Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all within a single transaction was causing a coredump.
  • Makefile updates from A. Rottmann

2001 Dec 22 (2.2.0)

  • Columns of type INTEGER PRIMARY KEY are actually used as the primary key in underlying B-Tree representation of the table.
  • Several obscure, unrelated bugs were found and fixed while implemented the integer primary key change of the previous bullet.
  • Added the ability to specify "*" as part of a larger column list in the result section of a SELECT statement. For example: "SELECT rowid, * FROM table1;".
  • Updates to comments and documentation.

2001 Dec 14 (2.1.7)

  • Fix a bug in CREATE TEMPORARY TABLE which was causing the table to be initially allocated in the main database file instead of in the separate temporary file. This bug could cause the library to suffer an assertion failure and it could cause "page leaks" in the main database file.
  • Fix a bug in the b-tree subsystem that could sometimes cause the first row of a table to be repeated during a database scan.

2001 Dec 14 (2.1.6)

  • Fix the locking mechanism yet again to prevent sqlite_exec() from returning SQLITE_PROTOCOL unnecessarily. This time the bug was a race condition in the locking code. This change affects both POSIX and Windows users.

2001 Dec 6 (2.1.5)

  • Fix for another problem (unrelated to the one fixed in 2.1.4) that sometimes causes sqlite_exec() to return SQLITE_PROTOCOL unnecessarily. This time the bug was in the POSIX locking code and should not effect Windows users.

2001 Dec 4 (2.1.4)

  • Sometimes sqlite_exec() would return SQLITE_PROTOCOL when it should have returned SQLITE_BUSY.
  • The fix to the previous bug uncovered a deadlock which was also fixed.
  • Add the ability to put a single .command in the second argument of the sqlite shell
  • Updates to the FAQ

2001 Nov 23 (2.1.3)

  • Fix the behavior of comparison operators (ex: "<", "==", etc.) so that they are consistent with the order of entries in an index.
  • Correct handling of integers in SQL expressions that are larger than what can be represented by the machine integer.

2001 Nov 22 (2.1.2)

  • Changes to support 64-bit architectures.
  • Fix a bug in the locking protocol.
  • Fix a bug that could (rarely) cause the database to become unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER table.
  • Change the code so that version 2.1.1 databases that were rendered unreadable by the above bug can be read by this version of the library even though the SQLITE_MASTER table is (slightly) corrupted.

2001 Nov 13 (2.1.1)

  • Bug fix: Sometimes arbitrary strings were passed to the callback function when the actual value of a column was NULL.

2001 Nov 12 (2.1.0)

  • Change the format of data records so that records up to 16MB in size can be stored.
  • Change the format of indices to allow for better query optimization.
  • Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.

2001 Nov 3 (2.0.8)

  • Made selected parameters in API functions const. This should be fully backwards compatible.
  • Documentation updates
  • Simplify the design of the VDBE by restricting the number of sorters and lists to 1. In practice, no more than one sorter and one list was ever used anyhow.

2001 Oct 21 (2.0.7)

  • Any UTF-8 character or ISO8859 character can be used as part of an identifier.
  • Patches from Christian Werner to improve ODBC compatibility and to fix a bug in the round() function.
  • Plug some memory leaks that use to occur if malloc() failed. We have been and continue to be memory leak free as long as malloc() works.
  • Changes to some test scripts so that they work on Windows in addition to Unix.

2001 Oct 19 (2.0.6)

  • Added the EMPTY_RESULT_CALLBACKS pragma
  • Support for UTF-8 and ISO8859 characters in column and table names.
  • Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma is turned on.

2001 Oct 14 (2.0.5)

  • Added the COUNT_CHANGES pragma.
  • Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.
  • Bug fix: "SELECT count(*)" was returning NULL for empty tables. Now it returns 0.

2001 Oct 13 (2.0.4)

  • Bug fix: an obscure and relatively harmless bug was causing one of the tests to fail when gcc optimizations are turned on. This release fixes the problem.

2001 Oct 13 (2.0.3)

  • Bug fix: the sqlite_busy_timeout() function was delaying 1000 times too long before failing.
  • Bug fix: an assertion was failing if the disk holding the database file became full or stopped accepting writes for some other reason. New tests were added to detect similar problems in the future.
  • Added new operators: & (bitwise-and) | (bitwise-or), ~ (ones-complement), << (shift left), >> (shift right).
  • Added new functions: round() and abs().

2001 Oct 9 (2.0.2)

  • Fix two bugs in the locking protocol. (One was masking the other.)
  • Removed some unused "#include " that were causing problems for VC++.
  • Fixed sqlite.h so that it is usable from C++
  • Added the FULL_COLUMN_NAMES pragma. When set to "ON", the names of columns are reported back as TABLE.COLUMN instead of just COLUMN.
  • Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the ODBC interface.
  • Added support for TEMPORARY tables and indices.

2001 Oct 2 (2.0.1)

  • Remove some C++ style comments from btree.c so that it will compile using compilers other than gcc.
  • The ".dump" output from the shell does not work if there are embedded newlines anywhere in the data. This is an old bug that was carried forward from version 1.0. To fix it, the ".dump" output no longer uses the COPY command. It instead generates INSERT statements.
  • Extend the expression syntax to support "expr NOT NULL" (with a space between the "NOT" and the "NULL") in addition to "expr NOTNULL" (with no space).

2001 Sep 28 (2.0.0)

  • Automatically build binaries for Linux and Windows and put them on the website.

2001 Sep 28 (2.0-alpha-4)

  • Incorporate makefile patches form A. Rottmann to use LIBTOOL

2001 Sep 27 (2.0-alpha-3)

  • SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX. Primary keys are required to be unique.
  • File format changed back to what it was for alpha-1
  • Fixes to the rollback and locking behavior

2001 Sep 20 (2.0-alpha-2)

  • Initial release of version 2.0. The idea of renaming the library to "SQLus" was abandoned in favor of keeping the "SQLite" name and bumping the major version number.
  • The pager and btree subsystems added back. They are now the only available backend.
  • The Dbbe abstraction and the GDBM and memory drivers were removed.
  • Copyright on all code was disclaimed. The library is now in the public domain.

2001 Jul 23 (1.0.32)

  • Pager and btree subsystems removed. These will be used in a follow-on SQL server library named "SQLus".
  • Add the ability to use quoted strings as table and column names in expressions.

2001 Apr 14 (1.0.31)

  • Pager subsystem added but not yet used.
  • More robust handling of out-of-memory errors.
  • New tests added to the test suite.

2001 Apr 6 (1.0.30)

  • Remove the sqlite_encoding TCL variable that was introduced in the previous version.
  • Add options -encoding and -tcl-uses-utf to the sqlite TCL command.
  • Add tests to make sure that tclsqlite was compiled using Tcl header files and libraries that match.

2001 Apr 5 (1.0.29)

  • The library now assumes data is stored as UTF-8 if the --enable-utf8 option is given to configure. The default behavior is to assume iso8859-x, as it has always done. This only makes a difference for LIKE and GLOB operators and the LENGTH and SUBSTR functions.
  • If the library is not configured for UTF-8 and the Tcl library is one of the newer ones that uses UTF-8 internally, then a conversion from UTF-8 to iso8859 and back again is done inside the TCL interface.

2001 Apr 4 (1.0.28)

  • Added limited support for transactions. At this point, transactions will do table locking on the GDBM backend. There is no support (yet) for rollback or atomic commit.
  • Added special column names ROWID, OID, and _ROWID_ that refer to the unique random integer key associated with every row of every table.
  • Additional tests added to the regression suite to cover the new ROWID feature and the TCL interface bugs mentioned below.
  • Changes to the "lemon" parser generator to help it work better when compiled using MSVC.
  • Bug fixes in the TCL interface identified by Oleg Oleinick.

2001 Mar 20 (1.0.27)

  • When doing DELETE and UPDATE, the library used to write the record numbers of records to be deleted or updated into a temporary file. This is changed so that the record numbers are held in memory.
  • The DELETE command without a WHILE clause just removes the database files from the disk, rather than going through and deleting record by record.

2001 Mar 20 (1.0.26)

  • A serious bug fixed on Windows. Windows users should upgrade. No impact to Unix.

2001 Mar 15 (1.0.25)

  • Modify the test scripts to identify tests that depend on system load and processor speed and to warn the user that a failure of one of those (rare) tests does not necessarily mean the library is malfunctioning. No changes to code.

2001 Mar 14 (1.0.24)

  • Fix a bug which was causing the UPDATE command to fail on systems where "malloc(0)" returns NULL. The problem does not appear on Windows, Linux, or HPUX but does cause the library to fail on QNX.

2001 Feb 19 (1.0.23)

  • An unrelated (and minor) bug from Mark Muranwski fixed. The algorithm for figuring out where to put temporary files for a "memory:" database was not working quite right.

2001 Feb 19 (1.0.22)

  • The previous fix was not quite right. This one seems to work better.

2001 Feb 19 (1.0.21)

  • The UPDATE statement was not working when the WHERE clause contained some terms that could be satisfied using indices and other terms that could not. Fixed.

2001 Feb 11 (1.0.20)

  • Merge development changes into the main trunk. Future work toward using a BTree file structure will use a separate CVS source tree. This CVS tree will continue to support the GDBM version of SQLite only.

2001 Feb 6 (1.0.19)

  • Fix a strange (but valid) C declaration that was causing problems for QNX. No logical changes.

2001 Jan 4 (1.0.18)

  • Print the offending SQL statement when an error occurs.
  • Do not require commas between constraints in CREATE TABLE statements.
  • Added the "-echo" option to the shell.
  • Changes to comments.

2000 Dec 10 (1.0.17)

  • Rewrote sqlite_complete() to make it faster.
  • Minor tweaks to other code to make it run a little faster.
  • Added new tests for sqlite_complete() and for memory leaks.

2000 Dec 4 (1.0.16)

  • Documentation updates. Mostly fixing of typos and spelling errors.

2000 Oct 23 (1.0.15)

  • Documentation updates
  • Some sanity checking code was removed from the inner loop of vdbe.c to help the library to run a little faster. The code is only removed if you compile with -DNDEBUG.

2000 Oct 19 (1.0.14)

  • Added a "memory:" backend driver that stores its database in an in-memory hash table.

2000 Oct 18 (1.0.13)

  • Break out the GDBM driver into a separate file in anticipation to added new drivers.
  • Allow the name of a database to be prefixed by the driver type. For now, the only driver type is "gdbm:".

2000 Oct 16 (1.0.12)

  • Fixed an off-by-one error that was causing a coredump in the '%q' format directive of the new sqlite_..._printf() routines.
  • Added the sqlite_interrupt() interface.
  • In the shell, sqlite_interrupt() is invoked when the user presses Control-C
  • Fixed some instances where sqlite_exec() was returning the wrong error code.

2000 Oct 11 (1.0.10)

  • Added notes on how to compile for Windows95/98.
  • Removed a few variables that were not being used. Etc.

2000 Oct 8 (1.0.9)

  • Added the sqlite_..._printf() interface routines.
  • Modified the sqlite shell program to use the new interface routines.
  • Modified the sqlite shell program to print the schema for the built-in SQLITE_MASTER table, if explicitly requested.

2000 Sep 30 (1.0.8)

  • Begin writing documentation on the TCL interface.

2000 Sep 29 (Not Released)

  • Added the sqlite_get_table() API
  • Updated the documentation for due to the above change.
  • Modified the sqlite shell to make use of the new sqlite_get_table() API in order to print a list of tables in multiple columns, similar to the way "ls" prints filenames.
  • Modified the sqlite shell to print a semicolon at the end of each CREATE statement in the output of the ".schema" command.

2000 Sep 21 (Not Released)

  • Change the tclsqlite "eval" method to return a list of results if no callback script is specified.
  • Change tclsqlite.c to use the Tcl_Obj interface
  • Add tclsqlite.c to the libsqlite.a library

2000 Sep 13 (Version 1.0.5)

  • Changed the print format for floating point values from "%g" to "%.15g".
  • Changed the comparison function so that numbers in exponential notation (ex: 1.234e+05) sort in numerical order.

2000 Aug 28 (Version 1.0.4)

  • Added functions length() and substr().
  • Fix a bug in the sqlite shell program that was causing a coredump when the output mode was "column" and the first row of data contained a NULL.

2000 Aug 22 (Version 1.0.3)

  • In the sqlite shell, print the "Database opened READ ONLY" message to stderr instead of stdout.
  • In the sqlite shell, now print the version number on initial startup.
  • Add the sqlite_version[] string constant to the library
  • Makefile updates
  • Bug fix: incorrect VDBE code was being generated for the following circumstance: a query on an indexed table containing a WHERE clause with an IN operator that had a subquery on its right-hand side.

2000 Aug 18 (Version 1.0.1)

  • Fix a bug in the configure script.
  • Minor revisions to the website.

2000 Aug 17 (Version 1.0)

  • Change the sqlite program so that it can read databases for which it lacks write permission. (It used to refuse all access if it could not write.)

2000 Aug 9

  • Treat carriage returns as white space.

2000 Aug 8

  • Added pattern matching to the ".table" command in the "sqlite" command shell.

2000 Aug 4

  • Documentation updates
  • Added "busy" and "timeout" methods to the Tcl interface

2000 Aug 3

  • File format version number was being stored in sqlite_master.tcl multiple times. This was harmless, but unnecessary. It is now fixed.

2000 Aug 2

  • The file format for indices was changed slightly in order to work around an inefficiency that can sometimes come up with GDBM when there are large indices having many entries with the same key. ** Incompatible Change **

2000 Aug 1

  • The parser's stack was overflowing on a very long UPDATE statement. This is now fixed.

2000 July 31

  • Finish the VDBE tutorial.
  • Added documentation on compiling to WinNT.
  • Fix a configuration program for WinNT.
  • Fix a configuration problem for HPUX.

2000 July 29

  • Better labels on column names of the result.

2000 July 28

  • Added the sqlite_busy_handler() and sqlite_busy_timeout() interface.

2000 June 23

  • Begin writing the VDBE tutorial.

2000 June 21

  • Clean up comments and variable names. Changes to documentation. No functional changes to the code.

2000 June 19

  • Column names in UPDATE statements were case sensitive. This mistake has now been fixed.

2000 June 16

  • Added the concatenate string operator (||)

2000 June 12

  • Added the fcnt() function to the SQL interpreter. The fcnt() function returns the number of database "Fetch" operations that have occurred. This function is designed for use in test scripts to verify that queries are efficient and appropriately optimized. Fcnt() has no other useful purpose, as far as I know.
  • Added a bunch more tests that take advantage of the new fcnt() function. The new tests did not uncover any new problems.

2000 June 8

  • Added lots of new test cases
  • Fix a few bugs discovered while adding test cases
  • Begin adding lots of new documentation

2000 June 6

  • Added compound select operators: UNION, UNION ALL, INTERSECT, and EXCEPT
  • Added support for using (SELECT ...) within expressions
  • Added support for IN and BETWEEN operators
  • Added support for GROUP BY and HAVING
  • NULL values are now reported to the callback as a NULL pointer rather than an empty string.

2000 June 3

  • Added support for default values on columns of a table.
  • Improved test coverage. Fixed a few obscure bugs found by the improved tests.

2000 June 2

  • All database files to be modified by an UPDATE, INSERT or DELETE are now locked before any changes are made to any files. This makes it safe (I think) to access the same database simultaneously from multiple processes.
  • The code appears stable so we are now calling it "beta".

2000 June 1

  • Better support for file locking so that two or more processes (or threads) can access the same database simultaneously. More work needed in this area, though.

2000 May 31

  • Added support for aggregate functions (Ex: COUNT(*), MIN(...)) to the SELECT statement.
  • Added support for SELECT DISTINCT ...

2000 May 30

  • Added the LIKE operator.
  • Added a GLOB operator: similar to LIKE but it uses Unix shell globbing wildcards instead of the '%' and '_' wildcards of SQL.
  • Added the COPY command patterned after PostgreSQL so that SQLite can now read the output of the pg_dump database dump utility of PostgreSQL.
  • Added a VACUUM command that calls the gdbm_reorganize() function on the underlying database files.
  • And many, many bug fixes...

2000 May 29

  • Initial Public Release of Alpha code


An Introduction To The SQLite C/C++ Interface

This article provides an overview and roadmap to the C/C++ interface to SQLite.

Early versions of SQLite were very easy to learn since they only supported 5 C/C++ interfaces. But as SQLite has grown in capability, new C/C++ interfaces have been added so that now there are over 185 distinct APIs. This can be overwhelming to a new programmer. Fortunately, most of the C/C++ interfaces in SQLite are very specialized and never need to be used. Despite having so many entry points, the core API is still relatively simple and easy to code to. This article aims to provide all of the background information needed to easily understand how SQLite works.

A separate document, The SQLite C/C++ Interface, provides detailed specifications for all of the various C/C++ APIs for SQLite. Once the reader understands the basic principles of operation for SQLite, that document should be used as a reference guide. This article is intended as introduction only and is neither a complete nor authoritative reference for the SQLite API.

1.0 Core Objects And Interfaces

The principal task of an SQL database engine is to evaluate statements of SQL. In order to accomplish this purpose, the developer needs to know about two objects:

  • The database connection object: sqlite3
  • The prepared statement object: sqlite3_stmt

Strictly speaking, the prepared statement object is not required since the convenience wrapper interfaces, sqlite3_exec or sqlite3_get_table, can be used and these convenience wrappers encapsulate and hide the prepared statement object. Nevertheless, an understanding of prepared statements is needed to make full use of SQLite.

The database connection and prepared statement objects are controlled by a small set of C/C++ interface routine listed below.

  • sqlite3_open()
  • sqlite3_prepare()
  • sqlite3_step()
  • sqlite3_column()
  • sqlite3_finalize()
  • sqlite3_close()

The six C/C++ interface routines and two objects listed above form the core functionality of SQLite. The developer who understands them will have a good foundation for using SQLite.

Note that the list of routines is conceptual rather than actual. Many of these routines come in multiple versions. For example, the list above shows a single routine named sqlite3_open() when in fact there are three separate routines that accomplish the same thing in slightly different ways: sqlite3_open(), sqlite3_open16() and sqlite3_open_v2(). The list mentions sqlite3_column() when in fact no such routine exists. The "sqlite3_column()" shown in the list is place holders for an entire family of routines to be used for extracting column data in various datatypes.

Here is a summary of what the core interfaces do:

sqlite3_open() | This routine opens a connection to an SQLite database file and returns a database connection object. This is often the first SQLite API call that an application makes and is a prerequisite for most other SQLite APIs. Many SQLite interfaces require a pointer to the database connection object as their first parameter and can be thought of as methods on the database connection object. This routine is the constructor for the database connection object.
sqlite3_prepare() This routine converts SQL text into a prepared statement object and returns a pointer to that object. This interface requires a database connection pointer created by a prior call to sqlite3_open() and a text string containing the SQL statement to be prepared. This API does not actually evaluate the SQL statement. It merely prepares the SQL statement for evaluation.

Note that the use of sqlite3_prepare() is not recommended for new applications. The alternative routine sqlite3_prepare_v2() should be used instead.
sqlite3_step() | This routine is used to evaluate a prepared statement that has been previously created by the sqlite3_prepare() interface. The statement is evaluated up to the point where the first row of results are available. To advance to the second row of results, invoke sqlite3_step() again. Continue invoking sqlite3_step() until the statement is complete. Statements that do not return results (ex: INSERT, UPDATE, or DELETE statements) run to completion on a single call to sqlite3_step().
sqlite3_column() This routine returns a single column from the current row of a result set for a prepared statement that is being evaluated by sqlite3_step(). Each time sqlite3_step() stops with a new result set row, this routine can be called multiple times to find the values of all columns in that row. As noted above, there really is no such thing as a "sqlite3_column()" function in the SQLite API. Instead, what we here call "sqlite3_column()" is really a place-holder for an entire family of functions that return a value from the result set in various data types. There are also routines in this family that return the size of the result (if it is a string or BLOB) and the number of columns in the result set.

  • sqlite3_column_blob()
  • sqlite3_column_bytes()
  • sqlite3_column_bytes16()
  • sqlite3_column_count()
  • sqlite3_column_double()
  • sqlite3_column_int()
  • sqlite3_column_int64()
  • sqlite3_column_text()
  • sqlite3_column_text16()
  • sqlite3_column_type()
  • sqlite3_column_value()

sqlite3_finalize() | This routine destroys a prepared statement created by a prior call to sqlite3_prepare(). Every prepared statement must be destroyed using a call to this routine in order to avoid memory leaks.
sqlite3_close() | This routine closes a database connection previously opened by a call to sqlite3_open(). All prepared statements associated with the connection should be finalized prior to closing the connection.

1.1 Typical Usage Of Core Routines And Objects

An application that wants to use SQLite will typically use sqlite3_open() to create a single database connection during initialization. Note that sqlite3_open() can be used to either open existing database files or to create and open new database files. While many applications use only a single database connection, there is no reason why an application cannot call sqlite3_open() multiple times in order to open multiple database connections - either to the same database or to different databases. Sometimes a multi-threaded application will create separate database connections for each threads. Note too that is not necessary to open separate database connections in order to access two or more databases. A single database connection can be made to access two or more databases at one time using the ATTACH SQL command.

Many applications destroy their database connections using calls to sqlite3_close() at shutdown. Or, for example, an application might open database connections in response to a File->Open menu action and then destroy the corresponding database connection in response to the File->Close menu.

To run an SQL statement, the application follows these steps:

  1. Create a prepared statement using sqlite3_prepare().
  2. Evaluate the prepared statement by calling sqlite3_step() one or more times.
  3. For queries, extract results by calling sqlite3_column() in between two calls to sqlite3_step().
  4. Destroy the prepared statement using sqlite3_finalize().

The foregoing is all one really needs to know in order to use SQLite effectively. All the rest is just ornamentation and detail.

2.0 Convenience Wrappers Around Core Routines

The sqlite3_exec() interface is a convenience wrapper that carries out all four of the above steps with a single function call. A callback function passed into sqlite3_exec() is used to process each row of the result set. The sqlite3_get_table() is another convenience wrapper that does all four of the above steps. The sqlite3_get_table() interface differs from sqlite3_exec() in that it stores the results of queries in heap memory rather than invoking a callback.

It is important to realize that neither sqlite3_exec() nor sqlite3_get_table() do anything that cannot be accomplished using the core routines. In fact, these wrappers are implemented purely in terms of the core routines.

3.0 Binding Parameters and Reusing Prepared Statements

In prior discussion, it was assumed that each SQL statement is prepared once, evaluated, then destroyed. However, the SQLite allows the same prepared statement to be evaluated multiple times. This is accomplished using the following routines:

  • sqlite3_reset()
  • sqlite3_bind()

After a prepared statement has been evaluated by one or more calls to sqlite3_step(), it can be reset in order to be evaluated again by a call to sqlite3_reset(). Using sqlite3_reset() on an existing prepared statement rather than creating a new prepared statement avoids unnecessary calls to sqlite3_prepare(). In many SQL statements, the time needed to run sqlite3_prepare() equals or exceeds the time needed by sqlite3_step(). So avoiding calls to sqlite3_prepare() can result in a significant performance improvement.

Usually, though, it is not useful to evaluate exactly the same SQL statement more than once. More often, one wants to evaluate similar statements. For example, you might want to evaluate an INSERT statement multiple times though with different values to insert. To accommodate this kind of flexibility, SQLite allows SQL statements to contain parameters which are "bound" to values prior to being evaluated. These values can later be changed and the same prepared statement can be evaluated a second time using the new values.

In SQLite, wherever it is valid to include a string literal, one can use a parameter in one of the following forms:

  • ?
  • ?NNN
  • :AAA
  • $AAA
  • @AAA

In the examples above, NNN is an integer value and AAA is an identifier. A parameter initially has a value of NULL. Prior to calling sqlite3_step() for the first time or immediately after sqlite3_reset(), the application can invoke one of the sqlite3_bind() interfaces to attach values to the parameters. Each call to sqlite3_bind() overrides prior bindings on the same parameter.

An application is allowed to prepare multiple SQL statements in advance and evaluate them as needed. There is no arbitrary limit to the number of outstanding prepared statements.

4.0 Extending SQLite

SQLite includes interfaces that can be used to extend its functionality. Such routines include:

  • sqlite3_create_collation()
  • sqlite3_create_function()
  • sqlite3_create_module()

The sqlite3_create_collation() interface is used to create new collating sequences for sorting text. The sqlite3_create_module() interface is used to register new virtual table implementations.

The sqlite3_create_function() interface creates new SQL functions - either scalar or aggregate. The new function implementation typically makes use of the following additional interfaces:

  • sqlite3_aggregate_context()
  • sqlite3_result()
  • sqlite3_user_data()
  • sqlite3_value()

All of the built-in SQL functions of SQLite are created using exactly these same interfaces. Refer to the SQLite source code, and in particular the date.c and func.c source files for examples.

5.0 Other Interfaces

This article only mentions the foundational SQLite interfaces. The SQLite library includes many other APIs implementing useful features that are not described here. A complete list of functions that form the SQLite application programming interface is found at the C/C++ Interface Specification. Refer to that document for complete and authoritative information about all SQLite interfaces.


Compilation Options For SQLite

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

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 Options To Set Default Parameter Values

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=<pages>

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 command. The default value is 2000.

SQLITE_DEFAULT_FILE_FORMAT=<1 or 4>

The default schema-level file format used by SQLite when creating new database files is set by this macro. The file 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.

SQLite (as of version 3.6.0) can read and write any file 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 file format is set to 1 for maximum compatibility.

The file format 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_JOURNAL_SIZE_LIMIT=<bytes>

This option sets the size limit on rollback journal files in persistent journal mode. When this compile-time option is omitted there is no upper bound on the size of the rollback journal file. 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 1024. The compile-time default may be overridden at runtime by the PRAGMA page_size command.

SQLITE_DEFAULT_TEMP_CACHE_SIZE=<pages>

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 TEMP TABLE are stored. The default value is 500.

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_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 5 which is more than adequate for most applications. But in some obscure cases, it is useful to raise this parameter to 100 or more to prevent spurious SQLITE_SCHEMA errors when running sqlite3_step().

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

  • SQLITE_MAX_ATTACHED
  • SQLITE_MAX_COLUMN
  • SQLITE_MAX_COMPOUND_SELECT
  • SQLITE_MAX_EXPR_DEPTH
  • SQLITE_MAX_FUNCTION_ARG
  • SQLITE_MAX_LENGTH
  • SQLITE_MAX_LIKE_PATTERN_LENGTH
  • SQLITE_MAX_PAGE_COUNT
  • SQLITE_MAX_SQL_LENGTH
  • SQLITE_MAX_VARIABLE_NUMBER

1.3 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. Without this option (the default behavior) SQLite uses its own internal implementation of isnan(). SQLite uses its own internal isnan() implementation by default because of past problems with system isnan() functions.

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 for this since additional I/O must occur. On the other hand, secure_delete can prevent sensitive information from lingering in unused parts of the database file after it has allegedly 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 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:

  • SQLITE_CONFIG_SINGLETHREAD
  • SQLITE_CONFIG_MULTITHREAD
  • SQLITE_CONFIG_SERIALIZED

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_STORE | Meaning
0 | Always use temporary files
1 | Use files by default but allow the PRAGMA temp_store command to override
2 | Use memory by default but allow the PRAGMA temp_store command to override
3 | Always use memory

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

SQLITE_USE_URI

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

1.4 Options To Enable Features Normally Turned Off

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_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:

  • sqlite3_column_database_name()
  • sqlite3_column_database_name16()
  • sqlite3_column_table_name()
  • sqlite3_column_table_name16()
  • sqlite3_column_origin_name()
  • sqlite3_column_origin_name16()
  • sqlite3_table_column_metadata()

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_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_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_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:

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

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

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

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

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

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_RTREE

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

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

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.

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

1.6 Options To Omit Features

The following options can 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 or from the collection of pre-packaged C files provided for non-Unix like platforms on the website. Any SQLITE_OMIT_* options which can be used directly with the amalgamation are listed below, however, the warnings in the following paragraph should be noted.

Important Note: The SQLITE_OMIT_* options do not work with the amalgamation or with pre-packaged C code files. SQLITE_OMIT_* compile-time options only work correctly 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.

All of the SQLITE_OMIT_* options are unsupported.

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

The SQLITE_OMIT_* compile-time options are usually untested and are almost certainly untested in combination. Any or all of these options may be removed from the code in future releases and without warning. For any particular release, some of these options may cause compile-time or run-time failures, particularly when used in combination with other options.

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.

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.

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_MERGE_SORT

Beginning with SQLite version 3.7.8, large sort operations such as used by CREATE INDEX commands are implemented using an external merge sort rather than insertions into a B-Tree. This results in better cache locality and an order-of-magnitude speed improvement for sorts that are larger than the filesystem cache. On the other hand, the merge sort logic uses some code space and is slightly (1%) slower for CREATE INDEX on small tables. The external merge sort can be disabled using this compile-time 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.

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 options 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.7 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 turns on some other debugging features.

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.


Constraint Conflict Resolution in SQLite

In most SQL databases, if you have a UNIQUE constraint on a table and you try to do an UPDATE or INSERT that violates the constraint, the database will abort the operation in progress, back out any prior changes associated with the same UPDATE or INSERT statement, and return an error. This is the default behavior of SQLite, though SQLite also allows one to define alternative ways for dealing with constraint violations. This article describes those alternatives and how to use them.

Conflict Resolution Algorithms

SQLite defines five constraint conflict resolution algorithms as follows:

ROLLBACK

When a constraint violation occurs, an immediate ROLLBACK occurs, thus ending the current transaction, and the command aborts with a return code of SQLITE_CONSTRAINT. If no transaction is active (other than the implied transaction that is created on every command) then this algorithm works the same as ABORT.

ABORT

When a constraint violation occurs, the command backs out any prior changes it might have made and aborts with a return code of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes from prior commands within the same transaction are preserved. This is the default behavior for SQLite.

FAIL

When a constraint violation occurs, the command aborts with a return code SQLITE_CONSTRAINT. But any changes to the database that the command made prior to encountering the constraint violation are preserved and are not backed out. For example, if an UPDATE statement encountered a constraint violation on the 100th row that it attempts to update, then the first 99 row changes are preserved but change to rows 100 and beyond never occur.

IGNORE

When a constraint violation occurs, the one row that contains the constraint violation is not inserted or changed. But the command continues executing normally. Other rows before and after the row that contained the constraint violation continue to be inserted or updated normally. No error is returned.

REPLACE

When a UNIQUE constraint violation occurs, the pre-existing row that caused the constraint violation is removed prior to inserting or updating the current row. Thus the insert or update always occurs. The command continues executing normally. No error is returned.


SQLite Consortium

Choose any three.
About Sitemap Documentation Download License News Support

The SQLite Consortium

The SQLite Consortium is a membership association dedicated to insuring the continuing vitality and independence of SQLite. SQLite is high-quality, public domain software. The goal of the SQLite Consortium is to make sure it stays that way.

Consortium members contribute funding to support the ongoing development and maintenance of SQLite and in return receive enterprise-level technical support and legal assurances that SQLite will remain independent and open-source. Consortium members have direct access to the SQLite developers and receive priority consideration for any bug fixes or feature requests. However, technical control and direction of SQLite remains with the SQLite architect and developers. An important goal of the SQLite Consortium, after all, is to make sure that SQLite does not fall under the governance of any single company but remains independent and fully under the control of the SQLite developers.

Companies that use SQLite as a critical component in their products or infrastructure may want to consider becoming SQLite Consortium Members as inexpensive insurance in the future vitality and independence of SQLite. The SQLite Consortium membership fee is a fraction of the cost of devoting internal staff to supporting the SQLite code base. Benefits of membership include:

  • Consortium members have the guaranteed, undivided attention of the SQLite developers for 23 staff-days per year and for as much additional time above and beyond that amount that the core developers have available. There are no arbitrary limits on contact time. The consortium will never be over-subscribed. New SQLite developers will be recruited and trained as necessary to cover the 23 day/year support commitment.

  • Consortium members can call any developer at any time, day or night, and expect to get their full and immediate attention. Consortium members have access to the home telephone numbers and cellphone numbers and work schedules of the core developers so that the developers can be tracked down quickly in a crisis.

  • The SQLite developers are eager and happy to write new code or debug existing code for consortium members. Consortium members can request and expect to receive significant new enhancements to the public SQLite code base. Consortium members can also request their own private, proprietary extensions and enhancements.

  • Consortium members can receive support for any version of SQLite no matter how old. Bug fixes will be back ported to older versions of SQLite upon request.

  • Consortium members can receive private email and/or telephone notifications and briefings covering new bugs or recently added features. The core developers are constantly watching out for the interests of consortium members and will attempt to protect those interests in every way possible and alert members when their interests are threatened in any way.

  • The SQLite developers will set up customized regression tests to fully and completely test SQLite as configured by consortium members. Normally, only the standard SQLite configuration is fully tested at each release. Consortium members that use a non-standard configuration can request that their configuration be tested to the same level of detail.

  • Support requests are accepted from any employee or contractor working for a consortium member. Support is not limited to a single development team as it is with a maintenance subscription or technical support agreement.

  • Support requests, comments, and suggestions for future changes to SQLite coming from consortium members take priority over requests from all other sources. Consortium members go to the front of the line.

  • We will be happy to recognize consortium members on the SQLite website with a logo and/or a brief acknowledgement of their contribution to the project. This is an opportunity for companies to build good will by demonstrating that they are giving back to the community. Or, members can remain anonymous.

How To Become A Consortium Member

Membership in the SQLite Consortium is via contract with Hipp, Wyrick & Company, Inc.. Please call +1.704.948.4565 during US east-coast business hours for additional information.


SQLite Consortium Agreement

This SQLite Consortium Agreement ("Agreement") is made and entered into as of the _____ day of ______________, 2007 ("Effective Date") by and between ___________________ (the "Company"), and Hipp, Wyrick & Company, Inc., a Georgia Corporation with headquarters at 6200 Maple Cove Lane, Charlotte, NC ("Hwaci").

WHEREAS, Hwaci is the developer of a serverless, embeddable, public domain SQL database engine available at http://www.sqlite.org/ ("SQLite"); and

WHEREAS, Company wishes to support the independent development of the SQLite database engine to insure the continuing reliability, vitality, and independence of SQLite, and in connection therewith, Company wishes to provide funds for ongoing research, development, and maintenance of the SQLite code base, operation of the SQLite website, protection and maintenance of the SQLite trademark, as well as for promotion of SQLite at conferences and trade shows; and

WHEREAS, Company wishes to receive benefits in the form of services from Hwaci in consideration for their support of SQLite; and

WHEREAS, Company and Hwaci each wish SQLite to be supported and maintained as an independent, community-driven project, and to ensure the SQLite development team remains independent.

NOW, THEREFORE, in consideration of the mutual promises contained herein, the parties agree as follows:

1.0 Definitions

1.1 SQLite Developers

The "SQLite Developers" are the employees or contractors of Hwaci engaged in the development of SQLite, including without limitation the SQLite Architect.

1.2 SQLite Architect

The "SQLite Architect" is the SQLite Developer with ultimate responsibility and authority over changes and maintenance of the SQLite code. The current SQLite Architect is the original designer and developer of SQLite, D. Richard Hipp. Hwaci may change the SQLite Architect from time to time upon approval by Company.

1.3 Consortium Member

A "Consortium Member" is a company or organization, including but not limited to Company, which has entered into an agreement with Hwaci which is substantially similar to this Agreement.

2.0 Agreement

2.1 Responsibilities And Obligations Of SQLite Developers

2.1.1 General Support

The SQLite Developers shall provide, without limit, timely and accurate answers, advice, and instruction in response to questions and comments from Company about SQLite submitted by email or by telephone at any time day or night.

2.1.2 Debugging Support

The SQLite Developers shall at Company's request provide Company with direct assistance in debugging applications that are built upon or use SQLite. The combined time for Debugging Support and Custom Development for Company is limited to 330 hours per year.

2.1.3 Custom Development

The SQLite Developers shall at the request of Company write new extensions or enhancements to SQLite according to Company's specifications. These extensions and enhancements may be proprietary to Company or open source or with the consent of both Company and the SQLite Architect may be folded into the public domain SQLite source tree. The time devoted to Custom Development for Company is limited 220 hours per year.

2.1.4 Custom Builds

The SQLite Developers shall at Company's request provide Company with specialized builds of SQLite according to Company's specifications.

2.1.5 Legacy Support

The SQLite Developers shall at Company's request provide support and bug-fix patches for any historical version of SQLite.

2.1.6 Custom Testing

The SQLite Developers shall at Company's request set up and run acceptance tests according Company's specifications that are specifically designed to exercise SQLite as configured and used by Company. These acceptance tests shall be run and shall pass prior to any release of SQLite.

2.1.7 Priority Bug Fixes

The SQLite Developers shall assign highest priority to fixing bugs in SQLite that are reported by Company or in which Company has expressed a specific interest.

2.1.8 Code Quality

The SQLite Developers shall at all times keep the SQLite source code well commented and documented and clearly structured and organized so that an experienced and competent programmer can understand it and support it after no more than a few months of study.

2.1.9 Backwards Compatibility

The SQLite Developers recognize that Company uses SQLite in mission-critical applications and therefore shall work diligently to ensure continuing bug-free correct operation and backwards compatibility with prior releases.

2.1.10 Test Coverage

The SQLite Developers shall maintain the SQLite test suite such that no less than 95% source code coverage is provided.

2.1.11 Website

The SQLite Developers shall maintain the SQLite website at http://www.sqlite.org/ in good working order and all SQLite source code shall be made freely available at such website.

2.2 Responsibilities And Obligations Of The SQLite Architect

2.2.1 Private Briefings

The SQLite Architect shall, at the request of Company, provide Company with private notification and briefings of any new bugs or new features in SQLite that might effect Company's products.

2.2.2 Direction

The SQLite Architect shall coordinate the activities of SQLite Developers and shall publish from time to time a roadmap of proposed future changes and enhancements to SQLite.

2.2.3 Oversight

The SQLite Architect shall personally review all changes to the SQLite Source Code and take responsibility for the quality and correctness of those changes.

2.2.4 Continuity

The initial SQLite Architect shall be the original developer of SQLite, D. Richard Hipp. The role of SQLite Architect shall not be assigned to another during the term of this Agreement except due to the disability of Dr. Hipp and with approval of Company.

2.3 Responsibilities And Obligations Of Hwaci

2.3.1 Employer

Hwaci shall act as the employer of the SQLite Developers and SQLite Architect and shall make all tax and legal filings and tax withholding required by employers. Hwaci shall provide Company with W-9 information upon request.

2.3.2 Responsible Party

All obligations of the SQLite Developers set forth in this agreement are deemed obligations of Hwaci. Hwaci shall recruit, employ, and supervise SQLite Developers in such a way that the responsibilities and obligations of the SQLite Developers set forth in this agreement are upheld.

2.3.3 Multiple Developers

Hwaci shall recruit and employ as many SQLite Developers for as many hours as can be reasonably achieved using the funds received from Consortium Members under this agreement. So that support for SQLite will not be interrupted by the disability or withdrawal of any one SQLite Developer, Hwaci will keep at least two knowledgeable and competent SQLite Developers on staff.

2.3.4 Mentorship

Hwaci shall work to encourage independent programmers from around the world to become familiar with SQLite internals so that there will be a pool of talent able to support SQLite in the future.

2.3.5 Audits

Hwaci shall keep and maintain complete and accurate records of the use of development funds provided by Company and shall allow Company, or its representative, a certified public accountant mutually acceptable to Hwaci and Company, during office hours and at reasonable intervals, no more than once every 12 months, to inspect and make extracts or copies of such records solely for the purpose of ascertaining Hwaci's compliance with the objectives and requirements of this agreement.

2.3.6 Disaster Planning

Hwaci shall maintain backup copies of all SQLite source files and documentation, current and historical, at at least two separate locations separated from each other and from the primary on-line SQLite repository by at least 400 kilometers.

2.3.7 Trademark

Hwaci shall maintain ownership of the SQLite trademark and the sqlite.org domain name and shall purchase bandwidth and server space for the http://www.sqlite.org/ website.

2.3.8 No Take-overs or Buy-outs

Neither Hwaci nor the SQLite Architect shall relinquish development control of SQLite during the term of this Agreement, by acquisition or merger or by any other means, except with the consent of Company.

2.3.9 New Consortium Members

New Consortium Members may be accepted into the consortium from time to time under identical terms as this agreement, or under substantially similar terms that have been approved by existing Consortium Members.

2.3.10 Adequate Staff

Hwaci shall recruit and employ a sufficient number of qualified SQLite Developers to easily cover all custom development, debugging, and general support service obligations for all Consortium Members while still providing ample time for the SQLite Developers to engage in general maintenance and extension of SQLite.

2.3.11 Use Of Funds

Hwaci shall use the funds provided hereunder solely for the development and maintenance of SQLite as set forth in this Agreement. Interest on funds received in advance and held in trust will be reinvested and used for the same purposes as the principal.

2.4 Responsibilities And Obligations Of Company

2.4.1 Funding

Company shall provide funding for the ongoing support and maintenance of SQLite as set forth in section 3.0 "Fees".

2.4.2 Copyright Disclaimer

Company acknowledges that SQLite source code and documentation published on the SQLite website is in the public domain and that nothing in this agreement shall change that fact.

3.0 Fees

In consideration of the performance by Hwaci, the SQLite Developers, and the SQLite Architect of the obligations described herein, Company shall pay Hwaci at least US $75,000 per year in advance either annually, quarterly, or monthly, at Company's discretion.

4.0 Confidentiality

4.1 Definition of Confidential Information

"Confidential Information" means any Company proprietary information, technical data, trade secrets or know-how, including, but not limited to, research, product plans, products, services, customers, customer lists, markets, software, developments, inventions, processes, formulas, technology, designs, drawings, engineering, hardware configuration information, marketing, finances or other business information disclosed by Company either directly or indirectly in writing, orally or by drawings or inspection of parts or equipment.

4.2 Non-Use and Non-Disclosure.

Hwaci shall not, during or subsequent to the term of this Agreement, use Company's Confidential Information for any purpose whatsoever other than the performance of the Services or disclose Company's Confidential Information to any third party. The parties acknowledge that Confidential Information will remain the sole property of Company. Hwaci shall take all reasonable precautions to prevent any unauthorized disclosure of Confidential Information including, but not limited to, having each employee or consultant of Hwaci, if any, with access to any Confidential Information, execute a nondisclosure agreement containing provisions in Company's favor substantially similar to this Agreement. Confidential Information does not include information that: (i) is known to Hwaci at the time of disclosure to Hwaci by Company as evidenced by written records of Hwaci; (ii) has become publicly known and made generally available through no wrongful act of Hwaci; or (iii) has been received by Hwaci from a third party who is authorized to make such disclosure.

4.2.1 Disclosure Required by Law

In the event any Confidential Information is required to be disclosed by Hwaci under the terms of a valid and effective subpoena or order issued by a court of competent jurisdiction, or by a demand or information request from an executive or administrative agency or other governmental authority, Hwaci shall, unless prohibited by the terms of a subpoena, order, or demand, promptly notify Company of the existence, terms and circumstances surrounding such demand or request, shall consult with Company on the advisability of taking legally available steps to resist or narrow such demand or request, and, if disclosure of such Confidential Information is required, shall exercise its reasonable best efforts to narrow the scope of disclosure and obtain an order or other reliable assurance that confidential treatment will be accorded to such Confidential Information. To the extent that Hwaci is prohibited from notifying Company of a subpoena, order or demand, by the terms of same, Hwaci shall exercise its reasonable efforts to narrow the scope of disclosure.

4.3 Return of Materials.

Upon the termination of this Agreement, or upon Company's earlier request, Hwaci shall deliver to Company all of Company's property or Confidential Information that Hwaci may have in Hwaci's possession or control.

5.0 Intellectual Property

5.1 No Assignment

Company acknowledges that all copyrightable material, notes, records, drawings, designs, inventions, improvements, developments, discoveries and trade secrets made, generated, conceived, or reduced to practice by Hwaci related to SQLite will remain the property of Hwaci. Nothing in this Agreement will be construed to transfer any intellectual property right of Hwaci to Company.

5.2 Availability and Public Domain Dedication

The SQLite Developers and Hwaci shall, subject to their discretion as to the quality and suitability of the SQLite source code and documentation for public release, make the SQLite source code and documentation publicly available as downloadable files and make a public statement ceding all intellectual property rights, including but not limited to copyright and patent rights, in the SQLite source code and documentation to the public domain. To the extent that the SQLite Developers and Hwaci elect not to release the SQLite source code and documentation publicly, they shall provide copies thereof to Company and hereby grants to Company, under all of the SQLite Developers' and Hwaci's rights including but not limited to copyright and patent rights, in and to the SQLite source code and documentation, perpetual, irrevocable, worldwide, non-exclusive, sublicenseable license to use, copy, prepare derivative works of, publicly perform and display the SQLite source code and documentation and derivative works thereof.

5.3 Trademark

Hwaci shall use the name "SQLite" only to apply to the publicly available project known by such name as of the Effective Date. Hwaci may in its discretion file such trademark applications or registrations as it deems appropriate to protect or record its rights therein, and may set such policies as it deems appropriate for licensing the use of the trademark.

6.0 Representations And Warranties

6.1 Intellectual Property Clearances.

Hwaci hereby represents and warrants that Hwaci shall enter into agreements with the SQLite Developers sufficient to enable Hwaci to undertake the obligations of Section 5.

6.2 Disclaimer.

THE WORK PRODUCT AND ALL MATERIAL PROVIDED BY HWACI AND COMPANY ARE PROVIDED "AS IS." NEITHER PARTY MAKES ANY REPRESENTATIONS OR WARRANTIES OF ANY KIND, WHETHER ORAL OR WRITTEN, WHETHER EXPRESS, IMPLIED, OR ARISING BY STATUTE, CUSTOM, COURSE OF DEALING OR TRADE USAGE, WITH RESPECT TO THE SUBJECT MATTER HEREOF, IN CONNECTION WITH THIS AGREEMENT. EACH PARTY SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIED WARRANTIES OR CONDITIONS OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

7.0 Term And Termination

7.1 Term.

This Agreement will commence on the Effective Date and will continue until 12 months after the Effective Date. Thereafter, the parties may by mutual consent renew this Agreement subject to agreement on fees to be paid by Company for sponsorship for additional periods.

7.2 Termination.

If either party materially defaults in the performance of any of its material obligations hereunder and if any such default is not corrected within 30 days after notice in writing, then the non-defaulting party, at its option, may, in addition to any other remedies it may have, thereupon terminate this Agreement by giving written notice of termination to the defaulting party.

7.3 Survival.

Upon such termination all rights and duties of the parties toward each other will cease except: Sections 4 (Confidentiality), 5 (Intellectual Property), and 8 (Miscellaneous) will survive termination of this Agreement.

8. Miscellaneous

8.1 Nonassignment/Binding Agreement.

The parties acknowledge that the unique nature of Hwaci's services are substantial consideration for the parties' entering into this Agreement. Neither this Agreement nor any rights under this Agreement may be assigned or otherwise transferred by Hwaci, in whole or in part, whether voluntarily or by operation of law, without the prior written consent of Company, which consent will not be unreasonably withheld. Subject to the foregoing, this Agreement will be binding upon and will inure to the benefit of the parties and their respective successors and assigns. Any assignment in violation of the foregoing will be null and void.

8.2 Notices.

Any notice required or permitted under the terms of this Agreement or required by law must be in writing and must be: (a) delivered in person; (b) sent by first class registered mail, or air mail, as appropriate; or (c) sent by overnight air courier, in each case properly posted and fully prepaid to the appropriate address set forth in the preamble to this Agreement. Either party may change its address for notice by notice to the other party given in accordance with this Section. Notices will be considered to have been given at the time of actual delivery in person, three business days after deposit in the mail as set forth above, or one day after delivery to an overnight air courier service.

8.3 Waiver.

Any waiver of the provisions of this Agreement or of a party's rights or remedies under this Agreement must be in writing to be effective. Failure, neglect, or delay by a party to enforce the provisions of this Agreement or its rights or remedies at any time, will not be construed as a waiver of such party's rights under this Agreement and will not in any way affect the validity of the whole or any part of this Agreement or prejudice such party's right to take subsequent action. No exercise or enforcement by either party of any right or remedy under this Agreement will preclude the enforcement by such party of any other right or remedy under this Agreement or that such party is entitled by law to enforce.

8.4 Severability.

If any term, condition, or provision in this Agreement is found to be invalid, unlawful or unenforceable to any extent, the parties shall endeavor in good faith to agree to such amendments that will preserve, as far as possible, the intentions expressed in this Agreement. If the parties fail to agree on such an amendment, such invalid term, condition or provision will be severed from the remaining terms, conditions and provisions, which will continue to be valid and enforceable to the fullest extent permitted by law.

8.5 Integration.

This Agreement contains the entire agreement of the parties with respect to the subject matter of this Agreement and supersedes all previous communications, representations, understandings and agreements, either oral or written, between the parties with respect to said subject matter. This Agreement may not be amended, except by a writing signed by both parties.

8.6 Counterparts.

This Agreement may be executed in counterparts, each of which so executed will be deemed to be an original and such counterparts together will constitute one and the same agreement.

8.7 Governing Law.

This Agreement will be interpreted and construed in accordance with the laws of the State of North Carolina and the United States of America, without regard to conflict of law principles. All disputes arising out of this Agreement will be subject to the exclusive jurisdiction of the state and federal courts located in North Carolina, and each party hereby consents to the personal jurisdiction thereof.

8.8 Independent Contractors.

It is the intention of the parties that Hwaci is an independent contractor. Nothing in this Agreement will in any way be construed to constitute Hwaci or any of its employees as an agent, employee or representative of Company.

9.0 Signatures

The parties have executed this Agreement below to indicate their acceptance of its terms.

HWACI
By:

Print Name:

Title:

 COMPANY
By:

Print Name:

Title:


SQLite Copyright

SQLite is in the
Public Domain

All of the deliverable code in SQLite has been dedicated to the public domain by the authors. All code authors, and representatives of the companies they work for, have signed affidavits dedicating their contributions to the public domain and originals of those signed affidavits are stored in a firesafe at the main offices of Hwaci. Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original SQLite code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

The previous paragraph applies to the deliverable code in SQLite - those parts of the SQLite library that you actually bundle and ship with a larger application. Portions of the documentation and some code used as part of the build process might fall under other licenses. The details here are unclear. We do not worry about the licensing of the documentation and build code so much because none of these things are part of the core deliverable SQLite library.

All of the deliverable code in SQLite has been written from scratch. No code has been taken from other projects or from the open internet. Every line of code can be traced back to its original author, and all of those authors have public domain dedications on file. So the SQLite code base is clean and is uncontaminated with licensed code from other projects.

Obtaining An Explicit License To Use SQLite

Even though SQLite is in the public domain and does not require a license, some users want to obtain a license anyway. Some reasons for obtaining a license include:

  • You are using SQLite in a jurisdiction that does not recognize the public domain.
  • You are using SQLite in a jurisdiction that does not recognize the right of an author to dedicate their work to the public domain.
  • You want to hold a tangible legal document as evidence that you have the legal right to use and distribute SQLite.
  • Your legal department tells you that you have to purchase a license.

If you feel like you really have to purchase a license for SQLite, Hwaci, the company that employs the architect and principal developers of SQLite, will sell you one.

Contributed Code

In order to keep SQLite completely free and unencumbered by copyright, all new contributors to the SQLite code base are asked to dedicate their contributions to the public domain. If you want to send a patch or enhancement for possible inclusion in the SQLite source tree, please accompany the patch with the following statement:

The author or authors of this code dedicate any and all copyright interest in this code to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this code under copyright law.

We are not able to accept patches or changes to SQLite that are not accompanied by a statement such as the above. In addition, if you make changes or enhancements as an employee, then a simple statement such as the above is insufficient. You must also send by surface mail a copyright release signed by a company officer. A signed original of the copyright release should be mailed to:

Hwaci
6200 Maple Cove Lane
Charlotte, NC 28269
USA

A template copyright release is available in PDF or HTML. You can use this release to make future changes.


SQLite Copyright Release Template

Copyright Release for
Contributions To SQLite

SQLite is software that implements an embeddable SQL database engine. SQLite is available for free download from http://www.sqlite.org/. The principal author and maintainer of SQLite has disclaimed all copyright interest in his contributions to SQLite and thus released his contributions into the public domain. In order to keep the SQLite software unencumbered by copyright claims, the principal author asks others who may from time to time contribute changes and enhancements to likewise disclaim their own individual copyright interest.

Because the SQLite software found at http://www.sqlite.org/ is in the public domain, anyone is free to download the SQLite software from that website, make changes to the software, use, distribute, or sell the modified software, under either the original name or under some new name, without any need to obtain permission, pay royalties, acknowledge the original source of the software, or in any other way compensate, identify, or notify the original authors. Nobody is in any way compelled to contribute their SQLite changes and enhancements back to the SQLite website. This document concerns only changes and enhancements to SQLite that are intentionally and deliberately contributed back to the SQLite website.

For the purposes of this document, "SQLite software" shall mean any computer source code, documentation, makefiles, test scripts, or other information that is published on the SQLite website, http://www.sqlite.org/. Precompiled binaries are excluded from the definition of "SQLite software" in this document because the process of compiling the software may introduce information from outside sources which is not properly a part of SQLite.

The header comments on the SQLite source files exhort the reader to share freely and to never take more than one gives. In the spirit of that exhortation I make the following declarations:

  1. I dedicate to the public domain any and all copyright interest in the SQLite software that was publicly available on the SQLite website (http://www.sqlite.org/) prior to the date of the signature below and any changes or enhancements to the SQLite software that I may cause to be published on that website in the future. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to the SQLite software under copyright law.

  2. To the best of my knowledge and belief, the changes and enhancements that I have contributed to SQLite are either originally written by me or are derived from prior works which I have verified are also in the public domain and are not subject to claims of copyright by other parties.

  3. To the best of my knowledge and belief, no individual, business, organization, government, or other entity has any copyright interest in the SQLite software as it existed on the SQLite website as of the date on the signature line below.

  4. I agree never to publish any additional information to the SQLite website (by CVS, email, scp, FTP, or any other means) unless that information is an original work of authorship by me or is derived from prior published versions of SQLite. I agree never to copy and paste code into the SQLite code base from other sources. I agree never to publish on the SQLite website any information that would violate a law or breach a contract.

Signature:

Date:
Name (printed):


SQLite Developers

Choose any three.
About Sitemap Documentation Download License News Support

The SQLite Development Team

D. Richard Hipp began the SQLite project in on 2000-May-29 and continues to serve as the project architect. Richard was born, lives, and works in Charlotte, North Carolina. He holds degrees from Georgia Tech (MSEE, 1984) and Duke University (PhD, 1992) and is the founder of the consulting firm Hwaci.

Dan Kennedy is an Australian currently based in South-East Asia. He holds a degree in Computer System Engineering from the University of Queensland and has worked in a variety of fields, including industrial automation, computer graphics and embedded software development. Dan has been a key contributor to SQLite since 2002.

Joe Mistachkin (pronounced "miss-tash-kin") is a software engineer and one of the maintainers of Tcl/Tk. He is also the author of the TclBridge component and the Eagle scripting language. He has been working in the software industry since 1994.


Custom Builds Of SQLite

Choose any three.
About Sitemap Documentation Download License News Support

Custom Builds Of SQLite
or
Porting SQLite To New Operating Systems

1.0 Introduction

For most applications, the recommended method for building SQLite is to use the amalgamation code file, sqlite3.c, and its corresponding header file sqlite3.h. The sqlite3.c code file should compile and run on any Unix, Windows, OS/2, or Mac OS X system without any changes or special compiler options. Most applications can simply include the sqlite3.c file together with the other C code files that make up the application, compile them all together, and have working and well configured version of SQLite.

Most applications work great with SQLite in its default configuration and with no special compile-time configuration. Most developers should be able to completely ignore this document and simply build SQLite from the amalgamation without any special knowledge and without taking any special actions.

However, highly tuned and specialized applications may want or need to replace some of SQLite's built-in system interfaces with alternative implementations more suitable for the needs of the application. SQLite is designed to be easily reconfigured at compile-time to meet the specific needs of individual projects. Among the compile-time configuration options for SQLite are these:

  • Replace the built-in mutex subsystem with an alternative implementation.

  • Completely disable all mutexing for use in single-threaded applications.

  • Reconfigure the memory allocation subsystem to use a memory allocator other the malloc() implementation from the standard library.

  • Realign the memory allocation subsystem so that it never calls malloc() at all but instead satisfies all memory requests using a fixed-size memory buffer assigned to SQLite at startup.

  • Replace the interface to the file system with an alternative design. In other words, override all of the system calls that SQLite makes in order to talk to the disk with a completely different set of system calls.

  • Override other operating system interfaces such as calls to obtain Zulu or local time.

Generally speaking, there are three separate subsystems within SQLite that can be modified or overridden at compile-time. The mutex subsystem is used to serialize access to SQLite resources that are shared among threads. The memory allocation subsystem is used to allocate memory required by SQLite objects and for the database cache. Finally, the Virtual File System subsystem is used to provide a portable interface between SQLite and the underlying operating system and especially the file system. We call these three subsystems the "interface" subsystems of SQLite.

We emphasis that most applications are well-served by the built-in default implementations of the SQLite interface subsystems. Developers are encouraged to use the default built-in implementations whenever possible and to build SQLite without any special compile-time options or parameters. However, some highly specialized applications may benefit from substituting or modifying one or more of these built-in SQLite interface subsystems. Or, if SQLite is used on an operating system other than Unix (Linux or Mac OS X), Windows (Win32 or WinCE), or OS/2 then none of the interface subsystems that come built into SQLite will work and the application will need to provide alternative implementations suitable for the target platform.

2.0 Configuring Or Replacing The Mutex Subsystem

In a multithreaded environment, SQLite uses mutexes to serialize access to shared resources. The mutex subsystem is only required for applications that access SQLite from multiple threads. For single-threaded applications, or applications which only call SQLite from a single thread, the mutex subsystem can be completely disabled by recompiling with the following option:

-DSQLITE_THREADSAFE=0

Mutexes are cheap but they are not free, so performance will be better when mutexes are completely disabled. The resulting library footprint will also be a little smaller. Disabling the mutexes at compile-time is a recommended optimization for applications where it makes sense.

When using SQLite as a shared library, an application can test to see whether or not mutexes have been disabled using the sqlite3_threadsafe() API. Applications that link against SQLite at run-time and use SQLite from multiple threads should probably check this API to make sure they did not accidentally get linked against a version of the SQLite library that has its mutexes disabled. Single-threaded applications will, of course, work correctly regardless of whether or not SQLite is configured to be threadsafe, though they will be a little bit faster when using versions of SQLite with mutexes disabled.

SQLite mutexes can also be disabled at run-time using the sqlite3_config() interface. To completely disable all mutexing, the application can invoke:

sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);

Disabling mutexes at run-time is not as effective as disabling them at compile-time since SQLite still must do a test of a boolean variable to see if mutexes are enabled or disabled at each point where a mutex might be required. But there is still a performance advantage for disabling mutexes at run-time.

For multi-threaded applications that are careful about how they manage threads, SQLite supports an alternative run-time configuration that is half way between not using any mutexes and the default situation of mutexing everything in sight. This in-the-middle mutex alignment can be established as follows:

sqlite3_config(SQLITE_CONFIG_MULTITHREAD);
sqlite3_config(SQLITE_CONFIG_MEMSTATUS, 0);

There are two separate configuration changes here which can be used either togethr or separately. The SQLITE_CONFIG_MULTITHREAD setting disables the mutexes that serialize access to database connection objects and prepared statement objects. With this setting, the application is free to use SQLite from multiple threads, but it must make sure than no two threads try to access the same database connection or any prepared statements associated with the same database connection at the same time. Two threads can use SQLite at the same time, but they must use separate database connections. The second SQLITE_CONFIG_MEMSTATUS setting disables the mechanism in SQLite that tracks the total size of all outstanding memory allocation requests. This omits the need to mutex each call to sqlite3_malloc() and sqlite3_free(), which saves a huge number of mutex operations. But a consequence of disabling the memory statistics mechanism is that the sqlite3_memory_used(), sqlite3_memory_highwater(), and sqlite3_soft_heap_limit64() interfaces cease to work.

SQLite uses pthreads for its mutex implementation on Unix and SQLite requires a recursive mutex. Most modern pthread implementations support recursive mutexes, but not all do. For systems that do not support recursive mutexes, it is recommended that applications operate in single-threaded mode only. If this is not possible, SQLite provides an alternative recursive mutex implementation built on top of the standard "fast" mutexes of pthreads. This alternative implementation should work correctly as long as pthread_equal() is atomic and the processor has a coherent data cache. The alternative recursive mutex implementation is enabled by the following compiler command-line switch:

-DSQLITE_HOMEGROWN_RECURSIVE_MUTEX=1

When porting SQLite to a new operating system, it is usually necessary to completely replace the built-in mutex subsystem with an alternative built around the mutex primitives of the new operating system. This is accomplished by compiling SQLite with the following option:

-DSQLITE_MUTEX_APPDEF=1

When SQLite is compiled with the SQLITE_MUTEX_APPDEF=1 option, it completely omits the implementation of its mutex primitive functions. But the SQLite library still attempts to call these functions where necessary, so the application must itself implement the mutex primitive functions and link them together with SQLite.

3.0 Configuring Or Replacing The Memory Allocation Subsystem

By default, SQLite obtains the memory it needs for objects and cache from the malloc()/free() implementation of the standard library. There is also on-going work with experimental memory allocators that satisfy all memory requests from a single fixed memory buffer handed to SQLite at application start. Additional information on these experimental memory allocators will be provided in a future revision of this document.

SQLite supports the ability of an application to specify an alternative memory allocator at run-time by filling in an instance of the sqlite3_mem_methods object with pointers to the routines of the alternative implementation then registering the new alternative implementation using the sqlite3_config() interface. For example:

sqlite3_config(SQLITE_CONFIG_MALLOC, &my_malloc_implementation);

SQLite makes a copy of the content of the sqlite3_mem_methods object so the object can be modified after the sqlite3_config() call returns.

4.0 Adding New Virtual File Systems

Since version 3.5.0, SQLite has supported an interface called the virtual file system or "VFS". This object is somewhat misnamed since it is really an interface to the whole underlying operating system, not just the filesystem.

One of the interesting features of the VFS interface is that SQLite can support multiple VFSes at the same time. Each database connection has to choose a single VFS for its use when the connection is first opened using sqlite3_open_v2(). But if a process contains multiple database connections each can choose a different VFS. VFSes can be added at run-time using the sqlite3_vfs_register() interface.

The default builds for SQLite on Unix, Windows, and OS/2 include a VFS appropriate for the target platform. SQLite builds for other operating systems do not contain a VFS by default, but the application can register one or more at run-time.

5.0 Porting SQLite To A New Operating System

In order to port SQLite to a new operating system - an operating system not supported by default - the application must provide...

  • a working mutex subsystem (but only if it is multithreaded),
  • a working memory allocation subsystem (assuming it lacks malloc() in its standard library), and
  • a working VFS implementation.

All of these things can be provided in a single auxiliary C code file and then linked with the stock "sqlite3.c" code file to generate a working SQLite build for the target operating system. In addition to the alternative mutex and memory allocation subsystems and the new VFS, the auxiliary C code file should contain implementations for the following two routines:

  • sqlite3_os_init()
  • sqlite3_os_end()

The "sqlite3.c" code file contains default implementations of a VFS and of the sqlite3_initialize() and sqlite3_shutdown() functions that are appropriate for Unix, Windows, and OS/2. To prevent one of these default components from being loaded when sqlite3.c is compiled, it is necessary to add the following compile-time option:

-DSQLITE_OS_OTHER=1

The SQLite core will call sqlite3_initialize() early. The auxiliary C code file can contain an implementation of sqlite3_initialize() that registers an appropriate VFS and also perhaps initializes an alternative mutex system (if mutexes are required) or does any memory allocation subsystem initialization that is required. The SQLite core never calls sqlite3_shutdown() but it is part of the official SQLite API and is not otherwise provided when compiled with -DSQLITE_OS_OTHER=1, so the auxiliary C code file should probably provide it for completeness.


Datatypes In SQLite Version 3

Most SQL database engines (every SQL database engine other than SQLite, as far as we know) uses static, rigid typing. With static typing, the datatype of a value is determined by its container - the particular column in which the value is stored.

SQLite uses a more general dynamic type system. In SQLite, the datatype of a value is associated with the value itself, not with its container. The dynamic type system of SQLite is backwards compatible with the more common static type systems of other database engines in the sense that SQL statement that work on statically typed databases should work the same way in SQLite. However, the dynamic typing in SQLite allows it to do things which are not possible in traditional rigidly typed databases.

1.0 Storage Classes and Datatypes

Each value stored in an SQLite database (or manipulated by the database engine) has one of the following storage classes:

  • NULL. The value is a NULL value.

  • INTEGER. The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.

  • REAL. The value is a floating point value, stored as an 8-byte IEEE floating point number.

  • TEXT. The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16LE).

  • BLOB. The value is a blob of data, stored exactly as it was input.

Note that a storage class is slightly more general than a datatype. The INTEGER storage class, for example, includes 6 different integer datatypes of different lengths. This makes a difference on disk. But as soon as INTEGER values are read off of disk and into memory for processing, they are converted to the most general datatype (8-byte signed integer). And so for the most part, "storage class" is indistinguishable from "datatype" and the two terms can be used interchangeably.

Any column in an SQLite version 3 database, except an INTEGER PRIMARY KEY column, may be used to store a value of any storage class.

All values in SQL statements, whether they are literals embedded in SQL statement text or parameters bound to precompiled SQL statements have an implicit storage class. Under circumstances described below, the database engine may convert values between numeric storage classes (INTEGER and REAL) and TEXT during query execution.

1.1 Boolean Datatype

SQLite does not have a separate Boolean storage class. Instead, Boolean values are stored as integers 0 (false) and 1 (true).

1.2 Date and Time Datatype

SQLite does not have a storage class set aside for storing dates and/or times. Instead, the built-in Date And Time Functions of SQLite are capable of storing dates and times as TEXT, REAL, or INTEGER values:

  • TEXT as ISO8601 strings ("YYYY-MM-DD HH:MM:SS.SSS").
  • REAL as Julian day numbers, the number of days since noon in Greenwich on November 24, 4714 B.C. according to the proleptic Gregorian calendar.
  • INTEGER as Unix Time, the number of seconds since 1970-01-01 00:00:00 UTC.

Applications can chose to store dates and times in any of these formats and freely convert between formats using the built-in date and time functions.

2.0 Type Affinity

In order to maximize compatibility between SQLite and other database engines, SQLite supports the concept of "type affinity" on columns. The type affinity of a column is the recommended type for data stored in that column. The important idea here is that the type is recommended, not required. Any column can still store any type of data. It is just that some columns, given the choice, will prefer to use one storage class over another. The preferred storage class for a column is called its "affinity".

Each column in an SQLite 3 database is assigned one of the following type affinities:

  • TEXT
  • NUMERIC
  • INTEGER
  • REAL
  • NONE

A column with TEXT affinity stores all data using storage classes NULL, TEXT or BLOB. If numerical data is inserted into a column with TEXT affinity it is converted into text form before being stored.

A column with NUMERIC affinity may contain values using all five storage classes. When text data is inserted into a NUMERIC column, the storage class of the text is converted to INTEGER or REAL (in order of preference) if such conversion is lossless and reversible. For conversions between TEXT and REAL storage classes, SQLite considers the conversion to be lossless and reversible if the first 15 significant decimal digits of the number are preserved. If the lossless conversion of TEXT to INTEGER or REAL is not possible then the value is stored using the TEXT storage class. No attempt is made to convert NULL or BLOB values.

A string might look like a floating-point literal with a decimal point and/or exponent notation but as long as the value can be expressed as an integer, the NUMERIC affinity will convert it into an integer. Hence, the string '3.0e+5' is stored in a column with NUMERIC affinity as the integer 300000, not as the floating point value 300000.0.

A column that uses INTEGER affinity behaves the same as a column with NUMERIC affinity. The difference between INTEGER and NUMERIC affinity is only evident in a CAST expression.

A column with REAL affinity behaves like a column with NUMERIC affinity except that it forces integer values into floating point representation. (As an internal optimization, small floating point values with no fractional component and stored in columns with REAL affinity are written to disk as integers in order to take up less space and are automatically converted back into floating point as the value is read out. This optimization is completely invisible at the SQL level and can only be detected by examining the raw bits of the database file.)

A column with affinity NONE does not prefer one storage class over another and no attempt is made to coerce data from one storage class into another.

2.1 Determination Of Column Affinity

The affinity of a column is determined by the declared type of the column, according to the following rules in the order shown:

  1. If the declared type contains the string "INT" then it is assigned INTEGER affinity.

  2. If the declared type of the column contains any of the strings "CHAR", "CLOB", or "TEXT" then that column has TEXT affinity. Notice that the type VARCHAR contains the string "CHAR" and is thus assigned TEXT affinity.

  3. If the declared type for a column contains the string "BLOB" or if no type is specified then the column has affinity NONE.

  4. If the declared type for a column contains any of the strings "REAL", "FLOA", or "DOUB" then the column has REAL affinity.

  5. Otherwise, the affinity is NUMERIC.

Note that the order of the rules for determining column affinity is important. A column whose declared type is "CHARINT" will match both rules 1 and 2 but the first rule takes precedence and so the column affinity will be INTEGER.

2.2 Affinity Name Examples

The following table shows how many common datatype names from more traditional SQL implementations are converted into affinities by the five rules of the previous section. This table shows only a small subset of the datatype names that SQLite will accept. Note that numeric arguments in parentheses that following the type name (ex: "VARCHAR(255)") are ignored by SQLite - SQLite does not impose any length restrictions (other than the large global SQLITE_MAX_LENGTH limit) on the length of strings, BLOBs or numeric values.

Example Typenames From The
CREATE TABLE Statement
or CAST Expression 		Resulting Affinity Rule Used To Determine Affinity
INT
INTEGER
TINYINT
SMALLINT
MEDIUMINT
BIGINT
UNSIGNED BIG INT
INT2
INT8 		INTEGER 1
CHARACTER(20)
VARCHAR(255)
VARYING CHARACTER(255)
NCHAR(55)
NATIVE CHARACTER(70)
NVARCHAR(100)
TEXT
CLOB 		TEXT 2
BLOB
no datatype specified 		NONE 3
REAL
DOUBLE
DOUBLE PRECISION
FLOAT 		REAL 4
NUMERIC
DECIMAL(10,5)
BOOLEAN
DATE
DATETIME 		NUMERIC 5

Note that a declared type of "FLOATING POINT" would give INTEGER affinity, not REAL affinity, due to the "INT" at the end of "POINT". And the declared type of "STRING" has an affinity of NUMERIC, not TEXT.

2.3 Column Affinity Behavior Example

The following SQL demonstrates how SQLite uses column affinity to do type conversions when values are inserted into a table.

CREATE TABLE t1(
    t  TEXT,     -- text affinity by rule 2
    nu NUMERIC,  -- numeric affinity by rule 5
    i  INTEGER,  -- integer affinity by rule 1
    r  REAL,     -- real affinity by rule 4
    no BLOB      -- no affinity by rule 3
);

-- Values stored as TEXT, INTEGER, INTEGER, REAL, TEXT.
INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0', '500.0');
SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;
text|integer|integer|real|text

-- Values stored as TEXT, INTEGER, INTEGER, REAL, REAL.
DELETE FROM t1;
INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0, 500.0);
SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;
text|integer|integer|real|real

-- Values stored as TEXT, INTEGER, INTEGER, REAL, INTEGER.
DELETE FROM t1;
INSERT INTO t1 VALUES(500, 500, 500, 500, 500);
SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;
text|integer|integer|real|integer

-- BLOBs are always stored as BLOBs regardless of column affinity.
DELETE FROM t1;
INSERT INTO t1 VALUES(x'0500', x'0500', x'0500', x'0500', x'0500');
SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;
blob|blob|blob|blob|blob

-- NULLs are also unaffected by affinity
DELETE FROM t1;
INSERT INTO t1 VALUES(NULL,NULL,NULL,NULL,NULL);
SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;
null|null|null|null|null

3.0 Comparison Expressions

SQLite version 3 has the usual set of SQL comparison operators including "=", "==", "<", "<=", ">", ">=", "!=", "<>", "IN", "NOT IN", "BETWEEN", "IS", and "IS NOT", .

3.1 Sort Order

The results of a comparison depend on the storage classes of the operands, according to the following rules:

  • A value with storage class NULL is considered less than any other value (including another value with storage class NULL).

  • An INTEGER or REAL value is less than any TEXT or BLOB value. When an INTEGER or REAL is compared to another INTEGER or REAL, a numerical comparison is performed.

  • A TEXT value is less than a BLOB value. When two TEXT values are compared an appropriate collating sequence is used to determine the result.

  • When two BLOB values are compared, the result is determined using memcmp().

3.2 Affinity Of Comparison Operands

SQLite may attempt to convert values between the storage classes INTEGER, REAL, and/or TEXT before performing a comparison. Whether or not any conversions are attempted before the comparison takes place depends on the affinity of the operands. Operand affinity is determined by the following rules:

  • An expression that is a simple reference to a column value has the same affinity as the column. Note that if X and Y.Z are column names, then +X and +Y.Z are considered expressions for the purpose of determining affinity.

  • An expression of the form "CAST(expr AS type)" has an affinity that is the same as a column with a declared type of "type".

  • Otherwise, an expression has NONE affinity.

3.3 Type Conversions Prior To Comparison

To "apply affinity" means to convert an operand to a particular storage class if and only if the conversion is lossless and reversible. Affinity is applied to operands of a comparison operator prior to the comparison according to the following rules in the order shown:

  • If one operand has INTEGER, REAL or NUMERIC affinity and the other operand as TEXT or NONE affinity then NUMERIC affinity is applied to other operand.

  • If one operand has TEXT affinity and the other has NONE affinity, then TEXT affinity is applied to the other operand.

  • Otherwise, no affinity is applied and both operands are compared as is.

The expression "a BETWEEN b AND c" is treated as two separate binary comparisons "a >= b AND a <= c", even if that means different affinities are applied to 'a' in each of the comparisons. Datatype conversions in comparisons of the form "x IN (SELECT y ...)" are handled is if the comparison were really "x=y". The expression "a IN (x, y, z, ...)" is equivalent to "a = +x OR a = +y OR a = +z OR ...". In other words, the values to the right of the IN operator (the "x", "y", and "z" values in this example) are considered to have no affinity, even if they happen to be column values or CAST expressions.

3.4 Comparison Example

CREATE TABLE t1(
    a TEXT,      -- text affinity
    b NUMERIC,   -- numeric affinity
    c BLOB,      -- no affinity
    d            -- no affinity
);

-- Values will be stored as TEXT, INTEGER, TEXT, and INTEGER respectively
INSERT INTO t1 VALUES('500', '500', '500', 500);
SELECT typeof(a), typeof(b), typeof(c), typeof(d) FROM t1;
text|integer|text|integer

-- Because column "a" has text affinity, numeric values on the
-- right-hand side of the comparisons are converted to text before
-- the comparison occurs.
SELECT a < 40,   a < 60,   a < 600 FROM t1;
0|1|1

-- Text affinity is applied to the right-hand operands but since
-- they are already TEXT this is a no-op; no conversions occur.
SELECT a < '40', a < '60', a < '600' FROM t1;
0|1|1

-- Column "b" has numeric affinity and so numeric affinity is applied
-- to the operands on the right.  Since the operands are already numeric,
-- the application of affinity is a no-op; no conversions occur.  All
-- values are compared numerically.
SELECT b < 40,   b < 60,   b < 600 FROM t1;
0|0|1

-- Numeric affinity is applied to operands on the right, converting them
-- from text to integers.  Then a numeric comparison occurs.
SELECT b < '40', b < '60', b < '600' FROM t1;
0|0|1

-- No affinity conversions occur.  Right-hand side values all have
-- storage class INTEGER which are always less than the TEXT values
-- on the left.
SELECT c < 40,   c < 60,   c < 600 FROM t1;
0|0|0

-- No affinity conversions occur.  Values are compared as TEXT.
SELECT c < '40', c < '60', c < '600' FROM t1;
0|1|1

-- No affinity conversions occur.  Right-hand side values all have
-- storage class INTEGER which compare numerically with the INTEGER
-- values on the left.
SELECT d < 40,   d < 60,   d < 600 FROM t1;
0|0|1

-- No affinity conversions occur.  INTEGER values on the left are
-- always less than TEXT values on the right.
SELECT d < '40', d < '60', d < '600' FROM t1;
1|1|1

All of the result in the example are the same if the comparisons are commuted - if expressions of the form "a<40" are rewritten as "40>a".

4.0 Operators

All mathematical operators (+, -, *, /, %, <<, >>, &, and |) cast both operands to the NUMERIC storage class prior to being carried out. The cast is carried through even if it is lossy and irreversible. A NULL operand on a mathematical operator yields a NULL result. An operand on a mathematical operator that does not look in any way numeric and is not NULL is converted to 0 or 0.0.

5.0 Sorting, Grouping and Compound SELECTs

When query results are sorted by an ORDER BY clause, values with storage class NULL come first, followed by INTEGER and REAL values interspersed in numeric order, followed by TEXT values in collating sequence order, and finally BLOB values in memcmp() order. No storage class conversions occur before the sort.

When grouping values with the GROUP BY clause values with different storage classes are considered distinct, except for INTEGER and REAL values which are considered equal if they are numerically equal. No affinities are applied to any values as the result of a GROUP by clause.

The compound SELECT operators UNION, INTERSECT and EXCEPT perform implicit comparisons between values. No affinity is applied to comparison operands for the implicit comparisons associated with UNION, INTERSECT, or EXCEPT - the values are compared as is.

6.0 Collating Sequences

When SQLite compares two strings, it uses a collating sequence or collating function (two words for the same thing) to determine which string is greater or if the two strings are equal. SQLite has three built-in collating functions: BINARY, NOCASE, and RTRIM.

  • BINARY - Compares string data using memcmp(), regardless of text encoding.
  • NOCASE - The same as binary, except the 26 upper case characters of ASCII are folded to their lower case equivalents before the comparison is performed. Note that only ASCII characters are case folded. SQLite does not attempt to do full UTF case folding due to the size of the tables required.
  • RTRIM - The same as binary, except that trailing space characters are ignored.

An application can register additional collating functions using the sqlite3_create_collation() interface.

6.1 Assigning Collating Sequences from SQL

Every column of every table has an associated collating function. If no collating function is explicitly defined, then the collating function defaults to BINARY. The COLLATE clause of the column definition is used to define alternative collating functions for a column.

The rules for determining which collating function to use for a binary comparison operator (=, <, >, <=, >=, !=, IS, and IS NOT) are as follows and in the order shown:

  1. If either operand has an explicit collating function assignment using the postfix COLLATE operator, then the explicit collating function is used for comparison, with precedence to the collating function of the left operand.

  2. If either operand is a column, then the collating function of that column is used with precedence to the left operand. For the purposes of the previous sentence, a column name preceded by one or more unary "+" operators is still considered a column name.

  3. Otherwise, the BINARY collating function is used for comparison.

An operand of a comparison is considered to have an explicit collating function assignment (rule 1 above) if any subexpression of the operand uses the postfix COLLATE operator. Thus, if a COLLATE operator is used anywhere in a comparision expression, the collating function defined by that operator is used for string comparison regardless of what table columns might be a part of that expression. If two or more COLLATE operator subexpressions appear anywhere in a comparison, the left most explicit collating function is used regardless of how deeply the COLLATE operators are nested in the expression and regardless of how the expression is parenthesized.

The expression "x BETWEEN y and z" is logically equivalent to two comparisons "x >= y AND x <= z" and works with respect to collating functions as if it were two separate comparisons. The expression "x IN (SELECT y ...)" is handled in the same way as the expression "x = y" for the purposes of determining the collating sequence. The collating sequence used for expressions of the form "x IN (y, z, ...)" is the collating sequence of x.

Terms of the ORDER BY clause that is part of a SELECT statement may be assigned a collating sequence using the COLLATE operator, in which case the specified collating function is used for sorting. Otherwise, if the expression sorted by an ORDER BY clause is a column, then the collating sequence of the column is used to determine sort order. If the expression is not a column and has no COLLATE clause, then the BINARY collating sequence is used.

6.2 Collation Sequence Examples

The examples below identify the collating sequences that would be used to determine the results of text comparisons that may be performed by various SQL statements. Note that a text comparison may not be required, and no collating sequence used, in the case of numeric, blob or NULL values.

CREATE TABLE t1(
    x INTEGER PRIMARY KEY,
    a,                 /* collating sequence BINARY */
    b COLLATE BINARY,  /* collating sequence BINARY */
    c COLLATE RTRIM,   /* collating sequence RTRIM  */
    d COLLATE NOCASE   /* collating sequence NOCASE */
);
                   /* x   a     b     c       d */
INSERT INTO t1 VALUES(1,'abc','abc', 'abc  ','abc');
INSERT INTO t1 VALUES(2,'abc','abc', 'abc',  'ABC');
INSERT INTO t1 VALUES(3,'abc','abc', 'abc ', 'Abc');
INSERT INTO t1 VALUES(4,'abc','abc ','ABC',  'abc');

/* Text comparison a=b is performed using the BINARY collating sequence. */
SELECT x FROM t1 WHERE a = b ORDER BY x;
--result 1 2 3

/* Text comparison a=b is performed using the RTRIM collating sequence. */
SELECT x FROM t1 WHERE a = b COLLATE RTRIM ORDER BY x;
--result 1 2 3 4

/* Text comparison d=a is performed using the NOCASE collating sequence. */
SELECT x FROM t1 WHERE d = a ORDER BY x;
--result 1 2 3 4

/* Text comparison a=d is performed using the BINARY collating sequence. */
SELECT x FROM t1 WHERE a = d ORDER BY x;
--result 1 4

/* Text comparison 'abc'=c is performed using the RTRIM collating sequence. */
SELECT x FROM t1 WHERE 'abc' = c ORDER BY x;
--result 1 2 3

/* Text comparison c='abc' is performed using the RTRIM collating sequence. */
SELECT x FROM t1 WHERE c = 'abc' ORDER BY x;
--result 1 2 3

/* Grouping is performed using the NOCASE collating sequence (Values
** 'abc', 'ABC', and 'Abc' are placed in the same group). */
SELECT count(*) FROM t1 GROUP BY d ORDER BY 1;
--result 4

/* Grouping is performed using the BINARY collating sequence.  'abc' and
** 'ABC' and 'Abc' form different groups */
SELECT count(*) FROM t1 GROUP BY (d || '') ORDER BY 1;
--result 1 1 2

/* Sorting or column c is performed using the RTRIM collating sequence. */
SELECT x FROM t1 ORDER BY c, x;
--result 4 1 2 3

/* Sorting of (c||'') is performed using the BINARY collating sequence. */
SELECT x FROM t1 ORDER BY (c||''), x;
--result 4 2 3 1

/* Sorting of column c is performed using the NOCASE collating sequence. */
SELECT x FROM t1 ORDER BY c COLLATE NOCASE, x;
--result 2 4 3 1


Datatypes In SQLite Version 2

1.0 Typelessness

SQLite is "typeless". This means that you can store any kind of data you want in any column of any table, regardless of the declared datatype of that column. (See the one exception to this rule in section 2.0 below.) This behavior is a feature, not a bug. A database is suppose to store and retrieve data and it should not matter to the database what format that data is in. The strong typing system found in most other SQL engines and codified in the SQL language spec is a misfeature - it is an example of the implementation showing through into the interface. SQLite seeks to overcome this misfeature by allowing you to store any kind of data into any kind of column and by allowing flexibility in the specification of datatypes.

A datatype to SQLite is any sequence of zero or more names optionally followed by a parenthesized lists of one or two signed integers. Notice in particular that a datatype may be zero or more names. That means that an empty string is a valid datatype as far as SQLite is concerned. So you can declare tables where the datatype of each column is left unspecified, like this:

CREATE TABLE ex1(a,b,c);

Even though SQLite allows the datatype to be omitted, it is still a good idea to include it in your CREATE TABLE statements, since the data type often serves as a good hint to other programmers about what you intend to put in the column. And if you ever port your code to another database engine, that other engine will probably require a datatype of some kind. SQLite accepts all the usual datatypes. For example:

CREATE TABLE ex2(
  a VARCHAR(10),
  b NVARCHAR(15),
  c TEXT,
  d INTEGER,
  e FLOAT,
  f BOOLEAN,
  g CLOB,
  h BLOB,
  i TIMESTAMP,
  j NUMERIC(10,5)
  k VARYING CHARACTER (24),
  l NATIONAL VARYING CHARACTER(16)
);

And so forth. Basically any sequence of names optionally followed by one or two signed integers in parentheses will do.

2.0 The INTEGER PRIMARY KEY

One exception to the typelessness of SQLite is a column whose type is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT". A column of type INT PRIMARY KEY is typeless just like any other.) INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any attempt to insert non-integer data will result in an error.

INTEGER PRIMARY KEY columns can be used to implement the equivalent of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY KEY column, the column will actually be filled with an integer that is one greater than the largest key already in the table. Or if the largest key is 2147483647, then the column will be filled with a random integer. Either way, the INTEGER PRIMARY KEY column will be assigned a unique integer. You can retrieve this integer using the sqlite_last_insert_rowid() API function or using the last_insert_rowid() SQL function in a subsequent SELECT statement.

3.0 Comparison and Sort Order

SQLite is typeless for the purpose of deciding what data is allowed to be stored in a column. But some notion of type comes into play when sorting and comparing data. For these purposes, a column or an expression can be one of two types: numeric and text. The sort or comparison may give different results depending on which type of data is being sorted or compared.

If data is of type text then the comparison is determined by the standard C data comparison functions memcmp() or strcmp(). The comparison looks at bytes from two inputs one by one and returns the first non-zero difference. Strings are '\000' terminated so shorter strings sort before longer strings, as you would expect.

For numeric data, this situation is more complex. If both inputs look like well-formed numbers, then they are converted into floating point values using atof() and compared numerically. If one input is not a well-formed number but the other is, then the number is considered to be less than the non-number. If neither inputs is a well-formed number, then strcmp() is used to do the comparison.

Do not be confused by the fact that a column might have a "numeric" datatype. This does not mean that the column can contain only numbers. It merely means that if the column does contain a number, that number will sort in numerical order.

For both text and numeric values, NULL sorts before any other value. A comparison of any value against NULL using operators like "<" or ">=" is always false.

4.0 How SQLite Determines Datatypes

For SQLite version 2.6.3 and earlier, all values used the numeric datatype. The text datatype appears in version 2.7.0 and later. In the sequel it is assumed that you are using version 2.7.0 or later of SQLite.

For an expression, the datatype of the result is often determined by the outermost operator. For example, arithmetic operators ("+", "*", "%") always return a numeric results. The string concatenation operator ("||") returns a text result. And so forth. If you are ever in doubt about the datatype of an expression you can use the special typeof() SQL function to determine what the datatype is. For example:

sqlite> SELECT typeof('abc'+123);
numeric
sqlite> SELECT typeof('abc'||123);
text

For table columns, the datatype is determined by the type declaration of the CREATE TABLE statement. The datatype is text if and only if the type declaration contains one or more of the following strings:

BLOB
CHAR
CLOB
TEXT

The search for these strings in the type declaration is case insensitive, of course. If any of the above strings occur anywhere in the type declaration, then the datatype of the column is text. Notice that the type "VARCHAR" contains "CHAR" as a substring so it is considered text.

If none of the strings above occur anywhere in the type declaration, then the datatype is numeric. Note in particular that the datatype for columns with an empty type declaration is numeric.

5.0 Examples

Consider the following two command sequences:

CREATE TABLE t1(a INTEGER UNIQUE);        CREATE TABLE t2(b TEXT UNIQUE);
INSERT INTO t1 VALUES('0');               INSERT INTO t2 VALUES(0);
INSERT INTO t1 VALUES('0.0');             INSERT INTO t2 VALUES(0.0);

In the sequence on the left, the second insert will fail. In this case, the strings '0' and '0.0' are treated as numbers since they are being inserted into a numeric column but 0==0.0 which violates the uniqueness constraint. However, the second insert in the right-hand sequence works. In this case, the constants 0 and 0.0 are treated a strings which means that they are distinct.

SQLite always converts numbers into double-precision (64-bit) floats for comparison purposes. This means that a long sequence of digits that differ only in insignificant digits will compare equal if they are in a numeric column but will compare unequal if they are in a text column. We have:

INSERT INTO t1                            INSERT INTO t2
   VALUES('12345678901234567890');           VALUES(12345678901234567890);
INSERT INTO t1                            INSERT INTO t2
   VALUES('12345678901234567891');           VALUES(12345678901234567891);

As before, the second insert on the left will fail because the comparison will convert both strings into floating-point number first and the only difference in the strings is in the 20-th digit which exceeds the resolution of a 64-bit float. In contrast, the second insert on the right will work because in that case, the numbers being inserted are strings and are compared using memcmp().

Numeric and text types make a difference for the DISTINCT keyword too:

CREATE TABLE t3(a INTEGER);               CREATE TABLE t4(b TEXT);
INSERT INTO t3 VALUES('0');               INSERT INTO t4 VALUES(0);
INSERT INTO t3 VALUES('0.0');             INSERT INTO t4 VALUES(0.0);
SELECT DISTINCT * FROM t3;                SELECT DISTINCT * FROM t4;

The SELECT statement on the left returns a single row since '0' and '0.0' are treated as numbers and are therefore indistinct. But the SELECT statement on the right returns two rows since 0 and 0.0 are treated a strings which are different.


SQLite Developer Links

Choose any three.
About Sitemap Documentation Download License News Support

Developer Resources

  • Report A Bug
  • Timeline
  • Browse Historical Source Files
  • Documentation Source Text


Distinctive Features Of SQLite

This page highlights some of the characteristics of SQLite that are unusual and which make SQLite different from many other SQL database engines.

Zero-Configuration

SQLite does not need to be "installed" before it is used. There is no "setup" procedure. There is no server process that needs to be started, stopped, or configured. There is no need for an administrator to create a new database instance or assign access permissions to users. SQLite uses no configuration files. Nothing needs to be done to tell the system that SQLite is running. No actions are required to recover after a system crash or power failure. There is nothing to troubleshoot.

SQLite just works.

Other more familiar database engines run great once you get them going. But doing the initial installation and configuration can be intimidatingly complex.

Serverless

Most SQL database engines are implemented as a separate server process. Programs that want to access the database communicate with the server using some kind of interprocess communication (typically TCP/IP) to send requests to the server and to receive back results. SQLite does not work this way. With SQLite, the process that wants to access the database reads and writes directly from the database files on disk. There is no intermediary server process.

There are advantages and disadvantages to being serverless. The main advantage is that there is no separate server process to install, setup, configure, initialize, manage, and troubleshoot. This is one reason why SQLite is a "zero-configuration" database engine. Programs that use SQLite require no administrative support for setting up the database engine before they are run. Any program that is able to access the disk is able to use an SQLite database.

On the other hand, a database engine that uses a server can provide better protection from bugs in the client application - stray pointers in a client cannot corrupt memory on the server. And because a server is a single persistent process, it is able control database access with more precision, allowing for finer grain locking and better concurrency.

Most SQL database engines are client/server based. Of those that are serverless, SQLite is the only one that this author knows of that allows multiple applications to access the same database at the same time.

Single Database File

An SQLite database is a single ordinary disk file that can be located anywhere in the directory hierarchy. If SQLite can read the disk file then it can read anything in the database. If the disk file and its directory are writable, then SQLite can change anything in the database. Database files can easily be copied onto a USB memory stick or emailed for sharing.

Other SQL database engines tend to store data as a large collection of files. Often these files are in a standard location that only the database engine itself can access. This makes the data more secure, but also makes it harder to access. Some SQL database engines provide the option of writing directly to disk and bypassing the filesystem all together. This provides added performance, but at the cost of considerable setup and maintenance complexity.

Stable Cross-Platform Database File

The SQLite file format is cross-platform. A database file written on one machine can be copied to and used on a different machine with a different architecture. Big-endian or little-endian, 32-bit or 64-bit does not matter. All machines use the same file format. Furthermore, the developers have pledged to keep the file format stable and backwards compatible, so newer versions of SQLite can read and write older database files.

Most other SQL database engines require you to dump and restore the database when moving from one platform to another and often when upgrading to a newer version of the software.

Compact

When optimized for size, the whole SQLite library with everything enabled is [footprint | less than 350KiB in size] (as measured on an ix86 using the "size" utility from the GNU compiler suite.) Unneeded features can be disabled at compile-time to further reduce the size of the library to under 190KiB if desired.

Most other SQL database engines are much larger than this. IBM boasts that its recently released CloudScape database engine is "only" a 2MiB jar file - an order of magnitude larger than SQLite even after it is compressed! Firebird boasts that its client-side library is only 350KiB. That's as big as SQLite and does not even contain the database engine. The Berkeley DB library from Oracle is 450KiB and it omits SQL support, providing the programmer with only simple key/value pairs.

Manifest typing

Most SQL database engines use static typing. A datatype is associated with each column in a table and only values of that particular datatype are allowed to be stored in that column. SQLite relaxes this restriction by using manifest typing. In manifest typing, the datatype is a property of the value itself, not of the column in which the value is stored. SQLite thus allows the user to store any value of any datatype into any column regardless of the declared type of that column. (There are some exceptions to this rule: An INTEGER PRIMARY KEY column may only store integers. And SQLite attempts to coerce values into the declared datatype of the column when it can.)

As far as we can tell, the SQL language specification allows the use of manifest typing. Nevertheless, most other SQL database engines are statically typed and so some people feel that the use of manifest typing is a bug in SQLite. But the authors of SQLite feel very strongly that this is a feature. The use of manifest typing in SQLite is a deliberate design decision which has proven in practice to make SQLite more reliable and easier to use, especially when used in combination with dynamically typed programming languages such as Tcl and Python.

Variable-length records

Most other SQL database engines allocated a fixed amount of disk space for each row in most tables. They play special tricks for handling BLOBs and CLOBs which can be of wildly varying length. But for most tables, if you declare a column to be a VARCHAR(100) then the database engine will allocate 100 bytes of disk space regardless of how much information you actually store in that column.

SQLite, in contrast, use only the amount of disk space actually needed to store the information in a row. If you store a single character in a VARCHAR(100) column, then only a single byte of disk space is consumed. (Actually two bytes - there is some overhead at the beginning of each column to record its datatype and length.)

The use of variable-length records by SQLite has a number of advantages. It results in smaller database files, obviously. It also makes the database run faster, since there is less information to move to and from disk. And, the use of variable-length records makes it possible for SQLite to employ manifest typing instead of static typing.

Readable source code

The source code to SQLite is designed to be readable and accessible to the average programmer. All procedures and data structures and many automatic variables are carefully commented with useful information about what they do. Boilerplate commenting is omitted.

SQL statements compile into virtual machine code

Every SQL database engine compiles each SQL statement into some kind of internal data structure which is then used to carry out the work of the statement. But in most SQL engines that internal data structure is a complex web of interlinked structures and objects. In SQLite, the compiled form of statements is a short program in a machine-language like representation. Users of the database can view this virtual machine language by prepending the EXPLAIN keyword to a query.

The use of a virtual machine in SQLite has been a great benefit to the library's development. The virtual machine provides a crisp, well-defined junction between the front-end of SQLite (the part that parses SQL statements and generates virtual machine code) and the back-end (the part that executes the virtual machine code and computes a result.) The virtual machine allows the developers to see clearly and in an easily readable form what SQLite is trying to do with each statement it compiles, which is a tremendous help in debugging. Depending on how it is compiled, SQLite also has the capability of tracing the execution of the virtual machine - printing each virtual machine instruction and its result as it executes.

Public domain

The source code for SQLite is in the public domain. No claim of copyright is made on any part of the core source code. (The documentation and test code is a different matter - some sections of documentation and test logic are governed by open-source licenses.) All contributors to the SQLite core software have signed affidavits specifically disavowing any copyright interest in the code. This means that anybody is able to legally do anything they want with the SQLite source code.

There are other SQL database engines with liberal licenses that allow the code to be broadly and freely used. But those other engines are still governed by copyright law. SQLite is different in that copyright law simply does not apply.

The source code files for other SQL database engines typically begin with a comment describing your license rights to view and copy that file. The SQLite source code contains no license since it is not governed by copyright. Instead of a license, the SQLite source code offers a blessing:

May you do good and not evil
May you find forgiveness for yourself and forgive others
May you share freely, never taking more than you give.

SQL language extensions

SQLite provides a number of enhancements to the SQL language not normally found in other database engines. The EXPLAIN keyword and manifest typing have already been mentioned above. SQLite also provides statements such as REPLACE and the ON CONFLICT clause that allow for added control over the resolution of constraint conflicts. SQLite supports ATTACH and DETACH commands that allow multiple independent databases to be used together in the same query. And SQLite defines APIs that allows the user to add new SQL functions and collating sequences.


Backlink Crossreference

Choose any three.
About Sitemap Documentation Download License News Support
  • 34to35 - 35to36.html oldnews.html
  • 35to36 - changes.html#version_3_6_1 oldnews.html releaselog/3_6_0.html
  • affinities - lang_expr.html#castexpr
  • affinity - faq.html#q3 fileformat2.html#serialtype foreignkeys.html#parentchild fts3.html#section_1_4 lang_createtable.html#rowid lang_createtable.html#tablecoldef lang_select.html#fromclause optoverview.html#like_opt
  • aggfunc - lang.html lang_corefunc.html lang_expr.html#booleanexpr
  • ALTER - foreignkeys.html
  • ALTER TABLE - changes.html#version_3_7_9 compile.html#omit_altertable fileformat2.html#filesize fileformat2.html#serialtype foreignkeys.html#fk_actions lang.html lang_analyze.html lang_createtrigger.html lang_naming.html releaselog/3_7_9.html vtab.html
  • alter-table-stmt - lang_altertable.html
  • amalgamation - compile.html#enable_fts3 compile.html#enable_fts4 compile.html#enable_update_delete_limit compile.html#omitfeatures faq.html#q23 howtocompile.html malloc.html#memsysx privatebranch.html rtree.html selfcontained.html sqlite.html
  • amalgamation tarball - howtocompile.html#cli
  • ANALYZE - changes.html#version_3_6_18 changes.html#version_3_7_3 changes.html#version_3_7_6 compile.html#enable_stat2 compile.html#enable_stat3 compile.html#omit_analyze eqp.html lang.html oldnews.html optoverview.html#autoindex optoverview.html#manctrl optoverview.html#multi_index optoverview.html#rangequery optoverview.html#table_order queryplanner.html#searching releaselog/3_6_18.html releaselog/3_7_3.html releaselog/3_7_6.html
  • analyze-stmt - lang_analyze.html
  • application file-format - wal.html
  • application-defined SQL function - lang_expr.html#regexp
  • application-defined SQL functions - c3ref/context.html c3ref/stmt_readonly.html c3ref/value.html capi3ref.html#sqlite3_context capi3ref.html#sqlite3_stmt_readonly capi3ref.html#sqlite3_value
  • asynchronous I/O backend - oldnews.html
  • asynchronous VFS - changes.html#version_3_6_14 releaselog/3_6_14.html
  • Atomic Commit - lockingv3.html#how_to_corrupt
  • atomic commit - wal.html
  • ATTACH - c3ref/backup_finish.html#sqlite3backupinit c3ref/blob_open.html c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/c_dbstatus_options.html#sqlitedbstatusschemaused c3ref/c_limit_attached.html#sqlitelimitattached c3ref/file_control.html c3ref/stmt_readonly.html c3ref/wal_hook.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_stmt_readonly capi3ref.html#sqlite3_wal_hook capi3ref.html#sqlite3backupinit capi3ref.html#sqliteconfiguri capi3ref.html#sqlitedbstatusschemaused capi3ref.html#sqlitelimitattached changes.html#version_3_5_6 cintro.html compile.html#omit_attach inmemorydb.html inmemorydb.html#temp_db lang_detach.html lang_naming.html lockingv3.html#rollback pragma.html#pragma_encoding pragma.html#pragma_locking_mode pragma.html#pragma_secure_delete pragma.html#syntax releaselog/3_5_6.html shortnames.html tclsqlite.html#varsubst tempfiles.html#masterjrnl tempfiles.html#tempdb uri.html vfs.html vtab.html#xcreate wal.html
  • ATTACH DATABASE - lang.html lang_createtable.html
  • attach-stmt - lang_attach.html
  • auto_vacuum - compile.html#default_autovacuum compile.html#omit_autovacuum fileformat2.html#filesize fileformat2.html#ovflpgs lang_vacuum.html
  • autocommit mode - c3ref/blob_close.html capi3ref.html#sqlite3_blob_close foreignkeys.html#fk_enable
  • AUTOINCREMENT - c3ref/table_column_metadata.html capi3ref.html#sqlite3_table_column_metadata compile.html#omit_autoincrement faq.html#q1
  • Automatic indexing - pragma.html#pragma_automatic_index
  • automatic indexing - compile.html#omit_automatic_index eqp.html pragma.html#pragma_automatic_index
  • automatic_index pragma - optoverview.html#autoindex
  • backup API - howtocorrupt.html wal.html
  • BEGIN - asyncvfs.html c3ref/get_autocommit.html c3ref/stmt_readonly.html capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_stmt_readonly faq.html#q19 foreignkeys.html#fk_enable lang_savepoint.html pragma.html#pragma_foreign_keys
  • BEGIN TRANSACTION - lang.html
  • begin-stmt - lang_transaction.html
  • BINARY - lang_corefunc.html#replace lang_createtable.html#tablecoldef lang_select.html#orderby
  • BLOB handle - c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html capi3ref.html#sqlite3_blob_bytes capi3ref.html#sqlite3_blob_close capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write
  • BLOB handles - c3ref/close.html capi3ref.html#sqlite3_close
  • books about SQLite - doclist.html keyword_index.html sitemap.html#pindex
  • boolean expression - lang_delete.html lang_select.html#fromclause lang_select.html#resultset lang_select.html#whereclause lang_update.html
  • bound parameter - oldnews.html
  • bound parameters - changes.html#version_3_6_21 releaselog/3_6_21.html
  • building the amalgamation - howtocompile.html
  • built-in memory allocators - c3ref/mem_methods.html capi3ref.html#sqlite3_mem_methods
  • cache_size - changes.html#version_3_7_6_3 news.html pragma.html#pragma_default_cache_size releaselog/3_7_6_3.html
  • cache_size pragma - malloc.html#nofrag
  • capi3ref - cintro.html quickstart.html
  • capi3ref_funclist - cintro.html
  • case_sensitive_like - optoverview.html#like_opt
  • case_sensitive_like pragma - compile.html#case_sensitive_like lang_expr.html#like
  • CAST expression - datatype3.html#affinity lang_createtable.html#ckconst lang_expr.html#booleanexpr rtree.html#customquery
  • categorical listing of SQLite documents - doclist.html keyword_index.html sitemap.html#pindex
  • change counter - fileformat2.html#filesize fileformat2.html#validfor
  • changes SQL function - c3ref/changes.html capi3ref.html#sqlite3_changes
  • CHECK constraint - lang_altertable.html
  • checkpoint - c3ref/wal_autocheckpoint.html c3ref/wal_hook.html capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_hook fileformat2.html#walcksm howtocorrupt.html#delhotjrnl news.html pragma.html#pragma_checkpoint_fullfsync pragma.html#pragma_synchronous
  • checkpoint_fullfsync - pragma.html#pragma_fullfsync pragma.html#pragma_synchronous
  • checkpointed - c3ref/wal_checkpoint.html capi3ref.html#sqlite3_wal_checkpoint
  • checkpointing - compile.html#default_wal_autocheckpoint pragma.html#pragma_wal_autocheckpoint wal.html
  • child key - c3ref/blob_open.html capi3ref.html#sqlite3_blob_open
  • cintro - c3ref/intro.html capi3ref.html quickstart.html
  • CLI - changes.html#version_3_6_11 changes.html#version_3_6_12 howtocompile.html#cli releaselog/3_6_11.html releaselog/3_6_12.html
  • coalesce - changes.html#version_3_6_21 lang_corefunc.html#ifnull releaselog/3_6_21.html
  • COLLATE operator - datatype3.html#collation lang_select.html#orderby
  • collating function - fileformat2.html#serialtype
  • collating sequence - foreignkeys.html#parentchild lang_createtable.html#tablecoldef lang_expr.html#collateop optoverview.html#like_opt
  • collation - c3ref/create_collation.html capi3ref.html#sqlite3_create_collation lang_select.html#fromclause lang_select.html#resultset
  • column access functions - c3ref/step.html c3ref/value_blob.html capi3ref.html#sqlite3_step capi3ref.html#sqlite3_value_blob
  • column affinity - lang_expr.html#castexpr
  • column definition - datatype3.html#collation fileformat2.html#serialtype lang_expr.html#collateop
  • column definitions - lang_createvtab.html vtab.html
  • column-constraint - lang_createtable.html lang_createtable.html#tablecoldef
  • column-def - lang_altertable.html lang_createtable.html lang_createtable.html#tablecoldef
  • Command Line Interface - changes.html#version_3_6_21 changes.html#version_3_6_23 compile.html#enable_iotrace oldnews.html releaselog/3_6_21.html releaselog/3_6_23.html
  • command-line shell - changes.html#version_3_7_5 releaselog/3_7_5.html wal.html#fast
  • comment - lang.html
  • comment-syntax - lang_comment.html
  • COMMIT - asyncvfs.html c3ref/commit_hook.html c3ref/get_autocommit.html c3ref/step.html c3ref/stmt_readonly.html capi3ref.html#sqlite3_commit_hook capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_step capi3ref.html#sqlite3_stmt_readonly changes.html#version_3_6_5 faq.html#q19 foreignkeys.html#fk_enable lang.html lang_attach.html lang_savepoint.html news.html releaselog/3_6_5.html wal.html wal.html#fast
  • commit-stmt - lang_transaction.html
  • comparison expressions - lang_select.html#orderby
  • compile fts - fts3.html#fts4aux fts3.html#termprefix
  • compile-time options - footprint.html#relfootprint howtocompile.html#amal howtocompile.html#cli lang_keywords.html pragma.html#pragma_compile_options privatebranch.html
  • compile_options pragma - c3ref/compileoption_get.html capi3ref.html#sqlite3_compileoption_get changes.html#version_3_6_23 compile.html#omit_compileoption_diags lang_corefunc.html#sqlite_compileoption_get oldnews.html releaselog/3_6_23.html
  • compound query - eqp.html
  • compound-operator - lang_select.html
  • compressed FTS4 content - changes.html#version_3_7_6 releaselog/3_7_6.html
  • configuration option - c3ref/config.html capi3ref.html#sqlite3_config
  • conflict clause - lang_createtable.html#ckconst
  • conflict-clause - lang_conflict.html lang_createtable.html#ckconst
  • constraints - lang_createtable.html#tablecoldef
  • corefunc - lang.html lang_expr.html#booleanexpr
  • count_changes pragma - c3ref/changes.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes changes.html#version_3_6_5 changes.html#version_3_7_9 lang_createtrigger.html#instead_of_trigger lang_delete.html#truncateopt releaselog/3_6_5.html releaselog/3_7_9.html
  • covering index - eqp.html queryplanner.html#srchsortcovidx
  • CREATE INDEX - changes.html#version_3_7_8 compile.html#omit_merge_sort fileformat2.html#serialtype foreignkeys.html#fk_actions lang.html lang_createtable.html#constraints lang_dropindex.html releaselog/3_7_8.html vtab.html
  • CREATE TABLE - compile.html#default_temp_cache_size eqp.html fileformat2.html#serialtype foreignkeys.html foreignkeys.html#fk_actions foreignkeys.html#fk_enable lang.html lang_altertable.html lang_createindex.html lang_createvtab.html lang_droptable.html lang_expr.html#in_op vtab.html vtab.html#xcreate
  • CREATE TRIGGER - c3ref/c_dbconfig_enable_fkey.html c3ref/changes.html c3ref/total_changes.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes compile.html#omit_trigger faq.html#q22 fileformat2.html#serialtype foreignkeys.html#fk_actions lang.html lang_conflict.html lang_createtable.html lang_delete.html lang_droptrigger.html lang_insert.html lang_update.html
  • CREATE VIEW - compile.html#omit_view fileformat2.html#serialtype lang.html lang_dropview.html
  • CREATE VIRTUAL TABLE - fileformat2.html#serialtype fts3.html#fts4 lang.html vtab.html vtab.html#xcreate
  • create-index-stmt - lang_createindex.html
  • create-table-stmt - lang_createtable.html
  • create-trigger-stmt - lang_createtrigger.html
  • create-view-stmt - lang_createview.html
  • create-virtual-table-stmt - lang_createvtab.html
  • custom builds - c3ref/initialize.html capi3ref.html#sqlite3_initialize
  • custom r-tree queries - changes.html#version_3_7_3 news.html releaselog/3_7_3.html
  • database connection - 35to36.html backup.html c3ref/auto_extension.html c3ref/backup_finish.html#sqlite3backupinit c3ref/backup_finish.html#sqlite3backuppagecount c3ref/backup_finish.html#sqlite3backupstep c3ref/blob_open.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_config_getmalloc.html#sqliteconfiglookaside c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/c_dbconfig_enable_fkey.html c3ref/changes.html c3ref/close.html c3ref/collation_needed.html c3ref/commit_hook.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/interrupt.html c3ref/last_insert_rowid.html c3ref/limit.html c3ref/module.html c3ref/next_stmt.html c3ref/open.html c3ref/prepare.html c3ref/progress_handler.html c3ref/set_authorizer.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/total_changes.html c3ref/update_hook.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_busy_handler capi3ref.html#sqlite3_busy_timeout capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_close capi3ref.html#sqlite3_collation_needed capi3ref.html#sqlite3_commit_hook capi3ref.html#sqlite3_context_db_handle capi3ref.html#sqlite3_create_collation capi3ref.html#sqlite3_create_function capi3ref.html#sqlite3_create_module capi3ref.html#sqlite3_db_config capi3ref.html#sqlite3_db_handle capi3ref.html#sqlite3_db_mutex capi3ref.html#sqlite3_db_status capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_errcode capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_interrupt capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_limit capi3ref.html#sqlite3_module capi3ref.html#sqlite3_next_stmt capi3ref.html#sqlite3_open capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_progress_handler capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_table_column_metadata capi3ref.html#sqlite3_temp_directory capi3ref.html#sqlite3_total_changes capi3ref.html#sqlite3_update_hook capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_checkpoint capi3ref.html#sqlite3backupinit capi3ref.html#sqlite3backuppagecount capi3ref.html#sqlite3backupstep capi3ref.html#sqliteconfiglookaside capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigserialized changes.html#version_3_5_8 changes.html#version_3_6_1 cintro.html compile.html#threadsafe custombuild.html fileformat2.html#serialtype foreignkeys.html#fk_enable lang_attach.html lang_transaction.html malloc.html malloc.html#lookaside malloc.html#memstatus malloc.html#nofrag oldnews.html pragma.html#pragma_journal_mode releaselog/3_5_8.html releaselog/3_6_1.html requirements.html tempfiles.html#masterjrnl tempfiles.html#tempdb unlock_notify.html vtab.html vtab.html#xcreate
  • database connections - c3ref/backup_finish.html#sqlite3backupinit c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/initialize.html capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3backupinit capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigserialized cintro.html compile.html#threadsafe compile.html#yystackdepth custombuild.html lang_expr.html#varparam malloc.html malloc.html#lookaside malloc.html#nofrag vfs.html
  • database corruption caused by inconsistent use of 83 filenames - howtocorrupt.html#delhotjrnl shortnames.html
  • database header - wal.html#bkwrds
  • datatype - faq.html#q3 faq.html#q4 lang_corefunc.html#typeof lang_expr.html#collateop
  • Date And Time Functions - datatype3.html#datetime
  • datefunc - lang.html lang_corefunc.html lang_expr.html#booleanexpr
  • debugging memory allocator - compile.html#memdebug compile.html#zero_malloc
  • default memory allocator - compile.html#zero_malloc malloc.html#memsysx
  • default_cache_size - pragma.html#pragma_cache_size
  • default_cache_size pragma - fileformat2.html#filesize
  • DELETE - c3ref/blob_open.html c3ref/changes.html c3ref/set_authorizer.html c3ref/total_changes.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_total_changes changes.html#version_3_6_4 compile.html#enable_update_delete_limit compile.html#omit_truncate_optimization foreignkeys.html#fk_actions fts3.html#fts4 lang.html lang_analyze.html lang_createtrigger.html lang_createview.html lang_droptable.html lang_indexedby.html pragma.html#pragma_count_changes pragma.html#pragma_writable_schema releaselog/3_6_4.html rtree.html vtab.html
  • delete-stmt - lang_delete.html
  • delete-stmt-limited - lang_delete.html
  • deleting a hot journal - shortnames.html#db83corrupt
  • deprecated - c3ref/aggregate_count.html c3ref/constlist.html c3ref/funclist.html c3ref/objlist.html capi3ref.html capi3ref.html#sqlite3_aggregate_count
  • DETACH - c3ref/stmt_readonly.html capi3ref.html#sqlite3_stmt_readonly compile.html#omit_attach tempfiles.html#tempdb
  • DETACH DATABASE - lang.html
  • detach-stmt - lang_detach.html
  • DISTINCT - lang_select.html
  • doclist - keyword_index.html sitemap.html#pindex
  • download page - howtocompile.html#amal howtocompile.html#cli howtocompile.html#tcl
  • DROP INDEX - lang.html lang_createindex.html lang_naming.html
  • DROP TABLE - c3ref/changes.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes changes.html#version_3_7_9 foreignkeys.html foreignkeys.html#fk_actions fts3.html#fts4 lang.html lang_analyze.html lang_createtable.html lang_createtrigger.html lang_createvtab.html lang_naming.html releaselog/3_7_9.html rtree.html vtab.html vtab.html#sqlite3_module.xDestroy
  • DROP TRIGGER - compile.html#omit_trigger lang.html lang_createtrigger.html lang_naming.html
  • DROP VIEW - compile.html#omit_view lang.html lang_createview.html lang_naming.html
  • drop-index-stmt - lang_dropindex.html
  • drop-table-stmt - lang_droptable.html
  • drop-trigger-stmt - lang_droptrigger.html
  • drop-view-stmt - lang_dropview.html
  • dynamic typing - faq.html#q2 faq.html#q3 lang_createtable.html#tablecoldef
  • encoding - lang_expr.html#castexpr
  • enhanced query syntax - fts3.html#section_2
  • error code - 35to36.html backup.html c3ref/auto_extension.html c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupstep c3ref/bind_blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/config.html c3ref/db_status.html c3ref/enable_shared_cache.html c3ref/finalize.html c3ref/initialize.html c3ref/open.html c3ref/prepare.html c3ref/reset.html c3ref/status.html c3ref/table_column_metadata.html capi3ref.html#SQLITE_CONFIG_GETMALLOC capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3_config capi3ref.html#sqlite3_db_status capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_finalize capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3_open capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_status capi3ref.html#sqlite3_table_column_metadata capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupstep vtab.html#xcolumn vtab.html#xfilter vtab.html#xnext vtab.html#xrename vtab.html#xrowid vtab.html#xupdate
  • error codes - c3ref/prepare.html c3ref/step.html capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_step
  • EXCLUSIVE - lang_transaction.html
  • experimental - c3ref/constlist.html c3ref/funclist.html c3ref/objlist.html capi3ref.html
  • experimental memory allocators - changes.html#version_3_6_5 releaselog/3_6_5.html
  • EXPLAIN - compile.html#omit_explain eqp.html lang.html opcode.html optoverview.html#or_opt
  • EXPLAIN QUERY PLAN - changes.html#version_3_7_4 news.html releaselog/3_7_4.html
  • explain query plan - lang_explain.html
  • expr - lang_expr.html
  • expression - lang.html
  • expression affinity - lang_createtable.html
  • extended error code - c3ref/blob_read.html c3ref/blob_write.html c3ref/finalize.html capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3_finalize
  • extended error codes - c3ref/prepare.html capi3ref.html#sqlite3_prepare unlock_notify.html
  • extended result code - c3ref/c_config_getmalloc.html#sqliteconfiglog c3ref/errcode.html capi3ref.html#sqlite3_errcode capi3ref.html#sqliteconfiglog
  • extended result codes - c3ref/extended_result_codes.html c3ref/step.html capi3ref.html#sqlite3_extended_result_codes capi3ref.html#sqlite3_step
  • file format - news.html onefile.html version3.html
  • flattening optimization - eqp.html
  • footprint - features.html
  • foreign key actions - c3ref/changes.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes compile.html#omit_trigger foreignkeys.html#fk_actions lang_droptable.html pragma.html#pragma_count_changes
  • foreign key constraint - compile.html#omit_foreign_key lang_createtable.html#rowid
  • FOREIGN KEY constraints - lang_conflict.html
  • foreign key constraints - c3ref/blob_open.html c3ref/c_dbconfig_enable_fkey.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_blob_open changes.html#version_3_6_19 compile.html#default_foreign_keys compile.html#omit_trigger faq.html#q22 lang_altertable.html lang_droptable.html oldnews.html pragma.html#pragma_foreign_keys releaselog/3_6_19.html
  • foreign key constraints are enabled - foreignkeys.html#fk_actions
  • foreign-key-clause - lang_altertable.html lang_createtable.html
  • foreign_keys pragma - changes.html#version_3_6_19 compile.html#default_foreign_keys lang_altertable.html oldnews.html releaselog/3_6_19.html
  • free-page list - changes.html#version_3_7_2 news.html releaselog/3_7_2.html
  • freelist - atomiccommit.html#freelistjrnl pragma.html#pragma_auto_vacuum pragma.html#pragma_incremental_vacuum
  • FROM clause - lang_select.html
  • FTS auxiliary functions - fts3.html#hiddencol fts3.html#section_1_4 vtab.html#hiddencol
  • FTS hidden column - fts3.html#matchinfo fts3.html#snippet vtab.html#hiddencol
  • FTS MATCH - fts3.html#fts4 fts3.html#hiddencol fts3.html#section_1_4 vtab.html#hiddencol
  • FTS shadow tables - fts3.html#fts4
  • FTS3 - amalgamation.html changes.html#version_3_6_22 changes.html#version_3_6_23 changes.html#version_3_6_23_1 changes.html#version_3_7_7 news.html oldnews.html releaselog/3_6_22.html releaselog/3_6_23.html releaselog/3_6_23_1.html releaselog/3_7_7.html vtab.html#hiddencol
  • fts3 - changes.html#version_3_6_21 releaselog/3_6_21.html
  • FTS4 - changes.html#version_3_7_4 changes.html#version_3_7_9 news.html releaselog/3_7_4.html releaselog/3_7_9.html
  • fts4 compress option - fts3.html#*matchinfo_fts3
  • FTS4 options - fts3.html#fts4
  • FTS4 order option - changes.html#version_3_7_7 news.html releaselog/3_7_7.html
  • FTS4 prefix option - changes.html#version_3_7_7 news.html releaselog/3_7_7.html
  • fts4 prefix option - fts3.html#fts4order
  • fts4aux - changes.html#version_3_7_6 releaselog/3_7_6.html
  • full-text search - news.html vtab.html
  • full_column_names - pragma.html#pragma_full_column_names pragma.html#pragma_short_column_names
  • fullfsync - pragma.html#pragma_checkpoint_fullfsync pragma.html#pragma_synchronous
  • GLOB - c3ref/c_limit_attached.html#sqlitelimitlikepatternlength c3ref/prepare.html capi3ref.html#sqlite3_prepare capi3ref.html#sqlitelimitlikepatternlength compile.html#omit_like_optimization lang_corefunc.html#glob limits.html#max_like_pattern_length news.html optoverview.html#like_opt vfs.html vtab.html#xfindfunction
  • glob - lang_expr.html#glob
  • GROUP BY - lang_select.html
  • group_concat - changes.html#version_3_6_14_1 releaselog/3_6_14_1.html
  • hex - lang_corefunc.html#randomblob
  • hidden column - fts3.html#hiddencol
  • host parameters - c3ref/stmt.html capi3ref.html#sqlite3_stmt
  • hot journal - wal.html#readonly
  • How To Corrupt Your Database Files - atomiccommit.html#sect_9_0
  • http://clang-analyzer.llvm.org/ - testing.html#staticanalysis
  • http://code.google.com/android/ - famous.html
  • http://code.google.com/apis/gears/api_database.html - famous.html
  • http://community.intuit.com/posts/database-error-sqlite-error-code1 - famous.html
  • http://desktop.gooogle.com/mac/legal.html - famous.html
  • http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/open.1.html - uri.html
  • http://docs.python.org/lib/module-sqlite3.html - famous.html
  • http://en.wikipedia.org/wiki/ACID - about.html transactional.html
  • http://en.wikipedia.org/wiki/Charlotte,_North_Carolina - crew.html
  • http://en.wikipedia.org/wiki/Coordinated_Universal_Time - lang_datefunc.html
  • http://en.wikipedia.org/wiki/Endianness - about.html onefile.html
  • http://en.wikipedia.org/wiki/Fuzz_testing - testing.html#fuzztesting
  • http://en.wikipedia.org/wiki/Gregorian_calendar - lang_datefunc.html
  • http://en.wikipedia.org/wiki/ISO_8601 - lang_datefunc.html
  • http://en.wikipedia.org/wiki/Julian_day - lang_datefunc.html
  • http://en.wikipedia.org/wiki/Modified_Condition/Decision_Coverage - testing.html#mcdc
  • http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar - lang_datefunc.html
  • http://en.wikipedia.org/wiki/Public_Domain - copyright.html
  • http://en.wikipedia.org/wiki/R-tree - rtree.html
  • http://en.wikipedia.org/wiki/Serializability - transactional.html
  • http://en.wikipedia.org/wiki/Unix_time - lang_datefunc.html
  • http://en.wikipedia.org/wiki/UUID - changes.html#version_3_3_13 releaselog/3_3_13.html
  • http://forums.mcafeehelp.com/showthread.php?t=173519 - famous.html
  • http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575 - changes.html#version_3_4_2 releaselog/3_4_2.html
  • http://gcc.gnu.org/onlinedocs/gcc/Gcov.html - testing.html#coverage th3.html
  • http://labs.adobe.com/technologies/air/ - famous.html
  • http://man.he.net/man3/fopen - about.html whentouse.html whentouse.html#appfileformat
  • http://man.he.net/man3/fread - whentouse.html#appfileformat
  • http://man.he.net/man3/fwrite - whentouse.html#appfileformat
  • http://marc.info/?l - support.html#mailinglists
  • http://news.gmane.org/gmane.comp.db.sqlite.general - support.html#mailinglists
  • http://opengroup.org/onlinepubs/007908799/xsh/strftime.html - lang_datefunc.html
  • http://osdir.com/Article6677.phtml - oldnews.html
  • http://System.Data.SQLite.org/ - news.html
  • http://tools.ietf.org/html/rfc3986 - uri.html
  • http://turbotax.intuit.com/ - famous.html
  • http://valgrind.org - faq.html#q17
  • http://valgrind.org/ - testing.html#valgrind
  • http://wiki.tcl.tk/21708 - faq.html#q25
  • http://wiki.tcl.tk/2364 - howtocompile.html#tcl
  • http://wiki.tcl.tk/2541 - howtocompile.html#tcl
  • http://wiki.tcl.tk/9830 - howtocompile.html#tcl
  • http://windows.microsoft.com/en-US/internet-explorer/products/ie/home - uri.html
  • http://www.adobe.com/ - famous.html
  • http://www.adobe.com/products/acrobat/readstep2.html - famous.html
  • http://www.adobe.com/products/photoshoplightroom/ - famous.html
  • http://www.airbus.com/ - famous.html
  • http://www.airbus.com/en/aircraftfamilies/a350 - famous.html
  • http://www.apple.com/ - famous.html
  • http://www.apple.com/aperture/ - famous.html
  • http://www.apple.com/iphone/ - famous.html
  • http://www.apple.com/ipodtouch/ - famous.html
  • http://www.apple.com/itunes/ - famous.html
  • http://www.apple.com/macosx/features/mail.html - famous.html
  • http://www.apple.com/macosx/features/safari.html - famous.html
  • http://www.apple.com/safari/ - uri.html
  • http://www.apress.com - oldnews.html
  • http://www.apress.com/book/bookDisplay.html?bID=10130 - oldnews.html
  • http://www.baymoon.com/~tg2/ - rtree.html
  • http://www.bloomberg.com/ - oldnews.html
  • http://www.cygwin.com/ - howtocompile.html#amal
  • http://www.devio.us/ - news.html
  • http://www.dropbox.com/ - famous.html
  • http://www.duke.edu/ - crew.html
  • http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-1.pdf - faq.html#q6
  • http://www.fossil-scm.org - privatebranch.html
  • http://www.fossil-scm.org/ - changes.html#version_3_6_18 download.html#encoding oldnews.html privatebranch.html releaselog/3_6_18.html
  • http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki - privatebranch.html
  • http://www.gatech.edu/ - crew.html
  • http://www.ge.com/ - famous.html
  • http://www.git-scm.org/ - privatebranch.html
  • http://www.google.com/ - famous.html
  • http://www.google.com/chrome - famous.html
  • http://www.google.com/chrome/ - uri.html
  • http://www.hwaci.com/ - consortium.html crew.html
  • http://www.hwaci.com/sw/sqlite/cerod.html - support.html#prosupport
  • http://www.hwaci.com/sw/sqlite/prosupport.html - support.html#prosupport
  • http://www.hwaci.com/sw/sqlite/see.html - support.html#prosupport
  • http://www.icu-project.org/ - changes.html#version_3_4_0 changes.html#version_3_4_1 compile.html#enable_icu releaselog/3_4_0.html releaselog/3_4_1.html
  • http://www.intuit.com/ - famous.html
  • http://www.mail-archive.com/sqlite-users%40sqlite.org/ - support.html#mailinglists
  • http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27326.html - famous.html
  • http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27332.html - famous.html
  • http://www.mail-archive.com/sqlite-users@sqlite.org/msg16931.html - famous.html
  • http://www.mail-archive.com/sqlite-users@sqlite.org/msg19226.html - famous.html
  • http://www.mcafee.com/ - famous.html mostdeployed.html
  • http://www.microsoft.com/ - famous.html
  • http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/start.mspx - uri.html
  • http://www.mikesclutter.com - oldnews.html
  • http://www.mingw.org/ - mingw.html
  • http://www.monotone.ca/ - privatebranch.html
  • http://www.mozilla.com/ - famous.html
  • http://www.mozilla.com/en-US/firefox/new/ - uri.html
  • http://www.mozilla.com/thunderbird/ - famous.html
  • http://www.mozilla.org/ - oldnews.html
  • http://www.opera.com/ - uri.html
  • http://www.oracle.com/database/index.html - about.html whentouse.html
  • http://www.paulgraham.com/ - version3.html
  • http://www.paulgraham.com/acl.html - version3.html
  • http://www.php.net/ - famous.html
  • http://www.postgresql.org/ - changes.html#version_1_0_8
  • http://www.quickbooks.com/ - famous.html
  • http://www.realbasic.com/ - famous.html
  • http://www.selenic.com/mercurial/wiki/ - privatebranch.html
  • http://www.sergeant.org/sqlite_vs_pgsync.html - speed.html
  • http://www.skype.com/ - mostdeployed.html
  • http://www.sqlite.org/src - howtocompile.html#amal privatebranch.html
  • http://www.sqlite.org/src/doc/trunk/src/os_unix.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_demovfs.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_journal.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_multiplex.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_onefile.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_quota.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_vfs.c - vfs.html
  • http://www.sqlite.org/src/doc/trunk/src/test_vfstrace.c - vfs.html
  • http://www.sqlite.org/src/info/25ee812710 - changes.html#version_3_7_7_1 news.html releaselog/3_7_7_1.html
  • http://www.sqlite.org/src/info/2d1a5c67df - news.html
  • http://www.sqlite.org/src/info/31338dca7e - oldnews.html
  • http://www.sqlite.org/src/info/5d863f876e - changes.html#version_3_7_5 releaselog/3_7_5.html
  • http://www.sqlite.org/src/info/80ba201079 - changes.html#version_3_7_4 news.html releaselog/3_7_4.html
  • http://www.sqlite.org/src/info/eb5548a849 - oldnews.html
  • http://www.sqlite.org/src/tktview?name=5d863f876e - news.html
  • http://www.sun.com/software/solaris/ - famous.html
  • http://www.symbian.com/ - famous.html oldnews.html
  • http://www.tcl.tk - quickstart.html tclsqlite.html
  • http://www.tcl.tk/ - lang_expr.html#varparam testing.html#tcl
  • http://www.tcl.tk/cgi-bin/tct/tip/322.html - changes.html#version_3_6_19 releaselog/3_6_19.html
  • http://www.tcl.tk/community/tcl2004/ - oldnews.html
  • http://www.tcl.tk/doc/tea/ - tclsqlite.html
  • http://www.toshiba.com/ - famous.html
  • http://www.w3c.org/TR/NOTE-datetime - lang_datefunc.html
  • https://ttlc.intuit.com/post/show_full/cJf8mIhC4r4jjracfArQzM/when-i-try-to-update-turbotax-i-receive-an-unexpected-error-message - famous.html
  • ifnull - changes.html#version_3_6_21 releaselog/3_6_21.html
  • in-memory database - compile.html#omit_memorydb pragma.html#pragma_journal_mode
  • in-memory databases - pragma.html#pragma_locking_mode pragma.html#pragma_temp_store
  • incremental_vacuum - changes.html#version_3_6_12 changes.html#version_3_7_2 fileformat2.html#filesize fileformat2.html#ovflpgs howtocorrupt.html#delhotjrnl news.html pragma.html#pragma_auto_vacuum releaselog/3_6_12.html releaselog/3_7_2.html
  • INDEXED BY - changes.html#version_3_6_4 lang.html releaselog/3_6_4.html
  • indexed-column - lang_createindex.html
  • indexing - eqp.html
  • INSERT - c3ref/changes.html c3ref/last_insert_rowid.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_total_changes faq.html#q1 faq.html#q19 fts3.html#fts4 lang.html lang_analyze.html lang_createtable.html#constraints lang_createtable.html#tablecoldef lang_createtrigger.html lang_createview.html lang_replace.html pragma.html pragma.html#pragma_count_changes pragma.html#pragma_writable_schema rtree.html vtab.html vtab.html#hiddencol
  • insert-stmt - lang_insert.html
  • INSTEAD OF trigger - c3ref/changes.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes lang_createview.html pragma.html#pragma_count_changes
  • INTEGER PRIMARY KEY - autoinc.html c3ref/last_insert_rowid.html c3ref/table_column_metadata.html capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_table_column_metadata compile.html#omit_autoincrement datatype3.html#storageclasses faq.html#q1 faq.html#q3 fileformat2.html#serialtype fts3.html#section_1_4 lang_createtable.html#constraints lang_vacuum.html queryplanner.html#searching
  • integrity_check - pragma.html#pragma_quick_check testing.html#crashtesting
  • integrity_check pragma - changes.html#version_3_6_23 compile.html#omit_integrity_check howtocorrupt.html#delhotjrnl releaselog/3_6_23.html
  • IS operator - oldnews.html
  • join order - eqp.html
  • join-constraint - lang_select.html lang_select.html#fromclause
  • join-op - lang_select.html lang_select.html#fromclause
  • join-source - lang_select.html
  • join-source syntax diagram - lang_select.html
  • journal_mode - c3ref/wal_hook.html capi3ref.html#sqlite3_wal_hook changes.html#version_3_5_9 lang_attach.html oldnews.html releaselog/3_5_9.html tempfiles.html#tempdb wal.html#fast wal.html#readonly
  • journal_mode pragma - atomiccommit.html#keepcache changes.html#version_3_6_5 compile.html#default_journal_size_limit fileformat2.html#rollbackjournal pragma.html#pragma_wal_autocheckpoint pragma.html#pragma_wal_checkpoint releaselog/3_6_5.html tempfiles.html#rollbackjrnl
  • journal_size_limit pragma - compile.html#default_journal_size_limit
  • keyword index - doclist.html sitemap.html#pindex
  • last_insert_rowid SQL function - c3ref/last_insert_rowid.html capi3ref.html#sqlite3_last_insert_rowid
  • legacy_file_format - lang_createindex.html
  • legacy_file_format pragma - fileformat2.html#filesize
  • library size - about.html
  • like - faq.html#q18 lang_expr.html#like optoverview.html#like_opt
  • LIKE - c3ref/c_limit_attached.html#sqlitelimitlikepatternlength c3ref/prepare.html capi3ref.html#sqlite3_prepare capi3ref.html#sqlitelimitlikepatternlength compile.html#case_sensitive_like compile.html#omit_like_optimization lang_corefunc.html#like limits.html#max_like_pattern_length news.html optoverview.html#like_opt pragma.html#pragma_case_sensitive_like vtab.html#xfindfunction
  • LIKE optimization - changes.html#version_3_7_1 releaselog/3_7_1.html
  • limit categories - c3ref/limit.html capi3ref.html#sqlite3_limit
  • limits - c3ref/c_limit_attached.html c3ref/limit.html capi3ref.html#SQLITE_LIMIT_ATTACHED capi3ref.html#sqlite3_limit compile.html#yystackdepth testing.html#fuzztesting
  • literal-value - lang_expr.html
  • load_extension - tclsqlite.html#varsubst
  • load_extension SQL function - c3ref/load_extension.html capi3ref.html#sqlite3_load_extension howtocompile.html#cli
  • locking_mode - changes.html#version_3_5_9 compile.html#default_locking_mode releaselog/3_5_9.html wal.html#noshm
  • lookaside memory allocator - c3ref/c_dbconfig_enable_fkey.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY changes.html#version_3_6_1 changes.html#version_3_7_9 compile.html#omit_lookaside malloc.html#memstatus malloc.html#nofrag news.html releaselog/3_6_1.html releaselog/3_7_9.html
  • lower - faq.html#q18 lang_corefunc.html#randomblob
  • MATCH - vtab.html#xfindfunction
  • matchinfo - changes.html#version_3_7_4 fts3.html#*matchinfo_fts3 fts3.html#appendix_a fts3.html#fts4 fts3.html#section_1_4 news.html releaselog/3_7_4.html
  • matchinfo_fts3 - fts3.html#*shadowtab fts3.html#fts4
  • max_page_count - c3ref/limit.html c3ref/set_authorizer.html capi3ref.html#sqlite3_limit capi3ref.html#sqlite3_set_authorizer
  • maxAggFunc - lang_corefunc.html#minoreunc
  • MC/DC - th3.html
  • memory - lang_attach.html tclsqlite.html
  • memory allocation - testing.html#memtesting testing.html#oomtesting
  • memory statistics - malloc.html#memstatus malloc.html#nofrag
  • memsys2 - testing.html#memtesting
  • memsys5 - changes.html#version_3_6_6 malloc.html#nofrag releaselog/3_6_6.html selfcontained.html
  • minAggFunc - lang_corefunc.html#maxoreunc
  • NOCASE - faq.html#q18
  • numeric-literal - lang_expr.html#litvalue
  • object resolution - lang_dropview.html
  • offsets - fts3.html#appendix_a fts3.html#section_1_4
  • omitfeatures - 34to35.html changes.html#version_3_1_4 changes.html#version_3_5_2 faq.html#q23 oldnews.html releaselog/3_1_4.html releaselog/3_5_2.html
  • ON CONFLICT - c3ref/blob_open.html c3ref/c_fail.html c3ref/c_vtab_constraint_support.html c3ref/update_hook.html c3ref/vtab_on_conflict.html capi3ref.html#SQLITE_FAIL capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_update_hook capi3ref.html#sqlite3_vtab_on_conflict changes.html#version_3_6_18 changes.html#version_3_7_7 lang_createtable.html#ckconst lang_createtrigger.html lang_createtrigger.html#undef_before lang_insert.html lang_replace.html lang_transaction.html lang_update.html news.html oldnews.html releaselog/3_6_18.html releaselog/3_7_7.html tempfiles.html#stmtjrnl
  • ON CONFLICT clause - lang.html
  • optimizer - eqp.html lang_createtable.html#constraints
  • or optimization - changes.html#version_3_7_4 eqp.html releaselog/3_7_4.html
  • or-connected-terms - eqp.html
  • order by - lang_createtable.html
  • ordering-term - lang_select.html
  • OS backend - testing.html#journaltest
  • overflow pages - changes.html#version_3_7_9 compile.html#direct_overflow_read releaselog/3_7_9.html
  • page cache - changes.html#version_3_7_9 compile.html#direct_overflow_read releaselog/3_7_9.html
  • page_count - 35to36.html changes.html#version_3_7_9 releaselog/3_7_9.html
  • page_size - lang_vacuum.html
  • page_size pragma - lang_vacuum.html
  • pagecache memory allocator - c3ref/c_status_malloc_count.html#sqlitestatuspagecachesize c3ref/c_status_malloc_count.html#sqlitestatuspagecacheused capi3ref.html#sqlitestatuspagecachesize capi3ref.html#sqlitestatuspagecacheused malloc.html#memstatus malloc.html#nofrag
  • parameter - c3ref/bind_blob.html c3ref/c_limit_attached.html#sqlitelimitvariablenumber c3ref/prepare.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_prepare capi3ref.html#sqlitelimitvariablenumber cintro.html limits.html#max_variable_number optoverview.html#like_opt optoverview.html#rangequery
  • parameter binding - c3ref/result_blob.html capi3ref.html#sqlite3_result_blob
  • parameters - c3ref/get_auxdata.html capi3ref.html#sqlite3_get_auxdata datatype3.html#storageclasses limits.html#max_sql_length
  • parent key - lang_createtable.html#rowid
  • permuted index - doclist.html keyword_index.html
  • PRAGMA - c3ref/limit.html c3ref/set_authorizer.html capi3ref.html#sqlite3_limit capi3ref.html#sqlite3_set_authorizer compile.html#omit_flag_pragmas compile.html#omit_pragma lang.html oldnews.html testing.html#crashtesting
  • PRAGMA auto_vacuum - compile.html#default_autovacuum compile.html#omit_autovacuum
  • PRAGMA cache_size - c3ref/pcache_methods.html#thexcachesizepagecachemethod capi3ref.html#thexcachesizepagecachemethod compile.html#default_cache_size
  • PRAGMA case_sensitive_like - changes.html#version_3_7_7_1 news.html releaselog/3_7_7_1.html
  • PRAGMA checkpoint_fullfsync - changes.html#version_3_7_4 releaselog/3_7_4.html
  • PRAGMA foreign_key_list - foreignkeys.html#fk_enable
  • PRAGMA foreign_keys - foreignkeys.html#fk_actions foreignkeys.html#fk_enable
  • PRAGMA incremental_vacuum - c3ref/data_count.html capi3ref.html#sqlite3_data_count
  • PRAGMA integrity_check - testing.html#ioerrtesting
  • PRAGMA journal_mode - changes.html#version_3_6_4 fileformat2.html#walindexformat lang_transaction.html lockingv3.html#hot_journals lockingv3.html#writing releaselog/3_6_4.html
  • PRAGMA legacy_file_format - compile.html#default_file_format
  • PRAGMA locking_mode - changes.html#version_3_7_4 releaselog/3_7_4.html tempfiles.html#rollbackjrnl
  • PRAGMA page_count - changes.html#version_3_6_1 releaselog/3_6_0.html
  • PRAGMA page_size - compile.html#default_page_size
  • PRAGMA recursive_triggers - changes.html#version_3_6_18 foreignkeys.html#fk_actions limits.html#max_trigger_depth releaselog/3_6_18.html
  • PRAGMA synchronous - c3ref/c_fcntl_chunk_size.html c3ref/c_sync_dataonly.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#SQLITE_SYNC_DATAONLY changes.html#version_3_7_5 faq.html#q19 releaselog/3_7_5.html wal.html#fast
  • PRAGMA table_info - vtab.html#hiddencol
  • PRAGMA temp_store - compile.html#temp_store
  • pragma-stmt - pragma.html#syntax
  • pragma-value - pragma.html#syntax
  • prefix queries - fts3.html#fts4order fts3.html#section_6_2 fts3.html#termprefix
  • prepared statement - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_name.html c3ref/busy_handler.html c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/clear_bindings.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/data_count.html c3ref/db_handle.html c3ref/finalize.html c3ref/next_stmt.html c3ref/prepare.html c3ref/reset.html c3ref/set_authorizer.html c3ref/sql.html c3ref/step.html c3ref/stmt_readonly.html c3ref/stmt_status.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_bind_parameter_count capi3ref.html#sqlite3_bind_parameter_name capi3ref.html#sqlite3_busy_handler capi3ref.html#sqlite3_clear_bindings capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_column_count capi3ref.html#sqlite3_column_database_name capi3ref.html#sqlite3_column_decltype capi3ref.html#sqlite3_column_name capi3ref.html#sqlite3_data_count capi3ref.html#sqlite3_db_handle capi3ref.html#sqlite3_finalize capi3ref.html#sqlite3_next_stmt capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_sql capi3ref.html#sqlite3_step capi3ref.html#sqlite3_stmt_readonly capi3ref.html#sqlite3_stmt_status capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigserialized cintro.html compile.html#omit_autoreset custombuild.html faq.html#q15 malloc.html malloc.html#nofrag optoverview.html#like_opt vfs.html
  • prepared statements - 35to36.html c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/close.html capi3ref.html#sqlite3_close capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigserialized changes.html#version_3_6_20 cintro.html custombuild.html datatype3.html#storageclasses malloc.html malloc.html#lookaside malloc.html#nofrag releaselog/3_6_20.html
  • professional support - about.html
  • protected sqlite3_value - c3ref/result_blob.html c3ref/value_blob.html capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_value_blob
  • qualified-table-name - lang_delete.html lang_indexedby.html lang_update.html
  • query parameters with special meaning to SQLite - c3ref/open.html#coreuriqueryparameters capi3ref.html#coreuriqueryparameters
  • query planner - compile.html#enable_stat3
  • quick_check - changes.html#version_3_7_9 releaselog/3_7_9.html
  • quickstart - c3ref/intro.html capi3ref.html
  • R-Trees - vtab.html
  • raise-function - lang_createtrigger.html#undef_before lang_expr.html
  • read-only WAL databases - wal.html
  • read_uncommitted - lang_transaction.html sharedcache.html
  • record format - opcode.html
  • recursive_triggers pragma - lang_conflict.html oldnews.html
  • REGEXP - vtab.html#xfindfunction
  • REINDEX - compile.html#omit_reindex lang.html lang_naming.html
  • reindex-stmt - lang_reindex.html
  • RELEASE - c3ref/stmt_readonly.html capi3ref.html#sqlite3_stmt_readonly lang_transaction.html
  • release-stmt - lang_savepoint.html
  • relfootprint - compile.html compile.html#omitfeatures
  • REPLACE - c3ref/changes.html c3ref/total_changes.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes changes.html#version_3_7_7 lang.html news.html releaselog/3_7_7.html
  • RESERVED - lang_transaction.html
  • result code - c3ref/c_config_getmalloc.html#sqliteconfiglog c3ref/c_fail.html c3ref/errcode.html capi3ref.html#SQLITE_FAIL capi3ref.html#sqlite3_errcode capi3ref.html#sqliteconfiglog
  • result codes - c3ref/step.html capi3ref.html#sqlite3_step
  • result-column - lang_select.html
  • reverse_unordered_selects pragma - changes.html#version_3_6_12 releaselog/3_6_12.html
  • Robson proof - malloc.html#memstatus malloc.html#memsys5 malloc.html#nofrag malloc.html#pagecache
  • ROLLBACK - asyncvfs.html c3ref/commit_hook.html c3ref/get_autocommit.html c3ref/stmt_readonly.html capi3ref.html#sqlite3_commit_hook capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_stmt_readonly changes.html#version_3_6_5 foreignkeys.html#fk_enable lang.html lang_savepoint.html news.html pragma.html#pragma_journal_mode releaselog/3_6_5.html wal.html
  • rollback journal - shortnames.html shortnames.html#db83corrupt wal.html
  • rollback-stmt - lang_savepoint.html lang_transaction.html
  • ROWID - autoinc.html c3ref/last_insert_rowid.html c3ref/randomness.html capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_randomness lang_corefunc.html#last_insert_rowid lang_vacuum.html
  • rowid - c3ref/blob_open.html c3ref/last_insert_rowid.html c3ref/update_hook.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_update_hook fileformat2.html#serialtype foreignkeys.html#parentchild lang_createtable.html lang_expr.html#in_op optoverview.html#index_only queryplanner.html#searching vtab.html#xrowid vtab.html#xupdate
  • rtree - 35to36.html changes.html#version_3_6_1 compile.html#enable_rtree releaselog/3_6_0.html
  • RTREE - amalgamation.html changes.html#version_3_7_7 news.html releaselog/3_7_7.html
  • rules for determining column affinity - lang_expr.html#castexpr
  • SAVEPOINT - c3ref/stmt_readonly.html capi3ref.html#sqlite3_stmt_readonly changes.html#version_3_6_8 changes.html#version_3_7_7 changes.html#version_3_7_9 foreignkeys.html#fk_enable lang.html lang_transaction.html news.html pragma.html#pragma_foreign_keys releaselog/3_6_8.html releaselog/3_7_7.html releaselog/3_7_9.html
  • savepoint-stmt - lang_savepoint.html
  • schema_version - compile.html#omit_schema_version_pragmas
  • scratch memory allocator - c3ref/c_status_malloc_count.html#sqlitestatusscratchsize c3ref/c_status_malloc_count.html#sqlitestatusscratchused capi3ref.html#sqlitestatusscratchsize capi3ref.html#sqlitestatusscratchused malloc.html#memstatus malloc.html#nofrag
  • search application tips - fts3.html#matchinfo
  • secure_delete pragma - changes.html#version_3_6_23 compile.html#secure_delete oldnews.html releaselog/3_6_23.html
  • segment btree - fts3.html#fts4
  • SELECT - 35to36.html c3ref/c_limit_attached.html#sqlitelimitcolumn c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/set_authorizer.html c3ref/stmt_readonly.html capi3ref.html#sqlite3_column_database_name capi3ref.html#sqlite3_column_decltype capi3ref.html#sqlite3_column_name capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_stmt_readonly capi3ref.html#sqlitelimitcolumn compile.html#omit_compound_select datatype3.html#collation fts3.html#section_1_4 lang.html lang_analyze.html lang_createview.html lang_expr.html#in_op lang_indexedby.html lang_transaction.html limits.html#max_compound_select pragma.html pragma.html#pragma_full_column_names pragma.html#pragma_reverse_unordered_selects pragma.html#pragma_short_column_names vtab.html#hiddencol
  • select-core - lang_select.html
  • select-core syntax diagram - lang_select.html
  • select-stmt - lang_select.html
  • serial types - fileformat2.html#filesize
  • SHARED - lang_transaction.html
  • shared cache mode - c3ref/backup_finish.html#sqlite3backuppagecount c3ref/c_dbstatus_options.html#sqlitedbstatusschemaused c3ref/open.html capi3ref.html#sqlite3_open capi3ref.html#sqlite3backuppagecount capi3ref.html#sqlitedbstatusschemaused changes.html#version_3_6_17 changes.html#version_3_6_18 docs.html releaselog/3_6_17.html releaselog/3_6_18.html uri.html#coreqp vtab.html
  • shared lock - c3ref/backup_finish.html#sqlite3backupstep capi3ref.html#sqlite3backupstep lang_transaction.html
  • short filenames - changes.html#version_3_7_7 releaselog/3_7_7.html
  • short_column_names - pragma.html#pragma_full_column_names
  • signed-number - lang_expr.html
  • simple fts queries - fts3.html#fts4 fts3.html#section_3 fts3.html#termprefix
  • single-source - lang_indexedby.html lang_select.html
  • snippet - fts3.html#appendix_a fts3.html#section_1_4
  • sorting - eqp.html
  • soundex SQL function - compile.html#soundex
  • SQL keywords - lang.html
  • SQL parameter - c3ref/bind_parameter_name.html c3ref/result_blob.html capi3ref.html#sqlite3_bind_parameter_name capi3ref.html#sqlite3_result_blob
  • SQL parameters - c3ref/bind_parameter_count.html capi3ref.html#sqlite3_bind_parameter_count
  • sql-stmt - lang.html lang_explain.html
  • sql-stmt-list - lang.html
  • SQLite Consortium - oldnews.html testing.html#tcl th3.html
  • SQLite Shared-Cache Mode - c3ref/enable_shared_cache.html c3ref/unlock_notify.html capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_unlock_notify pragma.html#pragma_read_uncommitted
  • sqlite3 - backup.html c3ref/close.html c3ref/intro.html c3ref/objlist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_close capi3ref.html#sqlite3_open sharedcache.html unlock_notify.html
  • sqlite3_aggregate_context - c3ref/context.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_context cintro.html
  • sqlite3_aggregate_count - c3ref/funclist.html capi3ref.html compile.html#omit_deprecated
  • sqlite3_auto_extension - c3ref/funclist.html c3ref/reset_auto_extension.html capi3ref.html capi3ref.html#sqlite3_reset_auto_extension changes.html#version_3_6_7 releaselog/3_6_7.html
  • sqlite3_backup - backup.html c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupinit c3ref/backup_finish.html#sqlite3backuppagecount c3ref/backup_finish.html#sqlite3backupstep c3ref/objlist.html capi3ref.html capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupinit capi3ref.html#sqlite3backuppagecount capi3ref.html#sqlite3backupstep changes.html#version_3_6_14_1 releaselog/3_6_14_1.html
  • sqlite3_backup_finish - backup.html c3ref/backup.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_backup
  • sqlite3_backup_init - backup.html c3ref/backup.html capi3ref.html#sqlite3_backup changes.html#version_3_6_11 docs.html releaselog/3_6_11.html
  • sqlite3_backup_pagecount - backup.html
  • sqlite3_backup_remaining - backup.html
  • sqlite3_backup_step - backup.html
  • sqlite3_bind_blob - c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/clear_bindings.html c3ref/funclist.html c3ref/reset.html capi3.html capi3ref.html capi3ref.html#sqlite3_bind_parameter_count capi3ref.html#sqlite3_bind_parameter_index capi3ref.html#sqlite3_bind_parameter_name capi3ref.html#sqlite3_clear_bindings capi3ref.html#sqlite3_reset lang_expr.html#varparam limits.html#max_sql_length
  • sqlite3_bind_double - compile.html#omit_floating_point
  • sqlite3_bind_int - cintro.html
  • sqlite3_bind_parameter_count - c3ref/bind_blob.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_bind_parameter_index capi3ref.html#sqlite3_bind_parameter_name
  • sqlite3_bind_parameter_index - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_bind_parameter_count capi3ref.html#sqlite3_bind_parameter_index capi3ref.html#sqlite3_bind_parameter_name
  • sqlite3_bind_parameter_name - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_bind_parameter_count lang_expr.html#varparam
  • sqlite3_bind_text - c3ref/prepare.html capi3ref.html#sqlite3_prepare optoverview.html#like_opt
  • sqlite3_bind_text16 - compile.html#omit_utf16
  • sqlite3_bind_value - c3ref/column_blob.html c3ref/value.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value
  • sqlite3_bind_zeroblob - c3ref/blob_open.html capi3ref.html#sqlite3_blob_open changes.html#version_3_4_0 releaselog/3_4_0.html
  • sqlite3_blob - c3ref/objlist.html capi3ref.html changes.html#version_3_7_4 compile.html#omit_incrblob lang_transaction.html malloc.html#nofrag releaselog/3_7_4.html
  • sqlite3_blob_bytes - c3ref/blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_reopen capi3ref.html#sqlite3_blob_write
  • sqlite3_blob_close - c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/close.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob capi3ref.html#sqlite3_blob_bytes capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3_close lang_transaction.html
  • sqlite3_blob_open - c3ref/bind_blob.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_blob capi3ref.html#sqlite3_blob_bytes capi3ref.html#sqlite3_blob_close capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_reopen capi3ref.html#sqlite3_blob_write changes.html#version_3_4_0 lang_corefunc.html#zeroblob releaselog/3_4_0.html
  • sqlite3_blob_read - c3ref/blob.html c3ref/blob_open.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_reopen capi3ref.html#sqlite3_blob_write
  • sqlite3_blob_reopen - c3ref/blob_reopen.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob_reopen changes.html#version_3_7_4 releaselog/3_7_4.html
  • sqlite3_blob_write - c3ref/blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_reopen
  • sqlite3_busy_handler - backup.html c3ref/backup_finish.html#sqlite3backupstep c3ref/busy_timeout.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_busy_timeout capi3ref.html#sqlite3backupstep faq.html#q5
  • sqlite3_busy_timeout - 34to35.html backup.html c3ref/busy_handler.html c3ref/funclist.html c3ref/sqlite3.html capi3ref.html capi3ref.html#sqlite3 capi3ref.html#sqlite3_busy_handler faq.html#q5
  • sqlite3_changes - c3ref/changes.html c3ref/funclist.html c3ref/total_changes.html capi3ref.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes changes.html#version_3_6_5 lang_conflict.html lang_corefunc.html#changes lang_createtrigger.html#instead_of_trigger lang_delete.html#truncateopt pragma.html#pragma_count_changes releaselog/3_6_5.html
  • sqlite3_clear_bindings - c3ref/funclist.html c3ref/reset.html capi3ref.html capi3ref.html#sqlite3_reset
  • sqlite3_close - backup.html c3ref/close.html c3ref/create_collation.html c3ref/funclist.html c3ref/open.html c3ref/sqlite3.html c3ref/unlock_notify.html capi3.html capi3ref.html capi3ref.html#sqlite3 capi3ref.html#sqlite3_close capi3ref.html#sqlite3_create_collation capi3ref.html#sqlite3_open capi3ref.html#sqlite3_unlock_notify cintro.html malloc.html quickstart.html tempfiles.html#tempdb
  • sqlite3_collation_needed - c3ref/create_collation.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_create_collation
  • sqlite3_collation_needed16 - c3ref/create_collation.html capi3ref.html#sqlite3_create_collation
  • sqlite3_column_blob - c3ref/column_blob.html c3ref/funclist.html capi3.html capi3ref.html capi3ref.html#sqlite3_column_blob changes.html#version_3_4_0 cintro.html releaselog/3_4_0.html
  • sqlite3_column_bytes - c3ref/column_blob.html capi3ref.html#sqlite3_column_blob cintro.html
  • sqlite3_column_bytes16 - c3ref/column_blob.html capi3ref.html#sqlite3_column_blob cintro.html
  • sqlite3_column_count - c3ref/column_blob.html c3ref/data_count.html c3ref/funclist.html capi3.html capi3ref.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_data_count cintro.html
  • sqlite3_column_database_name - c3ref/column_database_name.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_column_database_name compile.html#enable_column_metadata
  • sqlite3_column_database_name16 - compile.html#enable_column_metadata
  • sqlite3_column_decltype - c3ref/funclist.html capi3ref.html compile.html#omit_decltype
  • sqlite3_column_decltype16 - compile.html#omit_decltype
  • sqlite3_column_double - cintro.html compile.html#omit_floating_point
  • sqlite3_column_int - c3ref/data_count.html capi3ref.html#sqlite3_data_count cintro.html
  • sqlite3_column_int64 - cintro.html
  • sqlite3_column_name - c3ref/exec.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_exec
  • sqlite3_column_origin_name - compile.html#enable_column_metadata
  • sqlite3_column_origin_name16 - compile.html#enable_column_metadata
  • sqlite3_column_table_name - compile.html#enable_column_metadata
  • sqlite3_column_table_name16 - compile.html#enable_column_metadata
  • sqlite3_column_text - c3ref/column_blob.html c3ref/exec.html c3ref/free_table.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_free_table cintro.html
  • sqlite3_column_text16 - cintro.html compile.html#omit_utf16
  • sqlite3_column_type - capi3.html cintro.html
  • sqlite3_column_value - c3ref/column_blob.html c3ref/value.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value cintro.html
  • sqlite3_commit_hook - c3ref/funclist.html c3ref/update_hook.html capi3ref.html capi3ref.html#sqlite3_update_hook
  • sqlite3_compileoption_get - c3ref/funclist.html capi3ref.html changes.html#version_3_6_23 compile.html#omit_compileoption_diags lang_corefunc.html#sqlite_compileoption_get oldnews.html pragma.html#pragma_compile_options releaselog/3_6_23.html
  • sqlite3_compileoption_used - changes.html#version_3_6_23 compile.html#omit_compileoption_diags lang_corefunc.html#sqlite_compileoption_used oldnews.html releaselog/3_6_23.html
  • sqlite3_complete - c3ref/complete.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_complete compile.html#omit_complete
  • sqlite3_complete16 - c3ref/complete.html capi3ref.html#sqlite3_complete compile.html#omit_complete
  • sqlite3_config - 35to36.html c3ref/c_config_getmalloc.html c3ref/c_config_getmalloc.html#sqliteconfiggetmutex c3ref/c_config_getmalloc.html#sqliteconfigmalloc c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigmutex c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/c_config_getmalloc.html#sqliteconfigsinglethread c3ref/db_config.html c3ref/funclist.html c3ref/initialize.html c3ref/log.html c3ref/mem_methods.html c3ref/open.html#urifilenamesinsqlite3open c3ref/pcache_methods.html c3ref/soft_heap_limit64.html c3ref/threadsafe.html capi3ref.html capi3ref.html#SQLITE_CONFIG_GETMALLOC capi3ref.html#sqlite3_db_config capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3_log capi3ref.html#sqlite3_mem_methods capi3ref.html#sqlite3_pcache_methods capi3ref.html#sqlite3_soft_heap_limit64 capi3ref.html#sqlite3_threadsafe capi3ref.html#sqliteconfiggetmutex capi3ref.html#sqliteconfigmalloc capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigmutex capi3ref.html#sqliteconfigserialized capi3ref.html#sqliteconfigsinglethread capi3ref.html#urifilenamesinsqlite3open changes.html#version_3_6_1 changes.html#version_3_6_23 compile.html#default_memstatus compile.html#enable_memsys3 compile.html#enable_memsys5 compile.html#threadsafe compile.html#zero_malloc custombuild.html malloc.html#lookaside malloc.html#memstatus malloc.html#memsys5 malloc.html#memsysx malloc.html#pagecache malloc.html#scratch privatebranch.html releaselog/3_6_0.html releaselog/3_6_1.html releaselog/3_6_23.html selfcontained.html testing.html#oomtesting threadsafe.html uri.html
  • sqlite3_context - c3ref/aggregate_context.html c3ref/objlist.html c3ref/result_blob.html capi3ref.html capi3ref.html#sqlite3_aggregate_context capi3ref.html#sqlite3_result_blob
  • sqlite3_context_db_handle - c3ref/context.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_context changes.html#version_3_5_8 oldnews.html releaselog/3_5_8.html
  • sqlite3_create_collation - c3ref/collation_needed.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_collation_needed cintro.html datatype3.html#collation faq.html#q18 fileformat2.html#serialtype
  • sqlite3_create_collation16 - c3ref/collation_needed.html capi3ref.html#sqlite3_collation_needed
  • sqlite3_create_collation_v2 - c3ref/collation_needed.html capi3ref.html#sqlite3_collation_needed
  • sqlite3_create_function - c3ref/context_db_handle.html c3ref/funclist.html c3ref/result_blob.html c3ref/sqlite3.html c3ref/user_data.html c3ref/value_blob.html capi3ref.html capi3ref.html#sqlite3 capi3ref.html#sqlite3_context_db_handle capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_user_data capi3ref.html#sqlite3_value_blob changes.html#version_3_6_15 cintro.html faq.html#q18 fts3.html#appendix_a fts3.html#section_6_1 lang_aggfunc.html lang_corefunc.html lang_corefunc.html#glob lang_corefunc.html#like pragma.html#pragma_case_sensitive_like releaselog/3_6_15.html rtree.html
  • sqlite3_create_function16 - c3ref/context_db_handle.html c3ref/result_blob.html c3ref/user_data.html c3ref/value_blob.html capi3ref.html#sqlite3_context_db_handle capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_user_data capi3ref.html#sqlite3_value_blob
  • sqlite3_create_function_v2 - changes.html#version_3_7_3 news.html releaselog/3_7_3.html
  • sqlite3_create_module - c3ref/funclist.html c3ref/module.html capi3ref.html capi3ref.html#sqlite3_module cintro.html lang_createvtab.html rtree.html vtab.html vtab.html#xcreate
  • sqlite3_create_module_v2 - c3ref/module.html capi3ref.html#sqlite3_module lang_createvtab.html vtab.html vtab.html#xcreate
  • sqlite3_data_count - c3ref/column_count.html c3ref/funclist.html capi3.html capi3ref.html capi3ref.html#sqlite3_column_count changes.html#version_3_7_9 releaselog/3_7_9.html
  • sqlite3_db_config - c3ref/c_config_getmalloc.html#sqliteconfiglookaside c3ref/c_dbconfig_enable_fkey.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqliteconfiglookaside changes.html#version_3_6_1 malloc.html#lookaside privatebranch.html releaselog/3_6_1.html
  • sqlite3_db_handle - c3ref/funclist.html capi3ref.html unlock_notify.html
  • sqlite3_db_mutex - c3ref/errcode.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_errcode changes.html#version_3_6_5 releaselog/3_6_5.html
  • sqlite3_db_status - c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/funclist.html c3ref/status.html c3ref/stmt_status.html capi3ref.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#SQLITE_DBSTATUS options capi3ref.html#sqlite3_status capi3ref.html#sqlite3_stmt_status changes.html#version_3_6_1 changes.html#version_3_7_0 changes.html#version_3_7_1 changes.html#version_3_7_5 changes.html#version_3_7_9 malloc.html#memstatus news.html releaselog/3_6_1.html releaselog/3_7_0.html releaselog/3_7_1.html releaselog/3_7_5.html releaselog/3_7_9.html
  • sqlite3_declare_vtab - c3ref/funclist.html capi3ref.html fts3.html#section_1_4 vtab.html#hiddencol vtab.html#xbestindex vtab.html#xconnect vtab.html#xcreate vtab.html#xupdate
  • sqlite3_enable_load_extension - 34to35.html c3ref/funclist.html c3ref/load_extension.html capi3ref.html capi3ref.html#sqlite3_load_extension compile.html#omit_load_extension tclsqlite.html#varsubst
  • sqlite3_enable_shared_cache - 34to35.html c3ref/funclist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_open changes.html#version_3_5_0 compile.html#omit_shared_cache pragma.html#pragma_read_uncommitted releaselog/3_5_0.html sharedcache.html
  • sqlite3_errcode - backup.html c3ref/backup_finish.html#sqlite3backupinit c3ref/blob_open.html c3ref/column_blob.html c3ref/file_control.html c3ref/free_table.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3backupinit
  • sqlite3_errmsg - backup.html c3ref/backup_finish.html#sqlite3backupinit c3ref/blob_open.html c3ref/file_control.html c3ref/free_table.html c3ref/open.html c3ref/step.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3_open capi3ref.html#sqlite3_step capi3ref.html#sqlite3backupinit
  • sqlite3_errmsg16 - c3ref/backup_finish.html#sqlite3backupinit c3ref/open.html capi3ref.html#sqlite3_open capi3ref.html#sqlite3backupinit
  • sqlite3_exec - backup.html c3ref/changes.html c3ref/free_table.html c3ref/funclist.html c3ref/progress_handler.html c3ref/stmt_readonly.html capi3.html capi3ref.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3_progress_handler capi3ref.html#sqlite3_stmt_readonly cintro.html faq.html#q15 lang.html news.html pragma.html#pragma_empty_result_callbacks quickstart.html
  • sqlite3_expired - compile.html#omit_deprecated
  • sqlite3_extended_errcode - changes.html#version_3_6_5 releaselog/3_6_5.html
  • sqlite3_extended_result_codes - c3ref/c_busy_recovery.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_BUSY_RECOVERY
  • sqlite3_file - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/file.html c3ref/file_control.html c3ref/io_methods.html c3ref/objlist.html c3ref/vfs.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_file capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_io_methods capi3ref.html#sqlite3_vfs capi3ref.html#sqlite3vfsxopen vfs.html
  • sqlite3_file_control - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/file_control.html c3ref/funclist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_io_methods changes.html#version_3_7_1 changes.html#version_3_7_4 changes.html#version_3_7_5 releaselog/3_7_1.html releaselog/3_7_4.html releaselog/3_7_5.html
  • sqlite3_finalize - c3ref/close.html c3ref/column_blob.html c3ref/column_database_name.html c3ref/column_name.html c3ref/exec.html c3ref/funclist.html c3ref/prepare.html c3ref/step.html c3ref/stmt.html c3ref/total_changes.html capi3ref.html capi3ref.html#sqlite3_close capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_column_database_name capi3ref.html#sqlite3_column_name capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_step capi3ref.html#sqlite3_stmt capi3ref.html#sqlite3_total_changes changes.html#version_3_7_6 cintro.html faq.html#q6 lang_transaction.html malloc.html pragma.html releaselog/3_7_6.html
  • sqlite3_free - 34to35.html c3ref/auto_extension.html c3ref/column_blob.html c3ref/exec.html c3ref/free.html c3ref/free_table.html c3ref/funclist.html c3ref/index_info.html c3ref/load_extension.html c3ref/memory_highwater.html c3ref/mprintf.html c3ref/temp_directory.html c3ref/vtab.html capi3ref.html capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_free capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3_index_info capi3ref.html#sqlite3_load_extension capi3ref.html#sqlite3_memory_highwater capi3ref.html#sqlite3_mprintf capi3ref.html#sqlite3_temp_directory capi3ref.html#sqlite3_vtab custombuild.html malloc.html vtab.html vtab.html#xbestindex vtab.html#xconnect vtab.html#xcreate
  • sqlite3_free_table - c3ref/free_table.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_free_table compile.html#omit_get_table
  • sqlite3_get_autocommit - c3ref/funclist.html capi3ref.html lang_transaction.html
  • sqlite3_get_auxdata - c3ref/context.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_context
  • sqlite3_get_table - c3ref/free_table.html c3ref/progress_handler.html capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3_progress_handler cintro.html compile.html#omit_get_table lang.html
  • sqlite3_global_recover - compile.html#omit_deprecated
  • sqlite3_index_info - c3ref/c_index_constraint_eq.html c3ref/objlist.html capi3ref.html capi3ref.html#SQLITE_INDEX_CONSTRAINT_EQ vtab.html vtab.html#xbestindex vtab.html#xfilter
  • sqlite3_initialize - 35to36.html c3ref/complete.html c3ref/config.html c3ref/funclist.html c3ref/mutex_methods.html c3ref/pcache_methods.html#thexinitpagecachemethod capi3ref.html capi3ref.html#sqlite3_complete capi3ref.html#sqlite3_config capi3ref.html#sqlite3_mutex_methods capi3ref.html#thexinitpagecachemethod changes.html#version_3_6_1 compile.html#omit_autoinit custombuild.html releaselog/3_6_0.html
  • sqlite3_int64 - c3ref/intro.html c3ref/objlist.html capi3ref.html
  • sqlite3_interrupt - c3ref/funclist.html c3ref/interrupt.html capi3ref.html capi3ref.html#sqlite3_interrupt lang_transaction.html
  • sqlite3_io_methods - 34to35.html 35to36.html c3ref/c_fcntl_chunk_size.html c3ref/c_iocap_atomic.html c3ref/c_lock_exclusive.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_sync_dataonly.html c3ref/file.html c3ref/file_control.html c3ref/objlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#SQLITE_IOCAP_ATOMIC capi3ref.html#SQLITE_LOCK_EXCLUSIVE capi3ref.html#SQLITE_SHM_EXCLUSIVE capi3ref.html#SQLITE_SHM_NLOCK capi3ref.html#SQLITE_SYNC_DATAONLY capi3ref.html#sqlite3_file capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3vfsxopen compile.html#enable_atomic_write fileformat2.html#walcksm pragma.html#pragma_page_size vfs.html wal.html#noshm
  • sqlite3_last_insert_rowid - c3ref/funclist.html c3ref/last_insert_rowid.html capi3ref.html capi3ref.html#sqlite3_last_insert_rowid faq.html#q1 lang_corefunc.html#last_insert_rowid vtab.html#xupdate
  • sqlite3_libversion - c3ref/c_source_id.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_SOURCE_ID lang_corefunc.html#sqlite_version
  • sqlite3_libversion_number - c3ref/c_source_id.html capi3ref.html#SQLITE_SOURCE_ID
  • sqlite3_limit - c3ref/bind_blob.html c3ref/c_limit_attached.html c3ref/create_function.html c3ref/funclist.html c3ref/limit.html c3ref/set_authorizer.html capi3ref.html capi3ref.html#SQLITE_LIMIT_ATTACHED capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_create_function capi3ref.html#sqlite3_limit capi3ref.html#sqlite3_set_authorizer changes.html#version_3_5_8 compile.html#yystackdepth lang_attach.html lang_createindex.html lang_createtable.html#tablecoldef lang_expr.html#varparam limits.html limits.html#max_attached limits.html#max_column limits.html#max_compound_select limits.html#max_expr_depth limits.html#max_function_arg limits.html#max_length limits.html#max_like_pattern_length limits.html#max_sql_length limits.html#max_variable_number oldnews.html pragma.html#pragma_recursive_triggers privatebranch.html releaselog/3_5_8.html
  • sqlite3_load_extension - c3ref/enable_load_extension.html c3ref/funclist.html c3ref/load_extension.html capi3ref.html capi3ref.html#sqlite3_enable_load_extension capi3ref.html#sqlite3_load_extension compile.html#omit_load_extension howtocompile.html#cli lang_corefunc.html#load_extension vtab.html
  • sqlite3_log - c3ref/c_config_getmalloc.html#sqliteconfiglog c3ref/funclist.html c3ref/log.html capi3ref.html capi3ref.html#sqlite3_log capi3ref.html#sqliteconfiglog changes.html#version_3_6_23 oldnews.html releaselog/3_6_23.html
  • sqlite3_malloc - 34to35.html c3ref/c_config_getmalloc.html#sqliteconfigpagecache c3ref/c_config_getmalloc.html#sqliteconfigscratch c3ref/c_dbconfig_enable_fkey.html c3ref/c_status_malloc_count.html#sqlitestatusmallocsize c3ref/c_status_malloc_count.html#sqlitestatusmemoryused c3ref/c_status_malloc_count.html#sqlitestatuspagecacheoverflow c3ref/c_status_malloc_count.html#sqlitestatusscratchoverflow c3ref/exec.html c3ref/free.html c3ref/free_table.html c3ref/load_extension.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/mprintf.html c3ref/mutex_methods.html c3ref/result_blob.html c3ref/temp_directory.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_free capi3ref.html#sqlite3_free_table capi3ref.html#sqlite3_load_extension capi3ref.html#sqlite3_mem_methods capi3ref.html#sqlite3_memory_highwater capi3ref.html#sqlite3_mprintf capi3ref.html#sqlite3_mutex_methods capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_temp_directory capi3ref.html#sqliteconfigpagecache capi3ref.html#sqliteconfigscratch capi3ref.html#sqlitestatusmallocsize capi3ref.html#sqlitestatusmemoryused capi3ref.html#sqlitestatuspagecacheoverflow capi3ref.html#sqlitestatusscratchoverflow custombuild.html malloc.html malloc.html#lookaside malloc.html#memsys5 vtab.html vtab.html#xconnect vtab.html#xcreate vtab.html#xupdate
  • sqlite3_mem_methods - 35to36.html c3ref/c_config_getmalloc.html#sqliteconfiggetmalloc c3ref/c_config_getmalloc.html#sqliteconfigmalloc c3ref/c_status_malloc_count.html#sqlitestatusmemoryused c3ref/objlist.html capi3ref.html capi3ref.html#sqliteconfiggetmalloc capi3ref.html#sqliteconfigmalloc capi3ref.html#sqlitestatusmemoryused custombuild.html malloc.html#memsysx
  • sqlite3_memory_alarm - 34to35.html compile.html#omit_deprecated
  • sqlite3_memory_highwater - 34to35.html 35to36.html c3ref/c_config_getmalloc.html#sqliteconfigmemstatus c3ref/funclist.html c3ref/memory_highwater.html capi3ref.html capi3ref.html#sqlite3_memory_highwater capi3ref.html#sqliteconfigmemstatus custombuild.html
  • sqlite3_memory_used - 34to35.html 35to36.html c3ref/c_config_getmalloc.html#sqliteconfigmemstatus c3ref/memory_highwater.html capi3ref.html#sqlite3_memory_highwater capi3ref.html#sqliteconfigmemstatus custombuild.html
  • sqlite3_module - c3ref/objlist.html capi3ref.html vtab.html vtab.html#xBegin vtab.html#xcommit vtab.html#xconnect vtab.html#xcreate vtab.html#xrollback vtab.html#xsync vtab.html#xupdate
  • sqlite3_module.xClose - c3ref/vtab_cursor.html capi3ref.html#sqlite3_vtab_cursor vtab.html#xopen
  • sqlite3_module.xOpen - c3ref/vtab_cursor.html capi3ref.html#sqlite3_vtab_cursor vtab.html#xclose vtab.html#xfilter
  • sqlite3_module.xSync - vtab.html#xcommit
  • sqlite3_mprintf - c3ref/auto_extension.html c3ref/funclist.html c3ref/vtab.html capi3ref.html capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_vtab changes.html#version_3_5_9 changes.html#version_3_7_9 compile.html#omit_autoinit releaselog/3_5_9.html releaselog/3_7_9.html vtab.html vtab.html#xbestindex vtab.html#xconnect vtab.html#xcreate vtab.html#xupdate
  • sqlite3_mutex - 34to35.html c3ref/db_mutex.html c3ref/mutex.html c3ref/objlist.html capi3ref.html capi3ref.html#sqlite3_db_mutex capi3ref.html#sqlite3_mutex
  • sqlite3_mutex_alloc - 34to35.html c3ref/c_mutex_fast.html c3ref/funclist.html c3ref/mutex.html c3ref/mutex_methods.html capi3ref.html capi3ref.html#SQLITE_MUTEX_FAST capi3ref.html#sqlite3_mutex capi3ref.html#sqlite3_mutex_methods custombuild.html
  • sqlite3_mutex_enter - 34to35.html 35to36.html c3ref/errcode.html c3ref/mutex_methods.html capi3ref.html#sqlite3_errcode capi3ref.html#sqlite3_mutex_methods
  • sqlite3_mutex_free - 34to35.html c3ref/mutex_methods.html capi3ref.html#sqlite3_mutex_methods
  • sqlite3_mutex_held - c3ref/funclist.html c3ref/mutex_alloc.html c3ref/mutex_methods.html capi3ref.html capi3ref.html#sqlite3_mutex_alloc capi3ref.html#sqlite3_mutex_methods testing.html#mutextesting
  • sqlite3_mutex_leave - 34to35.html c3ref/errcode.html c3ref/mutex_methods.html capi3ref.html#sqlite3_errcode capi3ref.html#sqlite3_mutex_methods
  • sqlite3_mutex_methods - 35to36.html c3ref/c_config_getmalloc.html#sqliteconfiggetmutex c3ref/c_config_getmalloc.html#sqliteconfigmutex c3ref/objlist.html capi3ref.html capi3ref.html#sqliteconfiggetmutex capi3ref.html#sqliteconfigmutex
  • sqlite3_mutex_notheld - c3ref/mutex_alloc.html c3ref/mutex_methods.html capi3ref.html#sqlite3_mutex_alloc capi3ref.html#sqlite3_mutex_methods testing.html#mutextesting
  • sqlite3_mutex_try - 34to35.html c3ref/mutex_methods.html capi3ref.html#sqlite3_mutex_methods
  • sqlite3_next_stmt - 35to36.html c3ref/funclist.html c3ref/next_stmt.html capi3ref.html capi3ref.html#sqlite3_next_stmt changes.html#version_3_6_1 releaselog/3_6_0.html
  • sqlite3_open - 34to35.html backup.html c3ref/auto_extension.html c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/close.html c3ref/enable_shared_cache.html c3ref/funclist.html c3ref/initialize.html c3ref/prepare.html c3ref/sqlite3.html c3ref/vfs.html#sqlite3vfsxopen capi3.html capi3ref.html capi3ref.html#sqlite3 capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_close capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3vfsxopen capi3ref.html#sqliteconfiguri cintro.html compile.html#omit_autoinit compile.html#omit_memorydb faq.html#q6 inmemorydb.html inmemorydb.html#temp_db lang_attach.html malloc.html#lookaside malloc.html#nofrag pragma.html#pragma_journal_mode quickstart.html sharedcache.html shortnames.html tempfiles.html#masterjrnl threadsafe.html uri.html vfs.html
  • sqlite3_open16 - 34to35.html c3ref/auto_extension.html c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/close.html c3ref/enable_shared_cache.html c3ref/prepare.html c3ref/sqlite3.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html#sqlite3 capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_close capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3vfsxopen capi3ref.html#sqliteconfiguri cintro.html compile.html#omit_memorydb inmemorydb.html pragma.html#pragma_journal_mode sharedcache.html tempfiles.html#masterjrnl threadsafe.html uri.html vfs.html
  • sqlite3_open_v2 - 34to35.html 35to36.html c3ref/auto_extension.html c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/c_open_autoproxy.html c3ref/close.html c3ref/enable_shared_cache.html c3ref/prepare.html c3ref/sqlite3.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html#SQLITE_OPEN_AUTOPROXY capi3ref.html#sqlite3 capi3ref.html#sqlite3_auto_extension capi3ref.html#sqlite3_close capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3vfsxopen capi3ref.html#sqliteconfiguri changes.html#version_3_5_0 changes.html#version_3_6_1 changes.html#version_3_6_18 cintro.html compile.html#enable_locking_style compile.html#omit_memorydb compile.html#threadsafe custombuild.html howtocorrupt.html#delhotjrnl inmemorydb.html lang_attach.html pragma.html#pragma_journal_mode releaselog/3_5_0.html releaselog/3_6_0.html releaselog/3_6_18.html sharedcache.html tempfiles.html#masterjrnl threadsafe.html uri.html vfs.html
  • sqlite3_os_end - 35to36.html compile.html#os_other custombuild.html
  • sqlite3_os_init - 35to36.html c3ref/config.html capi3ref.html#sqlite3_config compile.html#os_other custombuild.html
  • sqlite3_overload_function - c3ref/funclist.html capi3ref.html
  • sqlite3_pcache - c3ref/objlist.html c3ref/pcache_methods.html#thexdestroypagecachemethod capi3ref.html capi3ref.html#thexdestroypagecachemethod
  • sqlite3_pcache_methods - c3ref/c_config_getmalloc.html#sqliteconfiggetpcache c3ref/c_config_getmalloc.html#sqliteconfigpcache c3ref/objlist.html c3ref/pcache.html capi3ref.html capi3ref.html#sqlite3_pcache capi3ref.html#sqliteconfiggetpcache capi3ref.html#sqliteconfigpcache changes.html#version_3_6_6 oldnews.html pragma.html#pragma_cache_size releaselog/3_6_6.html
  • sqlite3_prepare - c3ref/funclist.html c3ref/set_authorizer.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_step cintro.html faq.html#q15 lang.html limits.html#max_sql_length news.html optoverview.html#like_opt pragma.html pragma.html#pragma_foreign_keys pragma.html#pragma_recursive_triggers unlock_notify.html vtab.html#xbestindex vtab.html#xfindfunction
  • sqlite3_prepare16 - c3ref/bind_parameter_name.html c3ref/set_authorizer.html c3ref/step.html capi3ref.html#sqlite3_bind_parameter_name capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_step compile.html#omit_utf16 lang.html optoverview.html#like_opt
  • sqlite3_prepare16_v2 - c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/set_authorizer.html c3ref/sql.html c3ref/step.html capi3ref.html#sqlite3_bind_parameter_index capi3ref.html#sqlite3_bind_parameter_name capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_sql capi3ref.html#sqlite3_step lang.html optoverview.html#like_opt
  • sqlite3_prepare_v2 - c3ref/bind_blob.html c3ref/column_blob.html c3ref/commit_hook.html c3ref/db_handle.html c3ref/exec.html c3ref/progress_handler.html c3ref/set_authorizer.html c3ref/sql.html c3ref/sqlite3.html c3ref/step.html c3ref/stmt.html c3ref/update_hook.html capi3.html capi3ref.html#sqlite3 capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_commit_hook capi3ref.html#sqlite3_db_handle capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_progress_handler capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_sql capi3ref.html#sqlite3_step capi3ref.html#sqlite3_stmt capi3ref.html#sqlite3_update_hook changes.html#version_3_5_3 cintro.html faq.html#q15 lang.html lang_comment.html limits.html#max_column malloc.html#lookaside malloc.html#nofrag optoverview.html#like_opt releaselog/3_5_3.html unlock_notify.html vfs.html
  • sqlite3_profile - c3ref/funclist.html capi3ref.html compile.html#omit_trace
  • sqlite3_progress_handler - c3ref/funclist.html capi3ref.html compile.html#omit_progress_callback
  • sqlite3_randomness - c3ref/funclist.html capi3ref.html changes.html#version_3_5_8 oldnews.html releaselog/3_5_8.html
  • sqlite3_realloc - 34to35.html c3ref/c_status_malloc_count.html#sqlitestatusmallocsize c3ref/free.html c3ref/mem_methods.html c3ref/memory_highwater.html capi3ref.html#sqlite3_free capi3ref.html#sqlite3_mem_methods capi3ref.html#sqlite3_memory_highwater capi3ref.html#sqlitestatusmallocsize malloc.html
  • sqlite3_release_memory - 34to35.html c3ref/funclist.html capi3ref.html changes.html#version_3_5_0 compile.html#enable_memory_management releaselog/3_5_0.html
  • sqlite3_reset - c3ref/bind_blob.html c3ref/clear_bindings.html c3ref/column_blob.html c3ref/finalize.html c3ref/funclist.html c3ref/prepare.html c3ref/reset.html c3ref/step.html c3ref/stmt.html c3ref/total_changes.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_clear_bindings capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_finalize capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_step capi3ref.html#sqlite3_stmt capi3ref.html#sqlite3_total_changes cintro.html compile.html#omit_autoreset lang_transaction.html unlock_notify.html
  • sqlite3_reset_auto_extension - c3ref/auto_extension.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_auto_extension
  • sqlite3_result_blob - c3ref/c_static.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_STATIC vtab.html#xcolumn
  • sqlite3_result_double - compile.html#omit_floating_point vtab.html#xcolumn
  • sqlite3_result_error_code - changes.html#version_3_5_6 releaselog/3_5_6.html
  • sqlite3_result_int - c3ref/context.html capi3ref.html#sqlite3_context cintro.html vtab.html#xcolumn
  • sqlite3_result_int64 - vtab.html#xcolumn
  • sqlite3_result_null - vtab.html#xcolumn
  • sqlite3_result_text - vtab.html#xcolumn
  • sqlite3_result_text16 - vtab.html#xcolumn
  • sqlite3_result_text16be - vtab.html#xcolumn
  • sqlite3_result_text16le - vtab.html#xcolumn
  • sqlite3_result_value - c3ref/column_blob.html c3ref/value.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value
  • sqlite3_result_zeroblob - c3ref/blob_open.html capi3ref.html#sqlite3_blob_open lang_corefunc.html#zeroblob vtab.html#xcolumn
  • sqlite3_rollback_hook - c3ref/update_hook.html capi3ref.html#sqlite3_update_hook
  • sqlite3_set_authorizer - c3ref/c_alter_table.html c3ref/c_deny.html c3ref/c_fail.html c3ref/funclist.html c3ref/limit.html capi3ref.html capi3ref.html#SQLITE_ALTER_TABLE capi3ref.html#SQLITE_DENY capi3ref.html#SQLITE_FAIL capi3ref.html#sqlite3_limit compile.html#omit_authorization fts3.html#tokenizer lang_delete.html#truncateopt
  • sqlite3_set_auxdata - c3ref/context.html capi3ref.html#sqlite3_context
  • sqlite3_shutdown - 35to36.html c3ref/config.html c3ref/mem_methods.html c3ref/mutex_methods.html c3ref/pcache_methods.html#thexshutdownpagecachemethod capi3ref.html#sqlite3_config capi3ref.html#sqlite3_mem_methods capi3ref.html#sqlite3_mutex_methods capi3ref.html#thexshutdownpagecachemethod changes.html#version_3_6_1 changes.html#version_3_6_15 custombuild.html releaselog/3_6_0.html releaselog/3_6_15.html
  • sqlite3_sleep - 34to35.html backup.html c3ref/funclist.html capi3ref.html
  • sqlite3_snprintf - c3ref/c_config_getmalloc.html#sqliteconfiglog c3ref/column_blob.html c3ref/log.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_log capi3ref.html#sqliteconfiglog changes.html#version_3_4_0 lang_expr.html#castexpr news.html releaselog/3_4_0.html
  • sqlite3_soft_heap_limit - 34to35.html c3ref/funclist.html capi3ref.html changes.html#version_3_4_2 changes.html#version_3_5_0 changes.html#version_3_7_3 releaselog/3_4_2.html releaselog/3_5_0.html releaselog/3_7_3.html
  • sqlite3_soft_heap_limit64 - c3ref/c_config_getmalloc.html#sqliteconfigmemstatus c3ref/funclist.html c3ref/soft_heap_limit.html capi3ref.html capi3ref.html#sqlite3_soft_heap_limit capi3ref.html#sqliteconfigmemstatus changes.html#version_3_7_3 custombuild.html malloc.html malloc.html#memstatus news.html releaselog/3_7_3.html
  • sqlite3_sourceid - c3ref/c_source_id.html capi3ref.html#SQLITE_SOURCE_ID changes.html#version_3_6_18 lang_corefunc.html#sqlite_source_id releaselog/3_6_18.html
  • sqlite3_sql - c3ref/funclist.html capi3ref.html
  • sqlite3_status - 35to36.html c3ref/c_config_getmalloc.html#sqliteconfigmemstatus c3ref/c_status_malloc_count.html c3ref/c_status_malloc_count.html#sqlitestatusmallocsize c3ref/c_status_malloc_count.html#sqlitestatuspagecachesize c3ref/c_status_malloc_count.html#sqlitestatusscratchsize c3ref/db_status.html c3ref/funclist.html c3ref/stmt_status.html capi3ref.html capi3ref.html#SQLITE_STATUS_MALLOC_COUNT capi3ref.html#sqlite3_db_status capi3ref.html#sqlite3_stmt_status capi3ref.html#sqliteconfigmemstatus capi3ref.html#sqlitestatusmallocsize capi3ref.html#sqlitestatuspagecachesize capi3ref.html#sqlitestatusscratchsize changes.html#version_3_6_1 compile.html#yytrackmaxstackdepth malloc.html#memstatus releaselog/3_6_0.html releaselog/3_6_1.html
  • sqlite3_step - backup.html c3ref/bind_blob.html c3ref/busy_timeout.html c3ref/changes.html c3ref/column_blob.html c3ref/column_database_name.html c3ref/column_name.html c3ref/commit_hook.html c3ref/data_count.html c3ref/exec.html c3ref/finalize.html c3ref/funclist.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/reset.html c3ref/set_authorizer.html c3ref/stmt.html c3ref/unlock_notify.html c3ref/update_hook.html capi3.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_busy_timeout capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_column_database_name capi3ref.html#sqlite3_column_name capi3ref.html#sqlite3_commit_hook capi3ref.html#sqlite3_data_count capi3ref.html#sqlite3_exec capi3ref.html#sqlite3_finalize capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_profile capi3ref.html#sqlite3_progress_handler capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_stmt capi3ref.html#sqlite3_unlock_notify capi3ref.html#sqlite3_update_hook changes.html#version_3_5_3 cintro.html compile.html#max_schema_retry compile.html#omit_autoreset faq.html#q15 malloc.html#lookaside malloc.html#nofrag optoverview.html#like_opt pragma.html releaselog/3_5_3.html unlock_notify.html vfs.html
  • sqlite3_stmt - c3ref/bind_blob.html c3ref/column_blob.html c3ref/intro.html c3ref/objlist.html c3ref/prepare.html c3ref/value_blob.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_value_blob faq.html#q6 unlock_notify.html
  • sqlite3_stmt_readonly - c3ref/funclist.html capi3ref.html changes.html#version_3_7_4 changes.html#version_3_7_5 releaselog/3_7_4.html releaselog/3_7_5.html
  • sqlite3_stmt_status - c3ref/c_stmtstatus_counter.html c3ref/db_status.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_STMTSTATUS counter capi3ref.html#sqlite3_db_status changes.html#version_3_6_4 lang_indexedby.html releaselog/3_6_4.html tclsqlite.html#varsubst
  • sqlite3_strnicmp - c3ref/create_collation.html c3ref/funclist.html c3ref/strnicmp.html capi3ref.html capi3ref.html#sqlite3_create_collation capi3ref.html#sqlite3_strnicmp changes.html#version_3_6_17 oldnews.html releaselog/3_6_17.html
  • sqlite3_table_column_metadata - c3ref/funclist.html capi3ref.html compile.html#enable_column_metadata
  • sqlite3_temp_directory - c3ref/objlist.html capi3ref.html pragma.html#pragma_temp_store_directory
  • sqlite3_test_control - c3ref/c_testctrl_always.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_TESTCTRL_ALWAYS compile.html#omit_builtin_test testing.html#defensivecode testing.html#disopttest
  • sqlite3_thread_cleanup - 34to35.html compile.html#omit_deprecated
  • sqlite3_threadsafe - c3ref/funclist.html c3ref/value.html capi3ref.html capi3ref.html#sqlite3_value compile.html#threadsafe custombuild.html faq.html#q6 threadsafe.html
  • sqlite3_total_changes - c3ref/changes.html c3ref/funclist.html c3ref/total_changes.html capi3ref.html capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_total_changes changes.html#version_3_6_5 lang_corefunc.html#total_changes lang_createtrigger.html#instead_of_trigger lang_delete.html#truncateopt pragma.html#pragma_count_changes releaselog/3_6_5.html
  • sqlite3_trace - changes.html#version_3_6_21 changes.html#version_3_7_5 compile.html#omit_trace news.html oldnews.html releaselog/3_6_21.html releaselog/3_7_5.html
  • sqlite3_transfer_bindings - compile.html#omit_deprecated
  • sqlite3_unlock_notify - c3ref/funclist.html capi3ref.html changes.html#version_3_6_12 compile.html#enable_unlock_notify releaselog/3_6_12.html unlock_notify.html
  • sqlite3_update_hook - c3ref/commit_hook.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_commit_hook lang_conflict.html
  • sqlite3_uri_parameter - c3ref/funclist.html capi3ref.html
  • sqlite3_user_data - c3ref/context.html c3ref/create_function.html c3ref/funclist.html capi3ref.html capi3ref.html#sqlite3_context capi3ref.html#sqlite3_create_function cintro.html
  • sqlite3_value - c3ref/objlist.html c3ref/result_blob.html c3ref/value_blob.html capi3ref.html capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_value_blob
  • sqlite3_value_blob - c3ref/funclist.html c3ref/value.html c3ref/value_blob.html capi3ref.html capi3ref.html#sqlite3_value capi3ref.html#sqlite3_value_blob
  • sqlite3_value_bytes - c3ref/column_blob.html c3ref/value_blob.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value_blob
  • sqlite3_value_bytes16 - c3ref/value_blob.html capi3ref.html#sqlite3_value_blob
  • sqlite3_value_double - compile.html#omit_floating_point
  • sqlite3_value_int - c3ref/column_blob.html capi3ref.html#sqlite3_column_blob cintro.html
  • sqlite3_value_text - c3ref/column_blob.html c3ref/value_blob.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value_blob
  • sqlite3_value_text16 - c3ref/value_blob.html capi3ref.html#sqlite3_value_blob
  • sqlite3_vfs - 34to35.html 35to36.html asyncvfs.html c3ref/c_access_exists.html c3ref/file.html c3ref/initialize.html c3ref/objlist.html c3ref/open.html c3ref/randomness.html c3ref/sleep.html c3ref/temp_directory.html c3ref/vfs_find.html capi3ref.html capi3ref.html#SQLITE_ACCESS_EXISTS capi3ref.html#sqlite3_file capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3_open capi3ref.html#sqlite3_randomness capi3ref.html#sqlite3_sleep capi3ref.html#sqlite3_temp_directory capi3ref.html#sqlite3_vfs_find changes.html#version_3_6_1 changes.html#version_3_6_7 changes.html#version_3_7_4 changes.html#version_3_7_6 compile.html#os_other custombuild.html howtocorrupt.html#delhotjrnl lang_datefunc.html oldnews.html releaselog/3_6_0.html releaselog/3_6_7.html releaselog/3_7_4.html releaselog/3_7_6.html testing.html#crashtesting testing.html#ioerrtesting vfs.html
  • sqlite3_vfs.xOpen - c3ref/c_open_autoproxy.html c3ref/io_methods.html capi3ref.html#SQLITE_OPEN_AUTOPROXY capi3ref.html#sqlite3_io_methods
  • sqlite3_vfs_find - 34to35.html c3ref/funclist.html c3ref/vfs.html capi3ref.html capi3ref.html#sqlite3_vfs
  • sqlite3_vfs_register - 34to35.html asyncvfs.html c3ref/vfs.html capi3ref.html#sqlite3_vfs compile.html#omit_autoinit compile.html#os_other custombuild.html privatebranch.html uri.html#coreqp vfs.html
  • sqlite3_vfs_unregister - 34to35.html c3ref/vfs.html capi3ref.html#sqlite3_vfs
  • sqlite3_vsnprintf - changes.html#version_3_7_5 news.html releaselog/3_7_5.html
  • sqlite3_vtab - c3ref/objlist.html capi3ref.html compile.html#omit_virtualtable vtab.html vtab.html#xconnect vtab.html#xcreate vtab.html#xdisconnect vtab.html#xfindfunction
  • sqlite3_vtab_config - c3ref/c_vtab_constraint_support.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT changes.html#version_3_7_7 releaselog/3_7_7.html
  • sqlite3_vtab_cursor - c3ref/objlist.html capi3ref.html vtab.html vtab.html#xclose vtab.html#xnext vtab.html#xopen vtab.html#xrowid vtab.html#xupdate
  • sqlite3_vtab_on_conflict - c3ref/c_abort.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_vtab_constraint_support.html c3ref/funclist.html capi3ref.html capi3ref.html#SQLITE_ABORT capi3ref.html#SQLITE_DENY capi3ref.html#SQLITE_FAIL capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT
  • sqlite3_wal_autocheckpoint - c3ref/funclist.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_hook.html capi3ref.html capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_checkpoint capi3ref.html#sqlite3_wal_hook pragma.html#pragma_wal_autocheckpoint wal.html#fast
  • sqlite3_wal_checkpoint - c3ref/funclist.html c3ref/wal_checkpoint.html capi3ref.html capi3ref.html#sqlite3_wal_checkpoint pragma.html#pragma_wal_checkpoint wal.html#fast
  • sqlite3_wal_checkpoint_v2 - c3ref/c_checkpoint_full.html c3ref/funclist.html c3ref/wal_checkpoint.html capi3ref.html capi3ref.html#SQLITE_CHECKPOINT_FULL capi3ref.html#sqlite3_wal_checkpoint changes.html#version_3_7_6 pragma.html#pragma_wal_checkpoint releaselog/3_7_6.html
  • sqlite3_wal_hook - c3ref/funclist.html c3ref/wal_autocheckpoint.html c3ref/wal_hook.html capi3ref.html capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_hook wal.html#fast
  • SQLITE_4_BYTE_ALIGNED_MALLOC - c3ref/free.html capi3ref.html#sqlite3_free
  • SQLITE_ABORT - c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/c_fail.html c3ref/constlist.html c3ref/vtab_on_conflict.html capi3ref.html capi3ref.html#SQLITE_FAIL capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3_vtab_on_conflict
  • SQLITE_ACCESS_EXISTS - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxaccess capi3ref.html capi3ref.html#sqlite3vfsxaccess
  • SQLITE_ACCESS_READ - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxaccess capi3ref.html capi3ref.html#sqlite3vfsxaccess
  • SQLITE_ACCESS_READWRITE - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxaccess capi3ref.html capi3ref.html#sqlite3vfsxaccess
  • SQLITE_ALTER_TABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_ANALYZE - c3ref/constlist.html capi3ref.html
  • SQLITE_ANY - c3ref/constlist.html c3ref/create_function.html capi3ref.html capi3ref.html#sqlite3_create_function
  • SQLITE_ATTACH - c3ref/constlist.html capi3ref.html
  • SQLITE_AUTH - c3ref/constlist.html capi3ref.html
  • SQLITE_BLOB - c3ref/column_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_column_blob
  • SQLITE_BUSY - 34to35.html backup.html c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupstep c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_dbconfig_enable_fkey.html c3ref/constlist.html c3ref/get_autocommit.html c3ref/step.html capi3ref.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY capi3ref.html#sqlite3_busy_handler capi3ref.html#sqlite3_busy_timeout capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_step capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupstep changes.html#version_3_4_0 changes.html#version_3_6_5 compile.html#omit_autoreset lang_transaction.html releaselog/3_4_0.html releaselog/3_6_5.html
  • SQLITE_BUSY_RECOVERY - c3ref/constlist.html capi3ref.html
  • SQLITE_CANTOPEN - c3ref/constlist.html c3ref/free.html c3ref/vfs.html#sqlite3vfsxaccess capi3ref.html capi3ref.html#sqlite3_free capi3ref.html#sqlite3vfsxaccess
  • SQLITE_CANTOPEN_NOTEMPDIR - c3ref/constlist.html capi3ref.html
  • SQLITE_CASE_SENSITIVE_LIKE - optoverview.html#like_opt
  • SQLITE_CHECKPOINT_FULL - c3ref/constlist.html capi3ref.html
  • SQLITE_CHECKPOINT_PASSIVE - c3ref/constlist.html capi3ref.html pragma.html#pragma_wal_checkpoint
  • SQLITE_CHECKPOINT_RESTART - c3ref/constlist.html capi3ref.html
  • sqlite_compileoption_get - c3ref/compileoption_get.html capi3ref.html#sqlite3_compileoption_get changes.html#version_3_6_23 compile.html#omit_compileoption_diags oldnews.html pragma.html#pragma_compile_options releaselog/3_6_23.html
  • sqlite_compileoption_used - c3ref/compileoption_get.html capi3ref.html#sqlite3_compileoption_get changes.html#version_3_6_23 compile.html#omit_compileoption_diags oldnews.html releaselog/3_6_23.html
  • SQLITE_CONFIG_GETMALLOC - c3ref/constlist.html c3ref/mem_methods.html capi3ref.html capi3ref.html#sqlite3_mem_methods malloc.html#memsysx
  • SQLITE_CONFIG_GETMUTEX - c3ref/constlist.html c3ref/mutex_methods.html capi3ref.html capi3ref.html#sqlite3_mutex_methods
  • SQLITE_CONFIG_GETPCACHE - c3ref/constlist.html capi3ref.html
  • SQLITE_CONFIG_HEAP - c3ref/constlist.html capi3ref.html compile.html#enable_memsys3 compile.html#enable_memsys5 compile.html#zero_malloc malloc.html#memsys5 malloc.html#memsysx malloc.html#nofrag
  • SQLITE_CONFIG_LOG - c3ref/constlist.html c3ref/log.html capi3ref.html capi3ref.html#sqlite3_log changes.html#version_3_6_23 oldnews.html releaselog/3_6_23.html
  • SQLITE_CONFIG_LOOKASIDE - c3ref/c_dbconfig_enable_fkey.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_DBCONFIG_ENABLE_FKEY changes.html#version_3_6_1 malloc.html#lookaside releaselog/3_6_1.html
  • SQLITE_CONFIG_MALLOC - 35to36.html c3ref/c_config_getmalloc.html#sqliteconfigheap c3ref/constlist.html c3ref/mem_methods.html capi3ref.html capi3ref.html#sqlite3_mem_methods capi3ref.html#sqliteconfigheap compile.html#zero_malloc malloc.html#memsysx testing.html#oomtesting
  • SQLITE_CONFIG_MEMSTATUS - c3ref/constlist.html c3ref/mem_methods.html c3ref/soft_heap_limit64.html capi3ref.html capi3ref.html#sqlite3_mem_methods capi3ref.html#sqlite3_soft_heap_limit64 compile.html#default_memstatus custombuild.html malloc.html#memstatus malloc.html#memsysx
  • SQLITE_CONFIG_MULTITHREAD - 35to36.html c3ref/constlist.html c3ref/threadsafe.html c3ref/value.html capi3ref.html capi3ref.html#sqlite3_threadsafe capi3ref.html#sqlite3_value compile.html#threadsafe custombuild.html threadsafe.html
  • SQLITE_CONFIG_MUTEX - 35to36.html c3ref/constlist.html c3ref/mutex_alloc.html c3ref/mutex_methods.html c3ref/threadsafe.html capi3ref.html capi3ref.html#sqlite3_mutex_alloc capi3ref.html#sqlite3_mutex_methods capi3ref.html#sqlite3_threadsafe changes.html#version_3_6_1 releaselog/3_6_0.html selfcontained.html
  • SQLITE_CONFIG_PAGECACHE - c3ref/c_config_getmalloc.html#sqliteconfigheap c3ref/c_status_malloc_count.html#sqlitestatusmemoryused c3ref/c_status_malloc_count.html#sqlitestatuspagecacheoverflow c3ref/c_status_malloc_count.html#sqlitestatuspagecacheused c3ref/constlist.html c3ref/soft_heap_limit64.html capi3ref.html capi3ref.html#sqlite3_soft_heap_limit64 capi3ref.html#sqliteconfigheap capi3ref.html#sqlitestatusmemoryused capi3ref.html#sqlitestatuspagecacheoverflow capi3ref.html#sqlitestatuspagecacheused changes.html#version_3_6_1 changes.html#version_3_7_3 malloc.html#pagecache releaselog/3_6_1.html releaselog/3_7_3.html
  • SQLITE_CONFIG_PCACHE - c3ref/constlist.html c3ref/pcache_methods.html c3ref/soft_heap_limit64.html capi3ref.html capi3ref.html#sqlite3_pcache_methods capi3ref.html#sqlite3_soft_heap_limit64
  • SQLITE_CONFIG_SCRATCH - c3ref/c_config_getmalloc.html#sqliteconfigheap c3ref/c_status_malloc_count.html#sqlitestatusmemoryused c3ref/c_status_malloc_count.html#sqlitestatusscratchoverflow c3ref/c_status_malloc_count.html#sqlitestatusscratchused c3ref/constlist.html capi3ref.html capi3ref.html#sqliteconfigheap capi3ref.html#sqlitestatusmemoryused capi3ref.html#sqlitestatusscratchoverflow capi3ref.html#sqlitestatusscratchused changes.html#version_3_6_1 malloc.html#scratch releaselog/3_6_1.html
  • SQLITE_CONFIG_SERIALIZED - 35to36.html c3ref/constlist.html capi3ref.html compile.html#threadsafe threadsafe.html
  • SQLITE_CONFIG_SINGLETHREAD - 35to36.html c3ref/constlist.html c3ref/threadsafe.html c3ref/value.html capi3ref.html capi3ref.html#sqlite3_threadsafe capi3ref.html#sqlite3_value compile.html#threadsafe threadsafe.html
  • SQLITE_CONFIG_URI - c3ref/constlist.html c3ref/open.html#urifilenamesinsqlite3open capi3ref.html capi3ref.html#urifilenamesinsqlite3open uri.html
  • SQLITE_CONSTRAINT - c3ref/c_vtab_constraint_support.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT lang_createtrigger.html#undef_before
  • SQLITE_COPY - c3ref/constlist.html c3ref/set_authorizer.html capi3ref.html capi3ref.html#sqlite3_set_authorizer
  • SQLITE_CORRUPT - c3ref/constlist.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_step faq.html#q21 testing.html#fuzztesting
  • SQLITE_CORRUPT_VTAB - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_INDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TEMP_INDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TEMP_TABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TEMP_TRIGGER - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TEMP_VIEW - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_TRIGGER - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_VIEW - c3ref/constlist.html capi3ref.html
  • SQLITE_CREATE_VTABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_DBCONFIG_ENABLE_FKEY - c3ref/constlist.html capi3ref.html
  • SQLITE_DBCONFIG_ENABLE_TRIGGER - c3ref/constlist.html capi3ref.html
  • SQLITE_DBCONFIG_LOOKASIDE - c3ref/c_config_getmalloc.html#sqliteconfiglookaside c3ref/constlist.html c3ref/db_config.html capi3ref.html capi3ref.html#sqlite3_db_config capi3ref.html#sqliteconfiglookaside malloc.html#lookaside
  • SQLITE_DBSTATUS options - c3ref/db_status.html capi3ref.html#sqlite3_db_status
  • SQLITE_DBSTATUS_CACHE_HIT - c3ref/constlist.html capi3ref.html changes.html#version_3_7_9 releaselog/3_7_9.html
  • SQLITE_DBSTATUS_CACHE_MISS - c3ref/constlist.html capi3ref.html changes.html#version_3_7_9 releaselog/3_7_9.html
  • SQLITE_DBSTATUS_CACHE_USED - c3ref/constlist.html capi3ref.html changes.html#version_3_7_0 releaselog/3_7_0.html
  • SQLITE_DBSTATUS_LOOKASIDE_HIT - c3ref/constlist.html capi3ref.html changes.html#version_3_7_5 news.html releaselog/3_7_5.html
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL - c3ref/constlist.html capi3ref.html changes.html#version_3_7_5 releaselog/3_7_5.html
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE - c3ref/constlist.html capi3ref.html changes.html#version_3_7_5 releaselog/3_7_5.html
  • SQLITE_DBSTATUS_LOOKASIDE_USED - c3ref/constlist.html capi3ref.html malloc.html#memstatus
  • SQLITE_DBSTATUS_MAX - c3ref/constlist.html capi3ref.html
  • SQLITE_DBSTATUS_SCHEMA_USED - c3ref/constlist.html capi3ref.html changes.html#version_3_7_1 releaselog/3_7_1.html
  • SQLITE_DBSTATUS_STMT_USED - c3ref/constlist.html capi3ref.html changes.html#version_3_7_1 releaselog/3_7_1.html
  • SQLITE_DEBUG - pragma.html#pragma_parser_trace pragma.html#pragma_vdbe_listing pragma.html#pragma_vdbe_trace pragma.html#toc
  • SQLITE_DEFAULT_AUTOVACUUM - pragma.html#pragma_auto_vacuum
  • SQLITE_DEFAULT_FILE_FORMAT - fileformat2.html#filesize pragma.html#pragma_legacy_file_format
  • SQLITE_DEFAULT_FOREIGN_KEYS - changes.html#version_3_7_5 pragma.html#pragma_foreign_keys releaselog/3_7_5.html
  • SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT - pragma.html#pragma_journal_size_limit
  • SQLITE_DEFAULT_LOCKING_MODE - pragma.html#pragma_locking_mode
  • SQLITE_DEFAULT_MEMSTATUS - c3ref/c_config_getmalloc.html#sqliteconfigmemstatus c3ref/soft_heap_limit64.html capi3ref.html#sqlite3_soft_heap_limit64 capi3ref.html#sqliteconfigmemstatus
  • SQLITE_DEFAULT_WAL_AUTOCHECKPOINT - c3ref/wal_autocheckpoint.html capi3ref.html#sqlite3_wal_autocheckpoint pragma.html#pragma_wal_autocheckpoint wal.html#ckpt
  • SQLITE_DELETE - c3ref/constlist.html c3ref/set_authorizer.html c3ref/update_hook.html capi3ref.html capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_update_hook lang_delete.html#truncateopt
  • SQLITE_DENY - c3ref/constlist.html c3ref/set_authorizer.html capi3ref.html capi3ref.html#sqlite3_set_authorizer
  • SQLITE_DETACH - c3ref/constlist.html capi3ref.html
  • SQLITE_DIRECT_OVERFLOW_READ - changes.html#version_3_7_9 releaselog/3_7_9.html
  • SQLITE_DISABLE_DIRSYNC - footprint.html#relfootprint
  • SQLITE_DISABLE_LFS - footprint.html#relfootprint
  • SQLITE_DONE - c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupstep c3ref/constlist.html c3ref/data_count.html c3ref/reset.html c3ref/step.html c3ref/wal_hook.html capi3ref.html capi3ref.html#sqlite3_data_count capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_step capi3ref.html#sqlite3_wal_hook capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupstep
  • SQLITE_DROP_INDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TEMP_INDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TEMP_TABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TEMP_TRIGGER - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TEMP_VIEW - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_TRIGGER - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_VIEW - c3ref/constlist.html capi3ref.html
  • SQLITE_DROP_VTABLE - c3ref/constlist.html capi3ref.html
  • SQLITE_EMPTY - c3ref/constlist.html capi3ref.html
  • SQLITE_ENABLE_8_3_NAMES - shortnames.html
  • SQLITE_ENABLE_ATOMIC_WRITE - footprint.html#relfootprint
  • SQLITE_ENABLE_COLUMN_METADATA - c3ref/column_database_name.html c3ref/table_column_metadata.html capi3ref.html#sqlite3_column_database_name capi3ref.html#sqlite3_table_column_metadata footprint.html#relfootprint
  • SQLITE_ENABLE_FTS3 - footprint.html#relfootprint fts3.html#section_2 howtocompile.html#cli
  • SQLITE_ENABLE_FTS3_PARENTHESIS - changes.html#version_3_6_8 fts3.html#section_2 releaselog/3_6_8.html
  • SQLITE_ENABLE_FTS4 - footprint.html#relfootprint
  • SQLITE_ENABLE_IOTRACE - footprint.html#relfootprint
  • SQLITE_ENABLE_MEMORY_MANAGEMENT - c3ref/release_memory.html c3ref/soft_heap_limit64.html capi3ref.html#sqlite3_release_memory capi3ref.html#sqlite3_soft_heap_limit64 changes.html#version_3_7_3 footprint.html#relfootprint malloc.html#memstatus releaselog/3_7_3.html
  • SQLITE_ENABLE_MEMSYS3 - c3ref/c_config_getmalloc.html#sqliteconfigheap capi3ref.html#sqliteconfigheap footprint.html#relfootprint malloc.html#memsysx
  • SQLITE_ENABLE_MEMSYS5 - c3ref/c_config_getmalloc.html#sqliteconfigheap capi3ref.html#sqliteconfigheap footprint.html#relfootprint malloc.html#memsys5
  • SQLITE_ENABLE_RTREE - footprint.html#relfootprint howtocompile.html#cli rtree.html
  • SQLITE_ENABLE_STAT2 - changes.html#version_3_6_18 changes.html#version_3_6_20 changes.html#version_3_7_6 changes.html#version_3_7_9 news.html oldnews.html releaselog/3_6_18.html releaselog/3_6_20.html releaselog/3_7_6.html releaselog/3_7_9.html
  • SQLITE_ENABLE_STAT3 - c3ref/prepare.html capi3ref.html#sqlite3_prepare changes.html#version_3_7_9 compile.html#enable_stat2 footprint.html#relfootprint lang_analyze.html news.html optoverview.html#rangequery releaselog/3_7_9.html
  • SQLITE_ENABLE_UNLOCK_NOTIFY - c3ref/unlock_notify.html capi3ref.html#sqlite3_unlock_notify footprint.html#relfootprint unlock_notify.html
  • SQLITE_ENABLE_UPDATE_DELETE_LIMIT - changes.html#version_3_6_4 footprint.html#relfootprint howtocompile.html#amal lang_createtrigger.html lang_delete.html lang_update.html releaselog/3_6_4.html
  • SQLITE_ERROR - c3ref/blob_read.html c3ref/blob_write.html c3ref/c_config_getmalloc.html#sqliteconfiggetmutex c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigmutex c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/c_config_getmalloc.html#sqliteconfigsinglethread c3ref/constlist.html c3ref/load_extension.html c3ref/prepare.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_blob_read capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3_load_extension capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_step capi3ref.html#sqliteconfiggetmutex capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigmutex capi3ref.html#sqliteconfigserialized capi3ref.html#sqliteconfigsinglethread changes.html#version_3_6_15 changes.html#version_3_6_5 changes.html#version_3_7_5 releaselog/3_6_15.html releaselog/3_6_5.html releaselog/3_7_5.html vtab.html#xconnect vtab.html#xcreate
  • SQLITE_FAIL - c3ref/constlist.html c3ref/vtab_on_conflict.html capi3ref.html capi3ref.html#sqlite3_vtab_on_conflict
  • SQLITE_FCNTL_CHUNK_SIZE - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE changes.html#version_3_7_1 releaselog/3_7_1.html
  • SQLITE_FCNTL_FILE_POINTER - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE changes.html#version_3_7_4 releaselog/3_7_4.html
  • SQLITE_FCNTL_LOCKSTATE - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/file_control.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_file_control capi3ref.html#sqlite3_io_methods
  • SQLITE_FCNTL_OVERWRITE - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE changes.html#version_3_7_9 releaselog/3_7_9.html
  • SQLITE_FCNTL_PERSIST_WAL - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE
  • SQLITE_FCNTL_SIZE_HINT - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE changes.html#version_3_7_6_1 news.html releaselog/3_7_6_1.html
  • SQLITE_FCNTL_SYNC_OMITTED - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE changes.html#version_3_7_5 releaselog/3_7_5.html
  • SQLITE_FCNTL_WIN32_AV_RETRY - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE
  • SQLITE_FLOAT - c3ref/column_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_column_blob
  • SQLITE_FORMAT - c3ref/constlist.html capi3ref.html
  • SQLITE_FULL - 34to35.html autoinc.html c3ref/constlist.html c3ref/get_autocommit.html capi3ref.html capi3ref.html#sqlite3_get_autocommit changes.html#version_3_5_1 faq.html#q1 lang_transaction.html releaselog/3_5_1.html vfs.html
  • SQLITE_FUNCTION - c3ref/constlist.html capi3ref.html
  • SQLITE_GET_LOCKPROXYFILE - c3ref/constlist.html capi3ref.html
  • SQLITE_HAVE_ISNAN - changes.html#version_3_6_14 releaselog/3_6_14.html
  • SQLITE_IGNORE - c3ref/c_fail.html c3ref/constlist.html c3ref/set_authorizer.html c3ref/vtab_on_conflict.html capi3ref.html capi3ref.html#SQLITE_FAIL capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_vtab_on_conflict lang_delete.html#truncateopt
  • SQLITE_INDEX_CONSTRAINT_EQ - c3ref/constlist.html c3ref/index_info.html capi3ref.html capi3ref.html#sqlite3_index_info
  • SQLITE_INDEX_CONSTRAINT_GE - c3ref/constlist.html capi3ref.html
  • SQLITE_INDEX_CONSTRAINT_GT - c3ref/constlist.html capi3ref.html
  • SQLITE_INDEX_CONSTRAINT_LE - c3ref/constlist.html capi3ref.html
  • SQLITE_INDEX_CONSTRAINT_LT - c3ref/constlist.html capi3ref.html
  • SQLITE_INDEX_CONSTRAINT_MATCH - c3ref/constlist.html capi3ref.html
  • SQLITE_INSERT - c3ref/constlist.html c3ref/update_hook.html capi3ref.html capi3ref.html#sqlite3_update_hook
  • SQLITE_INTEGER - c3ref/column_blob.html c3ref/constlist.html c3ref/value_blob.html capi3ref.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_value_blob
  • SQLITE_INTERNAL - c3ref/constlist.html capi3ref.html
  • SQLITE_INTERRUPT - c3ref/constlist.html c3ref/get_autocommit.html c3ref/interrupt.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_interrupt capi3ref.html#sqlite3_step lang_transaction.html
  • SQLITE_IOCAP_ATOMIC - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods compile.html#enable_atomic_write
  • SQLITE_IOCAP_ATOMIC16K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC1K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC2K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC32K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC4K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC512 - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC64K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_ATOMIC8K - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_SAFE_APPEND - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_SEQUENTIAL - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR - 34to35.html c3ref/constlist.html c3ref/free.html c3ref/get_autocommit.html capi3ref.html capi3ref.html#sqlite3_free capi3ref.html#sqlite3_get_autocommit changes.html#version_3_5_1 lang_transaction.html releaselog/3_5_1.html
  • SQLITE_IOERR_ACCESS - 35to36.html c3ref/backup_finish.html#sqlite3backupstep c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3backupstep
  • SQLITE_IOERR_BLOCKED - c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_busy_handler capi3ref.html#sqlite3_busy_timeout
  • SQLITE_IOERR_CHECKRESERVEDLOCK - 35to36.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_CLOSE - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_DELETE - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_DIR_CLOSE - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_DIR_FSYNC - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_FSTAT - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_FSYNC - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_LOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_NOMEM - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_RDLOCK - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_READ - 34to35.html c3ref/c_abort.html c3ref/constlist.html capi3ref.html capi3ref.html#SQLITE_ABORT
  • SQLITE_IOERR_SEEK - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_SHMLOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_SHMMAP - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_SHMOPEN - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_SHMSIZE - c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_SHORT_READ - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_TRUNCATE - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_UNLOCK - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_IOERR_WRITE - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_LAST_ERRNO - c3ref/constlist.html capi3ref.html
  • SQLITE_LIMIT_ATTACHED - c3ref/constlist.html capi3ref.html lang_attach.html limits.html#max_attached
  • SQLITE_LIMIT_COLUMN - c3ref/constlist.html capi3ref.html lang_createindex.html limits.html#max_column
  • SQLITE_LIMIT_COMPOUND_SELECT - c3ref/constlist.html capi3ref.html limits.html#max_compound_select
  • SQLITE_LIMIT_EXPR_DEPTH - c3ref/constlist.html capi3ref.html limits.html#max_expr_depth
  • SQLITE_LIMIT_FUNCTION_ARG - c3ref/constlist.html c3ref/create_function.html capi3ref.html capi3ref.html#sqlite3_create_function limits.html#max_function_arg
  • SQLITE_LIMIT_LENGTH - c3ref/constlist.html capi3ref.html limits.html limits.html#max_length
  • SQLITE_LIMIT_LIKE_PATTERN_LENGTH - c3ref/constlist.html capi3ref.html limits.html#max_like_pattern_length
  • SQLITE_LIMIT_SQL_LENGTH - c3ref/constlist.html capi3ref.html limits.html#max_sql_length
  • SQLITE_LIMIT_TRIGGER_DEPTH - c3ref/constlist.html capi3ref.html foreignkeys.html#fk_actions pragma.html#pragma_recursive_triggers
  • SQLITE_LIMIT_VARIABLE_NUMBER - c3ref/bind_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_bind_blob lang_expr.html#varparam limits.html#max_variable_number
  • SQLITE_LIMIT_VDBE_OP - c3ref/constlist.html capi3ref.html
  • SQLITE_LOCK_EXCLUSIVE - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_io_methods
  • SQLITE_LOCK_NONE - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_io_methods
  • SQLITE_LOCK_PENDING - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_io_methods
  • SQLITE_LOCK_RESERVED - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_io_methods
  • SQLITE_LOCK_SHARED - 34to35.html c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_io_methods
  • SQLITE_LOCKED - c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupstep c3ref/constlist.html c3ref/unlock_notify.html capi3ref.html capi3ref.html#sqlite3_unlock_notify capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupstep compile.html#omit_autoreset
  • SQLITE_LOCKED_SHAREDCACHE - c3ref/constlist.html capi3ref.html
  • SQLITE_MAX_ATTACHED - changes.html#version_3_7_6 compile.html#yystackdepth releaselog/3_7_6.html
  • SQLITE_MAX_COLUMN - compile.html#yystackdepth lang_createtable.html#tablecoldef
  • SQLITE_MAX_COMPOUND_SELECT - compile.html#yystackdepth
  • SQLITE_MAX_EXPR_DEPTH - compile.html#yystackdepth
  • SQLITE_MAX_FUNCTION_ARG - compile.html#yystackdepth
  • SQLITE_MAX_LENGTH - compile.html#yystackdepth datatype3.html#affname lang_createtable.html#tablecoldef
  • SQLITE_MAX_LIKE_PATTERN_LENGTH - compile.html#yystackdepth
  • SQLITE_MAX_PAGE_COUNT - compile.html#yystackdepth
  • SQLITE_MAX_SQL_LENGTH - compile.html#yystackdepth
  • SQLITE_MAX_TRIGGER_DEPTH - foreignkeys.html#fk_actions pragma.html#pragma_recursive_triggers
  • SQLITE_MAX_VARIABLE_NUMBER - compile.html#yystackdepth lang_expr.html#varparam
  • SQLITE_MEMDEBUG - malloc.html malloc.html#memdebug testing.html#memtesting
  • SQLITE_MISMATCH - c3ref/constlist.html capi3ref.html
  • SQLITE_MISUSE - c3ref/bind_blob.html c3ref/constlist.html c3ref/create_function.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_create_function capi3ref.html#sqlite3_step changes.html#version_3_5_3 changes.html#version_3_6_15 compile.html#omit_autoreset releaselog/3_5_3.html releaselog/3_6_15.html
  • SQLITE_MUTEX_FAST - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_RECURSIVE - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_LRU - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_LRU2 - c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_MASTER - 34to35.html c3ref/constlist.html c3ref/mem_methods.html capi3ref.html capi3ref.html#sqlite3_mem_methods
  • SQLITE_MUTEX_STATIC_MEM - 34to35.html c3ref/constlist.html c3ref/mem_methods.html capi3ref.html capi3ref.html#sqlite3_mem_methods
  • SQLITE_MUTEX_STATIC_MEM2 - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_OPEN - c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_PMEM - c3ref/constlist.html capi3ref.html
  • SQLITE_MUTEX_STATIC_PRNG - 34to35.html c3ref/constlist.html capi3ref.html
  • SQLITE_NOLFS - c3ref/constlist.html capi3ref.html
  • SQLITE_NOMEM - c3ref/backup_finish.html#sqlite3backupstep c3ref/bind_blob.html c3ref/column_blob.html c3ref/constlist.html c3ref/free.html c3ref/get_autocommit.html c3ref/soft_heap_limit64.html capi3ref.html capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_free capi3ref.html#sqlite3_get_autocommit capi3ref.html#sqlite3_soft_heap_limit64 capi3ref.html#sqlite3backupstep lang_transaction.html malloc.html malloc.html#nofrag
  • SQLITE_NOTADB - c3ref/constlist.html capi3ref.html
  • SQLITE_NOTFOUND - c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods changes.html#version_3_7_5 releaselog/3_7_5.html
  • SQLITE_NULL - c3ref/column_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_column_blob
  • SQLITE_OK - 34to35.html c3ref/backup_finish.html#sqlite3backupfinish c3ref/backup_finish.html#sqlite3backupstep c3ref/bind_blob.html c3ref/blob_open.html c3ref/c_busy_recovery.html c3ref/c_deny.html c3ref/config.html c3ref/constlist.html c3ref/enable_shared_cache.html c3ref/initialize.html c3ref/intro.html c3ref/load_extension.html c3ref/mutex_alloc.html c3ref/open.html c3ref/prepare.html c3ref/reset.html c3ref/set_authorizer.html c3ref/wal_hook.html capi3ref.html capi3ref.html#SQLITE_BUSY_RECOVERY capi3ref.html#SQLITE_DENY capi3ref.html#sqlite3_bind_blob capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_config capi3ref.html#sqlite3_enable_shared_cache capi3ref.html#sqlite3_initialize capi3ref.html#sqlite3_load_extension capi3ref.html#sqlite3_mutex_alloc capi3ref.html#sqlite3_open capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_wal_hook capi3ref.html#sqlite3backupfinish capi3ref.html#sqlite3backupstep vtab.html#xcolumn vtab.html#xconnect vtab.html#xcreate vtab.html#xfilter vtab.html#xnext vtab.html#xopen vtab.html#xrename vtab.html#xrowid vtab.html#xupdate
  • SQLITE_OMIT_ALTERTABLE - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_ANALYZE - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_ATTACH - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_AUTHORIZATION - footprint.html#relfootprint
  • SQLITE_OMIT_AUTOINCREMENT - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_AUTOINIT - c3ref/initialize.html capi3ref.html#sqlite3_initialize footprint.html#relfootprint
  • SQLITE_OMIT_AUTOMATIC_INDEX - footprint.html#relfootprint optoverview.html#autoindex
  • SQLITE_OMIT_AUTORESET - c3ref/step.html capi3ref.html#sqlite3_step changes.html#version_3_7_5 footprint.html#relfootprint releaselog/3_7_5.html
  • SQLITE_OMIT_AUTOVACUUM - footprint.html#relfootprint
  • SQLITE_OMIT_BETWEEN_OPTIMIZATION - footprint.html#relfootprint
  • SQLITE_OMIT_BLOB_LITERAL - footprint.html#relfootprint
  • SQLITE_OMIT_BTREECOUNT - footprint.html#relfootprint
  • SQLITE_OMIT_BUILTIN_TEST - footprint.html#relfootprint
  • SQLITE_OMIT_CAST - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_CHECK - footprint.html#relfootprint
  • SQLITE_OMIT_COMPILEOPTION_DIAGS - c3ref/compileoption_get.html capi3ref.html#sqlite3_compileoption_get footprint.html#relfootprint
  • SQLITE_OMIT_COMPLETE - footprint.html#relfootprint
  • SQLITE_OMIT_COMPOUND_SELECT - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_DATETIME_FUNCS - footprint.html#relfootprint
  • SQLITE_OMIT_DECLTYPE - footprint.html#relfootprint
  • SQLITE_OMIT_DEPRECATED - footprint.html#relfootprint pragma.html#pragma_count_changes pragma.html#pragma_default_cache_size pragma.html#pragma_empty_result_callbacks pragma.html#pragma_full_column_names pragma.html#pragma_short_column_names pragma.html#pragma_temp_store_directory
  • SQLITE_OMIT_EXPLAIN - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_FLAG_PRAGMAS - footprint.html#relfootprint
  • SQLITE_OMIT_FLOATING_POINT - changes.html#version_3_3_3 changes.html#version_3_6_23 footprint.html#relfootprint oldnews.html releaselog/3_3_0.html releaselog/3_6_23.html
  • SQLITE_OMIT_FOREIGN_KEY - footprint.html#relfootprint foreignkeys.html#fk_enable howtocompile.html#amal
  • SQLITE_OMIT_GET_TABLE - footprint.html#relfootprint
  • SQLITE_OMIT_INCRBLOB - footprint.html#relfootprint
  • SQLITE_OMIT_INTEGRITY_CHECK - footprint.html#relfootprint
  • SQLITE_OMIT_LIKE_OPTIMIZATION - footprint.html#relfootprint
  • SQLITE_OMIT_LOAD_EXTENSION - 34to35.html footprint.html#relfootprint howtocompile.html#cli
  • SQLITE_OMIT_LOCALTIME - footprint.html#relfootprint
  • SQLITE_OMIT_LOOKASIDE - footprint.html#relfootprint
  • SQLITE_OMIT_MEMORYDB - footprint.html#relfootprint
  • SQLITE_OMIT_OR_OPTIMIZATION - footprint.html#relfootprint
  • SQLITE_OMIT_PAGER_PRAGMAS - footprint.html#relfootprint
  • SQLITE_OMIT_PRAGMA - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_PROGRESS_CALLBACK - footprint.html#relfootprint
  • SQLITE_OMIT_QUICKBALANCE - footprint.html#relfootprint
  • SQLITE_OMIT_REINDEX - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_SCHEMA_PRAGMAS - footprint.html#relfootprint
  • SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS - footprint.html#relfootprint
  • SQLITE_OMIT_SHARED_CACHE - footprint.html#relfootprint
  • SQLITE_OMIT_SUBQUERY - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_TCL_VARIABLE - footprint.html#relfootprint
  • SQLITE_OMIT_TEMPDB - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_TRACE - footprint.html#relfootprint
  • SQLITE_OMIT_TRIGGER - footprint.html#relfootprint foreignkeys.html#fk_enable howtocompile.html#amal
  • SQLITE_OMIT_TRUNCATE_OPTIMIZATION - changes.html#version_3_6_4 changes.html#version_3_6_5 footprint.html#relfootprint lang_delete.html#truncateopt releaselog/3_6_4.html releaselog/3_6_5.html
  • SQLITE_OMIT_UTF16 - footprint.html#relfootprint
  • SQLITE_OMIT_VACUUM - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_VIEW - footprint.html#relfootprint howtocompile.html#amal
  • SQLITE_OMIT_VIRTUALTABLE - footprint.html#relfootprint fts3.html#section_2 howtocompile.html#amal
  • SQLITE_OMIT_WAL - footprint.html#relfootprint
  • SQLITE_OMIT_WSD - footprint.html#relfootprint
  • SQLITE_OMIT_XFER_OPT - footprint.html#relfootprint
  • SQLITE_OPEN_AUTOPROXY - c3ref/constlist.html capi3ref.html
  • SQLITE_OPEN_CREATE - 34to35.html c3ref/constlist.html c3ref/open.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3_open capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_DELETEONCLOSE - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_EXCLUSIVE - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_FULLMUTEX - c3ref/constlist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_open compile.html#threadsafe threadsafe.html
  • SQLITE_OPEN_MAIN_DB - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_MAIN_JOURNAL - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_MASTER_JOURNAL - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_NOMUTEX - 35to36.html c3ref/constlist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_open changes.html#version_3_6_1 compile.html#threadsafe releaselog/3_6_0.html threadsafe.html
  • SQLITE_OPEN_PRIVATECACHE - c3ref/constlist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_open changes.html#version_3_6_18 releaselog/3_6_18.html sharedcache.html
  • SQLITE_OPEN_READONLY - 34to35.html c3ref/constlist.html c3ref/intro.html c3ref/open.html c3ref/open.html#coreuriqueryparameters c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#coreuriqueryparameters capi3ref.html#sqlite3_open capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_READWRITE - 34to35.html c3ref/constlist.html c3ref/open.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3_open capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_SHAREDCACHE - c3ref/constlist.html c3ref/open.html capi3ref.html capi3ref.html#sqlite3_open changes.html#version_3_6_18 releaselog/3_6_18.html sharedcache.html
  • SQLITE_OPEN_SUBJOURNAL - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_TEMP_DB - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_TEMP_JOURNAL - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_TRANSIENT_DB - 34to35.html c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OPEN_URI - c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/constlist.html c3ref/open.html c3ref/open.html#urifilenamesinsqlite3open capi3ref.html capi3ref.html#sqlite3_open capi3ref.html#sqliteconfiguri capi3ref.html#urifilenamesinsqlite3open uri.html
  • SQLITE_OPEN_WAL - c3ref/constlist.html c3ref/vfs.html#sqlite3vfsxopen capi3ref.html capi3ref.html#sqlite3vfsxopen
  • SQLITE_OS_OTHER - c3ref/initialize.html capi3ref.html#sqlite3_initialize
  • SQLITE_PERM - c3ref/constlist.html capi3ref.html
  • SQLITE_PRAGMA - c3ref/constlist.html capi3ref.html
  • SQLITE_PROTOCOL - c3ref/constlist.html capi3ref.html
  • SQLITE_RANGE - c3ref/bind_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_bind_blob
  • SQLITE_READ - c3ref/constlist.html c3ref/set_authorizer.html capi3ref.html capi3ref.html#sqlite3_set_authorizer
  • SQLITE_READONLY - c3ref/backup_finish.html#sqlite3backupstep c3ref/blob_write.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_blob_write capi3ref.html#sqlite3backupstep
  • SQLITE_READONLY_CANTLOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_READONLY_RECOVERY - c3ref/constlist.html capi3ref.html
  • SQLITE_REINDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_REPLACE - c3ref/constlist.html c3ref/vtab_on_conflict.html capi3ref.html capi3ref.html#sqlite3_vtab_on_conflict
  • SQLITE_ROLLBACK - c3ref/c_abort.html c3ref/c_deny.html c3ref/constlist.html c3ref/vtab_on_conflict.html capi3ref.html capi3ref.html#SQLITE_ABORT capi3ref.html#SQLITE_DENY capi3ref.html#sqlite3_vtab_on_conflict
  • SQLITE_ROW - c3ref/column_blob.html c3ref/constlist.html c3ref/data_count.html c3ref/reset.html c3ref/step.html c3ref/wal_hook.html capi3ref.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_data_count capi3ref.html#sqlite3_reset capi3ref.html#sqlite3_step capi3ref.html#sqlite3_wal_hook compile.html#omit_autoreset
  • SQLITE_SAVEPOINT - c3ref/constlist.html capi3ref.html
  • SQLITE_SCHEMA - c3ref/constlist.html c3ref/prepare.html c3ref/step.html capi3ref.html capi3ref.html#sqlite3_prepare capi3ref.html#sqlite3_step changes.html#version_3_7_7_1 compile.html#max_schema_retry faq.html#q15 news.html pragma.html#pragma_foreign_keys pragma.html#pragma_recursive_triggers releaselog/3_7_7_1.html
  • SQLITE_SECURE_DELETE - changes.html#version_3_6_21 faq.html#q20 pragma.html#pragma_secure_delete releaselog/3_6_21.html
  • SQLITE_SELECT - c3ref/constlist.html capi3ref.html
  • SQLITE_SET_LOCKPROXYFILE - c3ref/constlist.html capi3ref.html
  • SQLITE_SHM_EXCLUSIVE - c3ref/constlist.html capi3ref.html
  • SQLITE_SHM_LOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_SHM_NLOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_SHM_SHARED - c3ref/constlist.html capi3ref.html
  • SQLITE_SHM_UNLOCK - c3ref/constlist.html capi3ref.html
  • SQLITE_SOUNDEX - lang_corefunc.html#soundex
  • SQLITE_SOURCE_ID - c3ref/constlist.html c3ref/libversion.html capi3ref.html capi3ref.html#sqlite3_libversion changes.html#version_3_6_18 releaselog/3_6_18.html
  • sqlite_source_id - c3ref/c_source_id.html c3ref/libversion.html capi3ref.html#SQLITE_SOURCE_ID capi3ref.html#sqlite3_libversion changes.html#version_3_6_18 releaselog/3_6_18.html
  • SQLITE_STATIC - c3ref/bind_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_bind_blob
  • SQLITE_STATUS_MALLOC_COUNT - c3ref/constlist.html capi3ref.html
  • SQLITE_STATUS_MALLOC_SIZE - c3ref/constlist.html capi3ref.html
  • SQLITE_STATUS_MEMORY_USED - c3ref/constlist.html capi3ref.html malloc.html#memstatus malloc.html#nofrag
  • SQLITE_STATUS_PAGECACHE_OVERFLOW - c3ref/constlist.html capi3ref.html
  • SQLITE_STATUS_PAGECACHE_SIZE - c3ref/constlist.html capi3ref.html changes.html#version_3_6_1 releaselog/3_6_1.html
  • SQLITE_STATUS_PAGECACHE_USED - c3ref/constlist.html capi3ref.html
  • SQLITE_STATUS_PARSER_STACK - c3ref/constlist.html capi3ref.html compile.html#yytrackmaxstackdepth
  • SQLITE_STATUS_SCRATCH_OVERFLOW - c3ref/constlist.html capi3ref.html
  • SQLITE_STATUS_SCRATCH_SIZE - c3ref/constlist.html capi3ref.html changes.html#version_3_6_1 releaselog/3_6_1.html
  • SQLITE_STATUS_SCRATCH_USED - c3ref/constlist.html capi3ref.html
  • SQLITE_STMTSTATUS counter - c3ref/stmt_status.html capi3ref.html#sqlite3_stmt_status
  • SQLITE_STMTSTATUS counters - c3ref/stmt_status.html capi3ref.html#sqlite3_stmt_status
  • SQLITE_STMTSTATUS_AUTOINDEX - c3ref/constlist.html capi3ref.html
  • SQLITE_STMTSTATUS_FULLSCAN_STEP - c3ref/constlist.html capi3ref.html lang_indexedby.html
  • SQLITE_STMTSTATUS_SORT - c3ref/constlist.html capi3ref.html lang_indexedby.html
  • SQLITE_SYNC_DATAONLY - c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_SYNC_FULL - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_SYNC_NORMAL - 34to35.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html capi3ref.html#sqlite3_io_methods
  • SQLITE_TEMP_STORE - 35to36.html inmemorydb.html#temp_db pragma.html#pragma_temp_store tempfiles.html#otheropt tempfiles.html#tempstore
  • SQLITE_TESTCTRL_ALWAYS - c3ref/constlist.html capi3ref.html testing.html#defensivecode
  • SQLITE_TESTCTRL_ASSERT - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_BITVEC_TEST - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_FAULT_INSTALL - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_FIRST - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_ISKEYWORD - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_LAST - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_LOCALTIME_FAULT - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_OPTIMIZATIONS - c3ref/constlist.html capi3ref.html testing.html#disopttest
  • SQLITE_TESTCTRL_PENDING_BYTE - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_PGHDRSZ - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_PRNG_RESET - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_PRNG_RESTORE - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_PRNG_SAVE - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_RESERVE - c3ref/constlist.html capi3ref.html
  • SQLITE_TESTCTRL_SCRATCHMALLOC - c3ref/constlist.html capi3ref.html
  • SQLITE_TEXT - c3ref/column_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_column_blob
  • SQLITE_THREADSAFE - c3ref/c_config_getmalloc.html#sqliteconfiggetmutex c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigmutex c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/c_config_getmalloc.html#sqliteconfigsinglethread c3ref/threadsafe.html c3ref/value.html capi3ref.html#sqlite3_threadsafe capi3ref.html#sqlite3_value capi3ref.html#sqliteconfiggetmutex capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigmutex capi3ref.html#sqliteconfigserialized capi3ref.html#sqliteconfigsinglethread threadsafe.html
  • SQLITE_TOOBIG - c3ref/constlist.html capi3ref.html
  • SQLITE_TRANSACTION - c3ref/constlist.html capi3ref.html
  • SQLITE_TRANSIENT - c3ref/bind_blob.html c3ref/constlist.html capi3ref.html capi3ref.html#sqlite3_bind_blob
  • SQLITE_UPDATE - c3ref/constlist.html c3ref/update_hook.html capi3ref.html capi3ref.html#sqlite3_update_hook
  • SQLITE_USE_URI - c3ref/c_config_getmalloc.html#sqliteconfiguri c3ref/open.html#urifilenamesinsqlite3open capi3ref.html#sqliteconfiguri capi3ref.html#urifilenamesinsqlite3open uri.html
  • SQLITE_UTF16 - c3ref/constlist.html c3ref/create_collation.html capi3ref.html capi3ref.html#sqlite3_create_collation
  • SQLITE_UTF16_ALIGNED - c3ref/constlist.html c3ref/create_collation.html capi3ref.html capi3ref.html#sqlite3_create_collation
  • SQLITE_UTF16BE - c3ref/collation_needed.html c3ref/constlist.html c3ref/create_collation.html capi3ref.html capi3ref.html#sqlite3_collation_needed capi3ref.html#sqlite3_create_collation
  • SQLITE_UTF16LE - c3ref/collation_needed.html c3ref/constlist.html c3ref/create_collation.html capi3ref.html capi3ref.html#sqlite3_collation_needed capi3ref.html#sqlite3_create_collation
  • SQLITE_UTF8 - c3ref/collation_needed.html c3ref/constlist.html c3ref/create_collation.html c3ref/create_function.html capi3ref.html capi3ref.html#sqlite3_collation_needed capi3ref.html#sqlite3_create_collation capi3ref.html#sqlite3_create_function
  • SQLITE_VERSION - c3ref/c_source_id.html c3ref/constlist.html c3ref/libversion.html capi3ref.html capi3ref.html#SQLITE_SOURCE_ID capi3ref.html#sqlite3_libversion
  • sqlite_version - c3ref/c_source_id.html c3ref/libversion.html capi3ref.html#SQLITE_SOURCE_ID capi3ref.html#sqlite3_libversion
  • SQLITE_VERSION_NUMBER - c3ref/c_source_id.html c3ref/constlist.html c3ref/libversion.html capi3ref.html capi3ref.html#SQLITE_SOURCE_ID capi3ref.html#sqlite3_libversion fileformat2.html#database_header fileformat2.html#validfor
  • SQLITE_VTAB_CONSTRAINT_SUPPORT - c3ref/constlist.html c3ref/vtab_config.html capi3ref.html capi3ref.html#sqlite3_vtab_config
  • SQLITE_ZERO_MALLOC - changes.html#version_3_6_5 malloc.html#memsysx releaselog/3_6_5.html
  • status parameters - c3ref/status.html capi3ref.html#sqlite3_status
  • storage class - lang_expr.html#castexpr
  • strategies - eqp.html
  • substr - changes.html#version_3_6_21 releaselog/3_6_21.html
  • synchronous - tempfiles.html#tempdb
  • synchronous pragma - c3ref/c_sync_dataonly.html capi3ref.html#SQLITE_SYNC_DATAONLY howtocorrupt.html#delhotjrnl
  • syntax diagrams - lang.html
  • table-constraint - lang_createtable.html lang_createtable.html#constraints lang_createtable.html#tablecoldef
  • Tcl extension - lang_expr.html#varparam
  • TCL Interface - changes.html#version_3_6_19 releaselog/3_6_19.html
  • TCL test suite - malloc.html
  • TEA tarball - howtocompile.html#tcl
  • temp_store pragma - inmemorydb.html#temp_db tempfiles.html#otheropt tempfiles.html#tempstore
  • temp_store_directory - pragma.html#pragma_temp_store
  • temp_store_directory pragma - c3ref/c_access_exists.html c3ref/temp_directory.html capi3ref.html#SQLITE_ACCESS_EXISTS capi3ref.html#sqlite3_temp_directory
  • temporary disk files - shortnames.html
  • temporary tables - pragma.html#pragma_temp_store pragma.html#pragma_temp_store_directory
  • tempstore - compile.html#temp_store
  • test coverage - about.html changes.html#version_3_6_17 faq.html#q17 features.html malloc.html oldnews.html releaselog/3_6_17.html support.html#prosupport th3.html
  • test suite - limits.html tclsqlite.html
  • testcase macros - testing.html#fuzztesting
  • tested - news.html
  • testing - howtocorrupt.html#delhotjrnl malloc.html news.html
  • TH3 - malloc.html oldnews.html support.html#prosupport testing.html#coverage testing.html#stmtvbr testing.html#tcl
  • Things That Can Go Wrong - lockingv3.html#how_to_corrupt
  • threading mode - c3ref/c_config_getmalloc.html#sqliteconfigmultithread c3ref/c_config_getmalloc.html#sqliteconfigserialized c3ref/c_config_getmalloc.html#sqliteconfigsinglethread c3ref/db_mutex.html c3ref/errcode.html c3ref/open.html c3ref/threadsafe.html capi3ref.html#sqlite3_db_mutex capi3ref.html#sqlite3_errcode capi3ref.html#sqlite3_open capi3ref.html#sqlite3_threadsafe capi3ref.html#sqliteconfigmultithread capi3ref.html#sqliteconfigserialized capi3ref.html#sqliteconfigsinglethread compile.html#threadsafe
  • three test harnesses - th3.html
  • ticket #2273 - changes.html#version_3_3_14 releaselog/3_3_14.html
  • Ticket #2321 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2323 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2324 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2334 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2339 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2341 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2345 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2349 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2354 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2364 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2391 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2403 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2404 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2409 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • ticket #2418 - changes.html#version_3_4_0 releaselog/3_4_0.html
  • Ticket #2565 - changes.html#version_3_4_2 releaselog/3_4_2.html
  • Ticket #2640 - changes.html#version_3_5_1 releaselog/3_5_1.html
  • Ticket #2686 - changes.html#version_3_5_1 releaselog/3_5_1.html
  • Ticket #2804 - changes.html#version_3_5_4 releaselog/3_5_4.html
  • ticket #2822 - changes.html#version_3_5_4 releaselog/3_5_4.html
  • ticket #2832 - changes.html#version_3_5_4 releaselog/3_5_4.html
  • ticket #2913 - changes.html#version_3_5_6 releaselog/3_5_6.html
  • ticket #2927 - changes.html#version_3_5_7 releaselog/3_5_7.html
  • Ticket #2943 - changes.html#version_3_5_7 releaselog/3_5_7.html
  • ticket #3015 - changes.html#version_3_5_9 releaselog/3_5_9.html
  • Ticket #3060 - changes.html#version_3_5_9 releaselog/3_5_9.html
  • Ticket #3093 - changes.html#version_3_5_9 releaselog/3_5_9.html
  • Ticket #3497 - changes.html#version_3_6_6 releaselog/3_6_6.html
  • Ticket #3581 - changes.html#version_3_6_9 releaselog/3_6_9.html
  • Ticket #3584 - changes.html#version_3_6_10 releaselog/3_6_10.html
  • ticket #3841 - changes.html#version_3_6_14_1 releaselog/3_6_14_1.html
  • ticket #3844 - changes.html#version_3_6_14_1 releaselog/3_6_14_1.html
  • Ticket #3858 - changes.html#version_3_6_14_1 releaselog/3_6_14_1.html
  • Ticket #3879 - changes.html#version_3_6_14_2 releaselog/3_6_14_2.html
  • tokenizer - fts3.html#fts4 fts3.html#fts4aux fts3.html#section_1_4 fts3.html#section_2
  • total_changes SQL function - c3ref/total_changes.html capi3ref.html#sqlite3_total_changes
  • truncate optimization - c3ref/set_authorizer.html c3ref/update_hook.html capi3ref.html#sqlite3_set_authorizer capi3ref.html#sqlite3_update_hook changes.html#version_3_6_21 changes.html#version_3_6_5 releaselog/3_6_21.html releaselog/3_6_5.html
  • type-name - lang_createtable.html
  • unprotected sqlite3_value - c3ref/column_blob.html c3ref/result_blob.html c3ref/value_blob.html capi3ref.html#sqlite3_column_blob capi3ref.html#sqlite3_result_blob capi3ref.html#sqlite3_value_blob
  • UPDATE - c3ref/blob_open.html c3ref/changes.html c3ref/column_count.html c3ref/total_changes.html capi3ref.html#sqlite3_blob_open capi3ref.html#sqlite3_changes capi3ref.html#sqlite3_column_count capi3ref.html#sqlite3_total_changes changes.html#version_3_6_4 compile.html#enable_update_delete_limit fts3.html#fts4 lang.html lang_analyze.html lang_createtable.html#constraints lang_createtrigger.html lang_createview.html lang_indexedby.html pragma.html#pragma_count_changes pragma.html#pragma_writable_schema releaselog/3_6_4.html rtree.html vtab.html vtab.html#xupdate
  • update-stmt - lang_update.html
  • update-stmt-limited - lang_update.html
  • upper - faq.html#q18
  • URI filename - c3ref/open.html#urifilenamesinsqlite3open capi3ref.html#urifilenamesinsqlite3open compile.html#use_uri lang_attach.html
  • URI filename examples - uri.html#coreqp
  • URI filenames - c3ref/open.html#urifilenamesinsqlite3open capi3ref.html#urifilenamesinsqlite3open changes.html#version_3_7_7 compile.html#enable_8_3_names news.html releaselog/3_7_7.html shortnames.html vfs.html
  • URI filenames in sqlite3_open - uri.html#coreqp
  • user_version - compile.html#omit_schema_version_pragmas
  • user_version pragma - fileformat2.html#database_header fileformat2.html#filesize
  • Using the SQLite Online Backup API - c3ref/backup.html c3ref/backup_finish.html capi3ref.html#sqlite3_backup capi3ref.html#sqlite3_backup_finish
  • Using the SQLite Unlock Notification Feature - c3ref/unlock_notify.html capi3ref.html#sqlite3_unlock_notify compile.html#enable_unlock_notify
  • VACUUM - changes.html#version_3_5_8 changes.html#version_3_7_5 changes.html#version_3_7_9 compile.html#omit_vacuum faq.html#q20 fts3.html#fts4 howtocorrupt.html#delhotjrnl lang.html news.html pragma.html#pragma_auto_vacuum pragma.html#pragma_page_size releaselog/3_5_8.html releaselog/3_7_5.html releaselog/3_7_9.html tempfiles.html#vacuumdb wal.html
  • vacuum-stmt - lang_vacuum.html
  • variable-length integer - fileformat2.html#record_format
  • varint - fileformat2.html#record_format
  • Version 3.0.0 - lockingv3.html
  • version 3.3.0 - lang_createindex.html lang_createtable.html#ckconst
  • version 3.3.1 - faq.html#q6
  • Version 3.3.14 - changes.html#version_3_3_16 releaselog/3_3_16.html
  • Version 3.3.15 - changes.html#version_3_3_16 releaselog/3_3_16.html
  • version 3.5.0 - 35to36.html custombuild.html fts3.html#fts4
  • version 3.5.8 - changes.html#version_3_5_9 releaselog/3_5_9.html
  • version 3.6.0 - compile.html#default_file_format
  • version 3.6.1 - malloc.html#lookaside malloc.html#memsysx
  • version 3.6.12 - changes.html#version_3_6_13 releaselog/3_6_13.html
  • version 3.6.14 - changes.html#version_3_6_14_2 oldnews.html releaselog/3_6_14_2.html
  • version 3.6.14.1 - oldnews.html
  • version 3.6.14.2 - oldnews.html
  • version 3.6.15 - oldnews.html
  • version 3.6.16 - oldnews.html
  • version 3.6.17 - sharedcache.html vtab.html
  • version 3.6.19 - oldnews.html pragma.html#pragma_foreign_keys
  • version 3.6.20 - oldnews.html
  • version 3.6.21 - oldnews.html
  • Version 3.6.21 - amalgamation.html
  • version 3.6.22 - oldnews.html
  • version 3.6.23 - oldnews.html
  • version 3.6.23.1 - oldnews.html
  • version 3.6.4 - changes.html#version_3_6_6_1 oldnews.html releaselog/3_6_6_1.html
  • version 3.6.5 - lang_delete.html#truncateopt malloc.html#memsysx oldnews.html
  • version 3.6.6 - changes.html#version_3_6_6_2 oldnews.html releaselog/3_6_6_2.html
  • version 3.6.6.2 - oldnews.html
  • version 3.6.7 - oldnews.html
  • version 3.7.0 - atomiccommit.html fileformat2.html#walformat news.html wal.html
  • version 3.7.0.1 - news.html
  • version 3.7.1 - news.html
  • version 3.7.2 - news.html
  • version 3.7.3 - news.html
  • version 3.7.4 - download.html#encoding fts3.html#fts4 news.html
  • version 3.7.5 - news.html
  • version 3.7.6 - news.html
  • version 3.7.6.1 - news.html
  • version 3.7.6.2 - news.html
  • version 3.7.6.3 - news.html
  • version 3.7.7 - news.html uri.html vtab.html#xsavepoint
  • version 3.7.7.1 - news.html
  • version 3.7.8 - compile.html#omit_merge_sort news.html testing.html
  • version 3.7.9 - news.html
  • version-valid-for number - fileformat2.html#database_header fileformat2.html#filesize
  • VFS - atomiccommit.html#hardware c3ref/c_fcntl_chunk_size.html c3ref/open.html#coreuriqueryparameters c3ref/vfs.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#coreuriqueryparameters capi3ref.html#sqlite3_vfs compile.html#enable_locking_style fileformat2.html#validfor pragma.html#pragma_synchronous selfcontained.html testing.html#coverage testing.html#crashtesting uri.html uri.html#coreqp wal.html wal.html#fast wal.html#readonly
  • VFSes - news.html th3.html wal.html#noshm
  • views - lang_createtrigger.html#instead_of_trigger
  • virtual machine instructions - c3ref/progress_handler.html capi3ref.html#sqlite3_progress_handler lang_explain.html
  • virtual table - c3ref/c_fail.html c3ref/c_index_constraint_eq.html c3ref/c_vtab_constraint_support.html c3ref/create_module.html c3ref/index_info.html c3ref/last_insert_rowid.html c3ref/overload_function.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html capi3ref.html#SQLITE_FAIL capi3ref.html#SQLITE_INDEX_CONSTRAINT_EQ capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT capi3ref.html#sqlite3_create_module capi3ref.html#sqlite3_index_info capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_overload_function capi3ref.html#sqlite3_vtab capi3ref.html#sqlite3_vtab_config capi3ref.html#sqlite3_vtab_cursor capi3ref.html#sqlite3_vtab_on_conflict changes.html#version_3_7_9 lang_createvtab.html releaselog/3_7_9.html
  • virtual table module - c3ref/create_module.html c3ref/declare_vtab.html c3ref/index_info.html c3ref/overload_function.html c3ref/vtab.html c3ref/vtab_cursor.html capi3ref.html#sqlite3_create_module capi3ref.html#sqlite3_declare_vtab capi3ref.html#sqlite3_index_info capi3ref.html#sqlite3_overload_function capi3ref.html#sqlite3_vtab capi3ref.html#sqlite3_vtab_cursor
  • virtual tables - c3ref/last_insert_rowid.html c3ref/module.html c3ref/stmt_readonly.html capi3ref.html#sqlite3_last_insert_rowid capi3ref.html#sqlite3_module capi3ref.html#sqlite3_stmt_readonly changes.html#version_3_6_14 changes.html#version_3_6_17 changes.html#version_3_7_7 fileformat2.html#serialtype fts3.html#section_1_4 news.html oldnews.html releaselog/3_6_14.html releaselog/3_6_17.html releaselog/3_7_7.html
  • WAL - c3ref/c_fcntl_chunk_size.html c3ref/wal_checkpoint.html capi3ref.html#SQLITE_FCNTL_CHUNK_SIZE capi3ref.html#sqlite3_wal_checkpoint changes.html#version_3_7_0 changes.html#version_3_7_3 changes.html#version_3_7_4 changes.html#version_3_7_7 compile.html#default_wal_autocheckpoint compile.html#omit_wal fileformat2.html#database_header fileformat2.html#walformat howtocorrupt.html#delhotjrnl lang_attach.html lockingv3.html#rollback news.html pragma.html#pragma_locking_mode pragma.html#pragma_page_size pragma.html#pragma_synchronous releaselog/3_7_0.html releaselog/3_7_3.html releaselog/3_7_4.html releaselog/3_7_7.html
  • WAL mode - changes.html#version_3_7_6_3 fileformat2.html news.html releaselog/3_7_6_3.html
  • WAL read algorithm - fileformat2.html#walindexformat wal.html#readonly
  • WAL without shared memory - pragma.html#pragma_locking_mode wal.html
  • wal-index - vfs.html wal.html wal.html#bkwrds wal.html#readonly
  • wal_autocheckpoint pragma - c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_hook.html capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_checkpoint capi3ref.html#sqlite3_wal_hook wal.html#fast
  • wal_checkpoint pragma - c3ref/wal_checkpoint.html capi3ref.html#sqlite3_wal_checkpoint changes.html#version_3_7_6 releaselog/3_7_6.html wal.html#fast
  • WHERE clause - lang_select.html
  • write-ahead log - atomiccommit.html c3ref/wal_autocheckpoint.html c3ref/wal_hook.html capi3ref.html#sqlite3_wal_autocheckpoint capi3ref.html#sqlite3_wal_hook compile.html#omit_wal howtocorrupt.html#delhotjrnl lang_vacuum.html news.html pragma.html#pragma_journal_mode pragma.html#pragma_wal_autocheckpoint pragma.html#pragma_wal_checkpoint shortnames.html shortnames.html#db83corrupt
  • xBegin - vtab.html#xcommit vtab.html#xrollback vtab.html#xsync
  • xBestIndex - c3ref/index_info.html capi3ref.html#sqlite3_index_info vtab.html#xfilter
  • xColumn - c3ref/vtab_cursor.html capi3ref.html#sqlite3_vtab_cursor vtab.html#xfilter
  • xCommit - vtab.html#xBegin vtab.html#xsync
  • xConnect - c3ref/c_vtab_constraint_support.html c3ref/create_module.html c3ref/declare_vtab.html c3ref/vtab_config.html capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT capi3ref.html#sqlite3_create_module capi3ref.html#sqlite3_declare_vtab capi3ref.html#sqlite3_vtab_config lang_createvtab.html vtab.html#xbestindex vtab.html#xcreate vtab.html#xdisconnect vtab.html#xupdate
  • xCreate - c3ref/c_vtab_constraint_support.html c3ref/create_module.html c3ref/declare_vtab.html c3ref/vtab_config.html capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT capi3ref.html#sqlite3_create_module capi3ref.html#sqlite3_declare_vtab capi3ref.html#sqlite3_vtab_config lang_createvtab.html vtab.html vtab.html#sqlite3_module.xDestroy vtab.html#xbestindex vtab.html#xconnect vtab.html#xupdate
  • xDestroy - vtab.html#sqlite3_module.xDestroy vtab.html#xdisconnect
  • xDisconnect - vtab.html#sqlite3_module.xDestroy vtab.html#xdisconnect
  • xEof - c3ref/vtab_cursor.html capi3ref.html#sqlite3_vtab_cursor vtab.html#xfilter vtab.html#xnext
  • xFilter - c3ref/index_info.html c3ref/vtab_cursor.html capi3ref.html#sqlite3_index_info capi3ref.html#sqlite3_vtab_cursor vtab.html#xbestindex vtab.html#xeof vtab.html#xnext vtab.html#xopen
  • xFindFunction - c3ref/overload_function.html capi3ref.html#sqlite3_overload_function
  • xNext - c3ref/index_info.html c3ref/vtab_cursor.html capi3ref.html#sqlite3_index_info capi3ref.html#sqlite3_vtab_cursor vtab.html#xeof vtab.html#xfilter
  • xRelease - changes.html#version_3_7_7 releaselog/3_7_7.html
  • xRollback - vtab.html#xBegin vtab.html#xsync
  • xRollbackTo - changes.html#version_3_7_7 releaselog/3_7_7.html
  • xRowid - c3ref/vtab_cursor.html capi3ref.html#sqlite3_vtab_cursor vtab.html#xfilter
  • xSavepoint - changes.html#version_3_7_7 releaselog/3_7_7.html
  • xUpdate - c3ref/c_vtab_constraint_support.html c3ref/vtab_on_conflict.html capi3ref.html#SQLITE_VTAB_CONSTRAINT_SUPPORT capi3ref.html#sqlite3_vtab_on_conflict
  • YYSTACKDEPTH - compile.html#yytrackmaxstackdepth
  • YYTRACKMAXSTACKDEPTH - c3ref/c_status_malloc_count.html#sqlitestatusparserstack capi3ref.html#sqlitestatusparserstack
  • zeroblob - c3ref/blob_open.html capi3ref.html#sqlite3_blob_open


Keyword Crossreference

Choose any three.
About Sitemap Documentation Download License News Support
  • 34to35 - 34to35.html
  • 35to36 - 35to36.html
  • abs - lang_corefunc.html#abs
  • abs SQL function - lang_corefunc.html#abs
  • affinities - datatype3.html#affinity
  • affinity - datatype3.html#affinity
  • agg_max - lang_aggfunc.html#maxggunc
  • agg_min - lang_aggfunc.html#minggunc
  • aggfunc - lang_aggfunc.html
  • Aggregate Functions - lang_aggfunc.html
  • alphabetical listing of SQLite documents - doclist.html
  • ALTER - lang_altertable.html
  • ALTER TABLE - lang_altertable.html
  • alter-table-stmt - syntaxdiagrams.html#alter-table-stmt
  • alter-table-stmt syntax diagram - syntaxdiagrams.html#alter-table-stmt
  • amalgamation - amalgamation.html
  • amalgamation tarball - download.html
  • ANALYZE - lang_analyze.html
  • analyze-stmt - syntaxdiagrams.html#analyze-stmt
  • analyze-stmt syntax diagram - syntaxdiagrams.html#analyze-stmt
  • application file-format - whentouse.html#appfileformat
  • application-defined SQL function - c3ref/create_function.html
  • application-defined SQL functions - c3ref/create_function.html
  • asynchronous I/O backend - asyncvfs.html
  • asynchronous VFS - asyncvfs.html
  • Atomic Commit - atomiccommit.html
  • atomic commit - atomiccommit.html
  • ATTACH - lang_attach.html
  • ATTACH DATABASE - lang_attach.html
  • attach-stmt - syntaxdiagrams.html#attach-stmt
  • attach-stmt syntax diagram - syntaxdiagrams.html#attach-stmt
  • auto_vacuum - pragma.html#pragma_auto_vacuum
  • auto_vacuum pragma - pragma.html#pragma_auto_vacuum
  • autocommit mode - c3ref/get_autocommit.html
  • AUTOINCREMENT - autoinc.html
  • Automatic indexing - optoverview.html#autoindex
  • automatic indexing - optoverview.html#autoindex
  • automatic_index - pragma.html#pragma_automatic_index
  • automatic_index pragma - pragma.html#pragma_automatic_index
  • avg - lang_aggfunc.html#avg
  • avg aggregate function - lang_aggfunc.html#avg
  • backup API - backup.html
  • BEGIN - lang_transaction.html
  • BEGIN TRANSACTION - lang_transaction.html
  • begin-stmt - syntaxdiagrams.html#begin-stmt
  • begin-stmt syntax diagram - syntaxdiagrams.html#begin-stmt
  • BETWEEN - lang_expr.html#between
  • BINARY - datatype3.html#collation
  • BINARY collating function - datatype3.html#collation
  • binary operators - lang_expr.html#binaryops
  • BLOB handle - c3ref/blob.html
  • BLOB handles - c3ref/blob.html
  • books about SQLite - books.html
  • boolean datatype - datatype3.html#boolean
  • boolean expression - lang_expr.html#booleanexpr
  • bound parameter - lang_expr.html#varparam
  • bound parameters - lang_expr.html#varparam
  • btree design - btreemodule.html
  • build product names - download.html#encoding
  • building the amalgamation - howtocompile.html#amal
  • built-in memory allocators - malloc.html#altalloc
  • C-API function list - c3ref/funclist.html
  • C-language Interface - c3ref/intro.html
  • cache_size - pragma.html#pragma_cache_size
  • cache_size pragma - pragma.html#pragma_cache_size
  • capi3ref - c3ref/intro.html
  • capi3ref_funclist - c3ref/funclist.html
  • CASE expression - lang_expr.html#case
  • case_sensitive_like - pragma.html#pragma_case_sensitive_like
  • case_sensitive_like pragma - pragma.html#pragma_case_sensitive_like
  • CAST expression - lang_expr.html#castexpr
  • categorical listing of SQLite documents - docs.html
  • cell format summary - fileformat2.html#cellformat
  • cell payload - fileformat2.html#cell_payload
  • change counter - fileformat2.html#chngctr
  • changes - lang_corefunc.html#changes
  • changes SQL function - lang_corefunc.html#changes
  • CHECK - lang_createtable.html#ckconst
  • CHECK constraint - lang_createtable.html#ckconst
  • CHECK constraints - lang_createtable.html#ckconst
  • checkpoint - wal.html#ckpt
  • checkpoint_fullfsync - pragma.html#pragma_checkpoint_fullfsync
  • checkpoint_fullfsync pragma - pragma.html#pragma_checkpoint_fullfsync
  • checkpointed - wal.html#ckpt
  • checkpointing - wal.html#ckpt
  • child key - foreignkeys.html#parentchild
  • child table - foreignkeys.html#parentchild
  • cintro - cintro.html
  • CLI - sqlite.html
  • coalesce - lang_corefunc.html#coalesce
  • coalesce SQL function - lang_corefunc.html#coalesce
  • COLLATE operator - lang_expr.html#collateop
  • collating function - datatype3.html#collation
  • collating sequence - datatype3.html#collation
  • collation - datatype3.html#collation
  • collation_list - pragma.html#pragma_collation_list
  • collation_list pragma - pragma.html#pragma_collation_list
  • column access functions - c3ref/column_blob.html
  • column affinity - datatype3.html#affinity
  • column definition - lang_createtable.html#tablecoldef
  • column definitions - lang_createtable.html#tablecoldef
  • column-constraint - syntaxdiagrams.html#column-constraint
  • column-constraint syntax diagram - syntaxdiagrams.html#column-constraint
  • column-def - syntaxdiagrams.html#column-def
  • column-def syntax diagram - syntaxdiagrams.html#column-def
  • Command Line Interface - sqlite.html
  • command-line shell - sqlite.html
  • comment - lang_comment.html
  • comment-syntax - syntaxdiagrams.html#comment-syntax
  • comment-syntax syntax diagram - syntaxdiagrams.html#comment-syntax
  • comments - lang_comment.html
  • COMMIT - lang_transaction.html
  • commit-stmt - syntaxdiagrams.html#commit-stmt
  • commit-stmt syntax diagram - syntaxdiagrams.html#commit-stmt
  • comparison affinity rules - datatype3.html#compaff
  • comparison expressions - datatype3.html#comparisons
  • compile fts - fts3.html#section_2
  • compile-time options - compile.html
  • compile_options - pragma.html#pragma_compile_options
  • compile_options pragma - pragma.html#pragma_compile_options
  • compiling the CLI - howtocompile.html#cli
  • compiling the TCL interface - howtocompile.html#tcl
  • compound query - lang_select.html#compound
  • compound select - lang_select.html#compound
  • compound-operator - syntaxdiagrams.html#compound-operator
  • compound-operator syntax diagram - syntaxdiagrams.html#compound-operator
  • compressed FTS4 content - fts3.html#*fts4compression
  • configuration option - c3ref/c_config_getmalloc.html
  • conflict clause - lang_conflict.html
  • conflict-clause - syntaxdiagrams.html#conflict-clause
  • conflict-clause syntax diagram - syntaxdiagrams.html#conflict-clause
  • constraints - lang_createtable.html#constraints
  • Core Functions - lang_corefunc.html
  • core URI query parameters - c3ref/open.html#coreuriqueryparameters
  • corefunc - lang_corefunc.html
  • count - lang_aggfunc.html#count
  • count aggregate function - lang_aggfunc.html#count
  • count_changes - pragma.html#pragma_count_changes
  • count_changes pragma - pragma.html#pragma_count_changes
  • covering index - queryplanner.html#covidx
  • covering indices - queryplanner.html#covidx
  • CREATE INDEX - lang_createindex.html
  • CREATE TABLE - lang_createtable.html
  • CREATE TRIGGER - lang_createtrigger.html
  • CREATE VIEW - lang_createview.html
  • CREATE VIRTUAL TABLE - lang_createvtab.html
  • create-index-stmt - syntaxdiagrams.html#create-index-stmt
  • create-index-stmt syntax diagram - syntaxdiagrams.html#create-index-stmt
  • create-table-stmt - syntaxdiagrams.html#create-table-stmt
  • create-table-stmt syntax diagram - syntaxdiagrams.html#create-table-stmt
  • create-trigger-stmt - syntaxdiagrams.html#create-trigger-stmt
  • create-trigger-stmt syntax diagram - syntaxdiagrams.html#create-trigger-stmt
  • create-view-stmt - syntaxdiagrams.html#create-view-stmt
  • create-view-stmt syntax diagram - syntaxdiagrams.html#create-view-stmt
  • create-virtual-table-stmt - syntaxdiagrams.html#create-virtual-table-stmt
  • create-virtual-table-stmt syntax diagram - syntaxdiagrams.html#create-virtual-table-stmt
  • custom builds - custombuild.html
  • custom r-tree queries - rtree.html#customquery
  • database connection - c3ref/sqlite3.html
  • database connections - c3ref/sqlite3.html
  • database corruption caused by inconsistent use of 83 filenames - shortnames.html#db83corrupt
  • database header - fileformat2.html#database_header
  • Database Object Name Resolution - lang_naming.html
  • database_list - pragma.html#pragma_database_list
  • database_list pragma - pragma.html#pragma_database_list
  • datatype - datatype3.html
  • date and time datatype - datatype3.html#datetime
  • Date And Time Functions - lang_datefunc.html
  • date SQL function - lang_datefunc.html
  • datefunc - lang_datefunc.html
  • datetime SQL function - lang_datefunc.html
  • debugging memory allocator - malloc.html#memdebug
  • default memory allocator - malloc.html#defaultalloc
  • default_cache_size - pragma.html#pragma_default_cache_size
  • default_cache_size pragma - pragma.html#pragma_default_cache_size
  • DELETE - lang_delete.html
  • delete-stmt - syntaxdiagrams.html#delete-stmt
  • delete-stmt syntax diagram - syntaxdiagrams.html#delete-stmt
  • delete-stmt-limited - syntaxdiagrams.html#delete-stmt-limited
  • delete-stmt-limited syntax diagram - syntaxdiagrams.html#delete-stmt-limited
  • DELETEs - lang_delete.html
  • deleting a hot journal - howtocorrupt.html#delhotjrnl
  • deprecated - c3ref/experimental.html
  • DETACH - lang_detach.html
  • DETACH DATABASE - lang_detach.html
  • detach-stmt - syntaxdiagrams.html#detach-stmt
  • detach-stmt syntax diagram - syntaxdiagrams.html#detach-stmt
  • DISTINCT - lang_select.html#distinct
  • doclist - doclist.html
  • download page - download.html
  • DROP INDEX - lang_dropindex.html
  • DROP TABLE - lang_droptable.html
  • DROP TRIGGER - lang_droptrigger.html
  • DROP VIEW - lang_dropview.html
  • drop-index-stmt - syntaxdiagrams.html#drop-index-stmt
  • drop-index-stmt syntax diagram - syntaxdiagrams.html#drop-index-stmt
  • drop-table-stmt - syntaxdiagrams.html#drop-table-stmt
  • drop-table-stmt syntax diagram - syntaxdiagrams.html#drop-table-stmt
  • drop-trigger-stmt - syntaxdiagrams.html#drop-trigger-stmt
  • drop-trigger-stmt syntax diagram - syntaxdiagrams.html#drop-trigger-stmt
  • drop-view-stmt - syntaxdiagrams.html#drop-view-stmt
  • drop-view-stmt syntax diagram - syntaxdiagrams.html#drop-view-stmt
  • dynamic typing - datatype3.html
  • empty_result_callbacks - pragma.html#pragma_empty_result_callbacks
  • empty_result_callbacks pragma - pragma.html#pragma_empty_result_callbacks
  • encoding - pragma.html#pragma_encoding
  • encoding pragma - pragma.html#pragma_encoding
  • enhanced query syntax - fts3.html#section_3_1
  • error code - c3ref/c_abort.html
  • error codes - c3ref/c_abort.html
  • ESCAPE - lang_expr.html#like
  • EXCLUSIVE - lockingv3.html#excl_lock
  • EXCLUSIVE lock - lockingv3.html#excl_lock
  • exclusive lock - lockingv3.html#excl_lock
  • EXISTS operator - lang_expr.html#in_op
  • experimental - c3ref/experimental.html
  • experimental memory allocators - malloc.html#memsysx
  • EXPLAIN - lang_explain.html
  • EXPLAIN QUERY PLAN - eqp.html
  • explain query plan - eqp.html
  • expr - syntaxdiagrams.html#expr
  • expr syntax diagram - syntaxdiagrams.html#expr
  • expression - lang_expr.html
  • expression affinity - datatype3.html#expraff
  • expression syntax - lang_expr.html
  • extended error code - c3ref/c_busy_recovery.html
  • extended error codes - c3ref/c_busy_recovery.html
  • extended result code - c3ref/c_busy_recovery.html
  • extended result codes - c3ref/c_busy_recovery.html
  • file format - fileformat2.html
  • file I/O - fileio.html
  • file locking and concurrency control - lockingv3.html
  • file locking states - lockingv3.html#locking
  • flattening optimization - optoverview.html#flattening
  • footprint - footprint.html
  • foreign key actions - foreignkeys.html#fk_actions
  • foreign key constraint - foreignkeys.html
  • FOREIGN KEY constraints - foreignkeys.html
  • foreign key constraints - foreignkeys.html
  • foreign key constraints are enabled - foreignkeys.html#fk_enable
  • foreign-key-clause - syntaxdiagrams.html#foreign-key-clause
  • foreign-key-clause syntax diagram - syntaxdiagrams.html#foreign-key-clause
  • foreign_key_list - pragma.html#pragma_foreign_key_list
  • foreign_key_list pragma - pragma.html#pragma_foreign_key_list
  • foreign_keys - pragma.html#pragma_foreign_keys
  • foreign_keys pragma - pragma.html#pragma_foreign_keys
  • free-page list - fileformat2.html#freelist
  • freelist - fileformat2.html#freelist
  • freelist_count - pragma.html#pragma_freelist_count
  • freelist_count pragma - pragma.html#pragma_freelist_count
  • FROM clause - lang_select.html#fromclause
  • FTS auxiliary functions - fts3.html#snippet
  • FTS hidden column - fts3.html#hiddencol
  • FTS MATCH - fts3.html#section_3
  • FTS shadow tables - fts3.html#*shadowtab
  • FTS3 - fts3.html
  • fts3 - fts3.html
  • FTS4 - fts3.html#fts4
  • fts4 compress option - fts3.html#section_6_1
  • FTS4 options - fts3.html#fts4_options
  • FTS4 order option - fts3.html#fts4order
  • FTS4 prefix option - fts3.html#fts4prefix
  • fts4 prefix option - fts3.html#section_6_2
  • fts4aux - fts3.html#fts4aux
  • full-text search - fts3.html
  • full_column_names - pragma.html#pragma_full_column_names
  • full_column_names pragma - pragma.html#pragma_full_column_names
  • fullfsync - pragma.html#pragma_fullfsync
  • fullfsync pragma - pragma.html#pragma_fullfsync
  • function creation routines - c3ref/create_function.html
  • GLOB - lang_expr.html#glob
  • glob - lang_corefunc.html#glob
  • glob SQL function - lang_corefunc.html#glob
  • GROUP BY - lang_select.html#resultset
  • group_concat - lang_aggfunc.html#groupconcat
  • group_concat aggregate function - lang_aggfunc.html#groupconcat
  • hex - lang_corefunc.html#hex
  • hex SQL function - lang_corefunc.html#hex
  • hidden column - vtab.html#hiddencol
  • host parameter - c3ref/bind_blob.html
  • host parameter name - c3ref/bind_blob.html
  • host parameters - c3ref/bind_blob.html
  • hot journal - lockingv3.html#hotjrnl
  • how to compile - howtocompile.html
  • how to corrupt - howtocorrupt.html
  • How To Corrupt Your Database Files - lockingv3.html#how_to_corrupt
  • ifnull - lang_corefunc.html#ifnull
  • ifnull SQL function - lang_corefunc.html#ifnull
  • ignore_check_constraints - pragma.html#pragma_ignore_check_constraints
  • ignore_check_constraints pragma - pragma.html#pragma_ignore_check_constraints
  • IN operator - lang_expr.html#in_op
  • in-header database size - fileformat2.html#filesize
  • in-memory database - inmemorydb.html
  • in-memory databases - inmemorydb.html
  • incremental_vacuum - pragma.html#pragma_incremental_vacuum
  • incremental_vacuum pragma - pragma.html#pragma_incremental_vacuum
  • index_info - pragma.html#pragma_index_info
  • index_info pragma - pragma.html#pragma_index_info
  • index_list - pragma.html#pragma_index_list
  • index_list pragma - pragma.html#pragma_index_list
  • INDEXED BY - lang_indexedby.html
  • indexed-column - syntaxdiagrams.html#indexed-column
  • indexed-column syntax diagram - syntaxdiagrams.html#indexed-column
  • indexing - queryplanner.html
  • indexing tutorial - queryplanner.html
  • INSERT - lang_insert.html
  • insert-stmt - syntaxdiagrams.html#insert-stmt
  • insert-stmt syntax diagram - syntaxdiagrams.html#insert-stmt
  • INSERTs - lang_insert.html
  • INSTEAD OF - lang_createtrigger.html#instead_of_trigger
  • INSTEAD OF trigger - lang_createtrigger.html#instead_of_trigger
  • INTEGER PRIMARY KEY - lang_createtable.html#rowid
  • integrity_check - pragma.html#pragma_integrity_check
  • integrity_check pragma - pragma.html#pragma_integrity_check
  • IS NOT operator - lang_expr.html#isisnot
  • IS operator - lang_expr.html#isisnot
  • join order - optoverview.html#table_order
  • join-constraint - syntaxdiagrams.html#join-constraint
  • join-constraint syntax diagram - syntaxdiagrams.html#join-constraint
  • join-op - syntaxdiagrams.html#join-op
  • join-op syntax diagram - syntaxdiagrams.html#join-op
  • join-source - syntaxdiagrams.html#join-source
  • join-source syntax diagram - syntaxdiagrams.html#join-source
  • journal_mode - pragma.html#pragma_journal_mode
  • journal_mode pragma - pragma.html#pragma_journal_mode
  • journal_size_limit - pragma.html#pragma_journal_size_limit
  • journal_size_limit pragma - pragma.html#pragma_journal_size_limit
  • julianday SQL function - lang_datefunc.html
  • keyword index - keyword_index.html
  • last_insert_rowid - lang_corefunc.html#last_insert_rowid
  • last_insert_rowid SQL function - lang_corefunc.html#last_insert_rowid
  • legacy_file_format - pragma.html#pragma_legacy_file_format
  • legacy_file_format pragma - pragma.html#pragma_legacy_file_format
  • length - lang_corefunc.html#length
  • length SQL function - lang_corefunc.html#length
  • library size - footprint.html
  • LIKE - lang_expr.html#like
  • like - lang_corefunc.html#like
  • LIKE optimization - optoverview.html#like_opt
  • like SQL function - lang_corefunc.html#like
  • limit categories - c3ref/c_limit_attached.html
  • limit category - c3ref/c_limit_attached.html
  • limits - limits.html
  • literal value - lang_expr.html#litvalue
  • literal-value - syntaxdiagrams.html#literal-value
  • literal-value syntax diagram - syntaxdiagrams.html#literal-value
  • load_extension - lang_corefunc.html#load_extension
  • load_extension SQL function - lang_corefunc.html#load_extension
  • locking_mode - pragma.html#pragma_locking_mode
  • locking_mode pragma - pragma.html#pragma_locking_mode
  • lookaside memory allocator - malloc.html#lookaside
  • lower - lang_corefunc.html#lower
  • lower SQL function - lang_corefunc.html#lower
  • ltrim - lang_corefunc.html#ltrim
  • ltrim SQL function - lang_corefunc.html#ltrim
  • mailing lists - support.html#mailinglists
  • MATCH - lang_expr.html#match
  • matchinfo - fts3.html#matchinfo
  • matchinfo_fts3 - fts3.html#*matchinfo_fts3
  • max - lang_corefunc.html#maxoreunc
  • max aggregate function - lang_aggfunc.html#maxggunc
  • max SQL function - lang_corefunc.html#maxoreunc
  • max_page_count - pragma.html#pragma_max_page_count
  • max_page_count pragma - pragma.html#pragma_max_page_count
  • maxAggFunc - lang_aggfunc.html#maxggunc
  • maxCoreFunc - lang_corefunc.html#maxoreunc
  • MC/DC - testing.html#mcdc
  • MC/DC testing - testing.html#mcdc
  • memory - inmemorydb.html
  • memory allocation - malloc.html
  • memory statistics - malloc.html#memstatus
  • memsys2 - malloc.html#memdebug
  • memsys5 - malloc.html#memsys5
  • min - lang_corefunc.html#minoreunc
  • min aggregate function - lang_aggfunc.html#minggunc
  • min SQL function - lang_corefunc.html#minoreunc
  • minAggFunc - lang_aggfunc.html#minggunc
  • minCoreFunc - lang_corefunc.html#minoreunc
  • NOCASE - datatype3.html#collation
  • NOCASE collating function - datatype3.html#collation
  • NOT EXISTS operator - lang_expr.html#in_op
  • NOT IN operator - lang_expr.html#in_op
  • NOT INDEXED - lang_indexedby.html
  • nullif - lang_corefunc.html#nullif
  • nullif SQL function - lang_corefunc.html#nullif
  • numeric-literal - syntaxdiagrams.html#numeric-literal
  • numeric-literal syntax diagram - syntaxdiagrams.html#numeric-literal
  • object resolution - lang_naming.html
  • offsets - fts3.html#offsets
  • omitfeatures - compile.html#omitfeatures
  • ON CONFLICT - lang_conflict.html
  • ON CONFLICT clause - lang_conflict.html
  • optimizer - optoverview.html
  • or optimization - optoverview.html#or_opt
  • or-connected-terms - queryplanner.html#or_in_where
  • order by - lang_select.html#orderby
  • ordering-term - syntaxdiagrams.html#ordering-term
  • ordering-term syntax diagram - syntaxdiagrams.html#ordering-term
  • OS backend - vfs.html
  • overflow page - fileformat2.html#ovflpgs
  • overflow pages - fileformat2.html#ovflpgs
  • page cache - c3ref/pcache_methods.html
  • page_count - pragma.html#pragma_page_count
  • page_count pragma - pragma.html#pragma_page_count
  • page_size - pragma.html#pragma_page_size
  • page_size pragma - pragma.html#pragma_page_size
  • pagecache memory allocator - malloc.html#pagecache
  • parameter - lang_expr.html#varparam
  • parameter binding - c3ref/bind_blob.html
  • parameters - lang_expr.html#varparam
  • parent key - foreignkeys.html#parentchild
  • parent table - foreignkeys.html#parentchild
  • parser_trace - pragma.html#pragma_parser_trace
  • parser_trace pragma - pragma.html#pragma_parser_trace
  • PENDING - lockingv3.html#pending_lock
  • PENDING lock - lockingv3.html#pending_lock
  • pending lock - lockingv3.html#pending_lock
  • permuted index - sitemap.html#pindex
  • porting SQLite - custombuild.html
  • PRAGMA - pragma.html#syntax
  • PRAGMA auto_vacuum - pragma.html#pragma_auto_vacuum
  • PRAGMA automatic_index - pragma.html#pragma_automatic_index
  • PRAGMA cache_size - pragma.html#pragma_cache_size
  • PRAGMA case_sensitive_like - pragma.html#pragma_case_sensitive_like
  • PRAGMA checkpoint_fullfsync - pragma.html#pragma_checkpoint_fullfsync
  • PRAGMA collation_list - pragma.html#pragma_collation_list
  • PRAGMA compile_options - pragma.html#pragma_compile_options
  • PRAGMA count_changes - pragma.html#pragma_count_changes
  • PRAGMA database_list - pragma.html#pragma_database_list
  • PRAGMA default_cache_size - pragma.html#pragma_default_cache_size
  • PRAGMA empty_result_callbacks - pragma.html#pragma_empty_result_callbacks
  • PRAGMA encoding - pragma.html#pragma_encoding
  • PRAGMA foreign_key_list - pragma.html#pragma_foreign_key_list
  • PRAGMA foreign_keys - pragma.html#pragma_foreign_keys
  • PRAGMA freelist_count - pragma.html#pragma_freelist_count
  • PRAGMA full_column_names - pragma.html#pragma_full_column_names
  • PRAGMA fullfsync - pragma.html#pragma_fullfsync
  • PRAGMA ignore_check_constraints - pragma.html#pragma_ignore_check_constraints
  • PRAGMA incremental_vacuum - pragma.html#pragma_incremental_vacuum
  • PRAGMA index_info - pragma.html#pragma_index_info
  • PRAGMA index_list - pragma.html#pragma_index_list
  • PRAGMA integrity_check - pragma.html#pragma_integrity_check
  • PRAGMA journal_mode - pragma.html#pragma_journal_mode
  • PRAGMA journal_size_limit - pragma.html#pragma_journal_size_limit
  • PRAGMA legacy_file_format - pragma.html#pragma_legacy_file_format
  • pragma list - pragma.html#toc
  • PRAGMA locking_mode - pragma.html#pragma_locking_mode
  • PRAGMA max_page_count - pragma.html#pragma_max_page_count
  • PRAGMA page_count - pragma.html#pragma_page_count
  • PRAGMA page_size - pragma.html#pragma_page_size
  • PRAGMA parser_trace - pragma.html#pragma_parser_trace
  • PRAGMA quick_check - pragma.html#pragma_quick_check
  • PRAGMA read_uncommitted - pragma.html#pragma_read_uncommitted
  • PRAGMA recursive_triggers - pragma.html#pragma_recursive_triggers
  • PRAGMA reverse_unordered_selects - pragma.html#pragma_reverse_unordered_selects
  • PRAGMA schema_version - pragma.html#pragma_schema_version
  • PRAGMA secure_delete - pragma.html#pragma_secure_delete
  • PRAGMA short_column_names - pragma.html#pragma_short_column_names
  • PRAGMA synchronous - pragma.html#pragma_synchronous
  • PRAGMA table_info - pragma.html#pragma_table_info
  • PRAGMA temp_store - pragma.html#pragma_temp_store
  • PRAGMA temp_store_directory - pragma.html#pragma_temp_store_directory
  • PRAGMA user_version - pragma.html#pragma_schema_version
  • PRAGMA vdbe_listing - pragma.html#pragma_vdbe_listing
  • PRAGMA vdbe_trace - pragma.html#pragma_vdbe_trace
  • PRAGMA wal_autocheckpoint - pragma.html#pragma_wal_autocheckpoint
  • PRAGMA wal_checkpoint - pragma.html#pragma_wal_checkpoint
  • PRAGMA writable_schema - pragma.html#pragma_writable_schema
  • pragma-stmt - syntaxdiagrams.html#pragma-stmt
  • pragma-stmt syntax diagram - syntaxdiagrams.html#pragma-stmt
  • pragma-value - syntaxdiagrams.html#pragma-value
  • pragma-value syntax diagram - syntaxdiagrams.html#pragma-value
  • prefix queries - fts3.html#termprefix
  • prefix query - fts3.html#termprefix
  • prepared statement - c3ref/stmt.html
  • prepared statements - c3ref/stmt.html
  • private branches - privatebranch.html
  • professional support - support.html#prosupport
  • protected sqlite3_value - c3ref/value.html
  • qualified-table-name - syntaxdiagrams.html#qualified-table-name
  • qualified-table-name syntax diagram - syntaxdiagrams.html#qualified-table-name
  • query - lang_select.html
  • query parameters with special meaning to SQLite - uri.html#coreqp
  • query planner - optoverview.html
  • Quick Start Guide - quickstart.html
  • quick_check - pragma.html#pragma_quick_check
  • quick_check pragma - pragma.html#pragma_quick_check
  • quickstart - quickstart.html
  • quote - lang_corefunc.html#quote
  • quote SQL function - lang_corefunc.html#quote
  • R-Tree extension - rtree.html
  • R-Trees - rtree.html
  • raise-function - syntaxdiagrams.html#raise-function
  • raise-function syntax diagram - syntaxdiagrams.html#raise-function
  • random - lang_corefunc.html#random
  • random SQL function - lang_corefunc.html#random
  • randomblob - lang_corefunc.html#randomblob
  • randomblob SQL function - lang_corefunc.html#randomblob
  • range query optimization - optoverview.html#rangequery
  • read-only WAL databases - wal.html#readonly
  • read_uncommitted - pragma.html#pragma_read_uncommitted
  • read_uncommitted pragma - pragma.html#pragma_read_uncommitted
  • record format - fileformat2.html#record_format
  • recursive_triggers - pragma.html#pragma_recursive_triggers
  • recursive_triggers pragma - pragma.html#pragma_recursive_triggers
  • REGEXP - lang_expr.html#regexp
  • REINDEX - lang_reindex.html
  • reindex-stmt - syntaxdiagrams.html#reindex-stmt
  • reindex-stmt syntax diagram - syntaxdiagrams.html#reindex-stmt
  • RELEASE - lang_savepoint.html
  • release-stmt - syntaxdiagrams.html#release-stmt
  • release-stmt syntax diagram - syntaxdiagrams.html#release-stmt
  • relfootprint - footprint.html#relfootprint
  • REPLACE - lang_replace.html
  • replace - lang_corefunc.html#replace
  • replace SQL function - lang_corefunc.html#replace
  • requirements - requirements.html
  • RESERVED - lockingv3.html#reserved_lock
  • RESERVED lock - lockingv3.html#reserved_lock
  • reserved lock - lockingv3.html#reserved_lock
  • result code - c3ref/c_abort.html
  • result codes - c3ref/c_abort.html
  • result-column - syntaxdiagrams.html#result-column
  • result-column syntax diagram - syntaxdiagrams.html#result-column
  • result-set expressions - lang_select.html#resultset
  • reverse_unordered_selects - pragma.html#pragma_reverse_unordered_selects
  • reverse_unordered_selects pragma - pragma.html#pragma_reverse_unordered_selects
  • Robson proof - malloc.html#nofrag
  • ROLLBACK - lang_transaction.html
  • rollback journal - lockingv3.html#rollback
  • rollback journal format - fileformat2.html#rollbackjournal
  • rollback-stmt - syntaxdiagrams.html#rollback-stmt
  • rollback-stmt syntax diagram - syntaxdiagrams.html#rollback-stmt
  • round - lang_corefunc.html#round
  • round SQL function - lang_corefunc.html#round
  • ROWID - lang_createtable.html#rowid
  • rowid - lang_createtable.html#rowid
  • RTREE - rtree.html
  • rtree - rtree.html
  • RTRIM - datatype3.html#collation
  • rtrim - lang_corefunc.html#rtrim
  • RTRIM collating function - datatype3.html#collation
  • rtrim SQL function - lang_corefunc.html#rtrim
  • rules for determining column affinity - datatype3.html#affname
  • SAVEPOINT - lang_savepoint.html
  • savepoint-stmt - syntaxdiagrams.html#savepoint-stmt
  • savepoint-stmt syntax diagram - syntaxdiagrams.html#savepoint-stmt
  • schema_version - pragma.html#pragma_schema_version
  • schema_version pragma - pragma.html#pragma_schema_version
  • scratch memory allocator - malloc.html#scratch
  • search application tips - fts3.html#appendix_a
  • second edition file format document - fileformat2.html
  • secure_delete - pragma.html#pragma_secure_delete
  • secure_delete pragma - pragma.html#pragma_secure_delete
  • segment btree - fts3.html#section_8
  • SELECT - lang_select.html
  • select-core - syntaxdiagrams.html#select-core
  • select-core syntax diagram - syntaxdiagrams.html#select-core
  • select-stmt - syntaxdiagrams.html#select-stmt
  • select-stmt syntax diagram - syntaxdiagrams.html#select-stmt
  • serial type - fileformat2.html#serialtype
  • serial types - fileformat2.html#serialtype
  • session - session/intro.html
  • Session Module C-API function list - session/funclist.html
  • Session Module C-language Interface - session/intro.html
  • session_funclist - session/funclist.html
  • SHARED - lockingv3.html#shared_lock
  • shared cache - c3ref/enable_shared_cache.html
  • shared cache mode - sharedcache.html
  • SHARED lock - lockingv3.html#shared_lock
  • shared lock - lockingv3.html#shared_lock
  • short filenames - shortnames.html
  • short_column_names - pragma.html#pragma_short_column_names
  • short_column_names pragma - pragma.html#pragma_short_column_names
  • signed-number - syntaxdiagrams.html#signed-number
  • signed-number syntax diagram - syntaxdiagrams.html#signed-number
  • simple fts queries - fts3.html#section_1_4
  • single-source - syntaxdiagrams.html#single-source
  • single-source syntax diagram - syntaxdiagrams.html#single-source
  • SLT - testing.html#slt
  • snippet - fts3.html#snippet
  • sorting - queryplanner.html#sorting
  • soundex - lang_corefunc.html#soundex
  • soundex SQL function - lang_corefunc.html#soundex
  • SQL keyword - lang_keywords.html
  • SQL keywords - lang_keywords.html
  • SQL Logic Tests - testing.html#slt
  • SQL parameter - c3ref/bind_blob.html
  • SQL parameters - c3ref/bind_blob.html
  • SQL statement compiler - c3ref/prepare.html
  • sql-stmt - syntaxdiagrams.html#sql-stmt
  • sql-stmt syntax diagram - syntaxdiagrams.html#sql-stmt
  • sql-stmt-list - syntaxdiagrams.html#sql-stmt-list
  • sql-stmt-list syntax diagram - syntaxdiagrams.html#sql-stmt-list
  • SQLite Consortium - consortium.html
  • SQLite Keywords - lang_keywords.html
  • SQLite Shared-Cache Mode - sharedcache.html
  • sqlite3 - c3ref/sqlite3.html
  • sqlite3_aggregate_context - c3ref/aggregate_context.html
  • sqlite3_aggregate_count - c3ref/aggregate_count.html
  • sqlite3_auto_extension - c3ref/auto_extension.html
  • sqlite3_backup - c3ref/backup.html
  • sqlite3_backup__remaining - c3ref/backup_finish.html#sqlite3backupremaining
  • sqlite3_backup_finish - c3ref/backup_finish.html#sqlite3backupfinish
  • sqlite3_backup_init - c3ref/backup_finish.html#sqlite3backupinit
  • sqlite3_backup_pagecount - c3ref/backup_finish.html#sqlite3backuppagecount
  • sqlite3_backup_remaining - c3ref/backup_finish.html
  • sqlite3_backup_step - c3ref/backup_finish.html#sqlite3backupstep
  • sqlite3_bind_blob - c3ref/bind_blob.html
  • sqlite3_bind_double - c3ref/bind_blob.html
  • sqlite3_bind_int - c3ref/bind_blob.html
  • sqlite3_bind_int64 - c3ref/bind_blob.html
  • sqlite3_bind_null - c3ref/bind_blob.html
  • sqlite3_bind_parameter_count - c3ref/bind_parameter_count.html
  • sqlite3_bind_parameter_index - c3ref/bind_parameter_index.html
  • sqlite3_bind_parameter_name - c3ref/bind_parameter_name.html
  • sqlite3_bind_text - c3ref/bind_blob.html
  • sqlite3_bind_text16 - c3ref/bind_blob.html
  • sqlite3_bind_value - c3ref/bind_blob.html
  • sqlite3_bind_zeroblob - c3ref/bind_blob.html
  • sqlite3_blob - c3ref/blob.html
  • sqlite3_blob_bytes - c3ref/blob_bytes.html
  • sqlite3_blob_close - c3ref/blob_close.html
  • sqlite3_blob_open - c3ref/blob_open.html
  • sqlite3_blob_read - c3ref/blob_read.html
  • sqlite3_blob_reopen - c3ref/blob_reopen.html
  • sqlite3_blob_write - c3ref/blob_write.html
  • sqlite3_busy_handler - c3ref/busy_handler.html
  • sqlite3_busy_timeout - c3ref/busy_timeout.html
  • sqlite3_changes - c3ref/changes.html
  • sqlite3_clear_bindings - c3ref/clear_bindings.html
  • sqlite3_close - c3ref/close.html
  • sqlite3_collation_needed - c3ref/collation_needed.html
  • sqlite3_collation_needed16 - c3ref/collation_needed.html
  • sqlite3_column_blob - c3ref/column_blob.html
  • sqlite3_column_bytes - c3ref/column_blob.html
  • sqlite3_column_bytes16 - c3ref/column_blob.html
  • sqlite3_column_count - c3ref/column_count.html
  • sqlite3_column_database_name - c3ref/column_database_name.html
  • sqlite3_column_database_name16 - c3ref/column_database_name.html
  • sqlite3_column_decltype - c3ref/column_decltype.html
  • sqlite3_column_decltype16 - c3ref/column_decltype.html
  • sqlite3_column_double - c3ref/column_blob.html
  • sqlite3_column_int - c3ref/column_blob.html
  • sqlite3_column_int64 - c3ref/column_blob.html
  • sqlite3_column_name - c3ref/column_name.html
  • sqlite3_column_name16 - c3ref/column_name.html
  • sqlite3_column_origin_name - c3ref/column_database_name.html
  • sqlite3_column_origin_name16 - c3ref/column_database_name.html
  • sqlite3_column_table_name - c3ref/column_database_name.html
  • sqlite3_column_table_name16 - c3ref/column_database_name.html
  • sqlite3_column_text - c3ref/column_blob.html
  • sqlite3_column_text16 - c3ref/column_blob.html
  • sqlite3_column_type - c3ref/column_blob.html
  • sqlite3_column_value - c3ref/column_blob.html
  • sqlite3_commit_hook - c3ref/commit_hook.html
  • sqlite3_compileoption_get - c3ref/compileoption_get.html
  • sqlite3_compileoption_used - c3ref/compileoption_get.html
  • sqlite3_complete - c3ref/complete.html
  • sqlite3_complete16 - c3ref/complete.html
  • sqlite3_config - c3ref/config.html
  • sqlite3_context - c3ref/context.html
  • sqlite3_context_db_handle - c3ref/context_db_handle.html
  • sqlite3_create_collation - c3ref/create_collation.html
  • sqlite3_create_collation16 - c3ref/create_collation.html
  • sqlite3_create_collation_v2 - c3ref/create_collation.html
  • sqlite3_create_function - c3ref/create_function.html
  • sqlite3_create_function16 - c3ref/create_function.html
  • sqlite3_create_function_v2 - c3ref/create_function.html
  • sqlite3_create_module - c3ref/create_module.html
  • sqlite3_create_module_v2 - c3ref/create_module.html
  • sqlite3_data_count - c3ref/data_count.html
  • sqlite3_db_config - c3ref/db_config.html
  • sqlite3_db_handle - c3ref/db_handle.html
  • sqlite3_db_mutex - c3ref/db_mutex.html
  • sqlite3_db_status - c3ref/db_status.html
  • sqlite3_declare_vtab - c3ref/declare_vtab.html
  • sqlite3_enable_load_extension - c3ref/enable_load_extension.html
  • sqlite3_enable_shared_cache - c3ref/enable_shared_cache.html
  • sqlite3_errcode - c3ref/errcode.html
  • sqlite3_errmsg - c3ref/errcode.html
  • sqlite3_errmsg16 - c3ref/errcode.html
  • sqlite3_exec - c3ref/exec.html
  • sqlite3_expired - c3ref/aggregate_count.html
  • sqlite3_extended_errcode - c3ref/errcode.html
  • sqlite3_extended_result_codes - c3ref/extended_result_codes.html
  • sqlite3_file - c3ref/file.html
  • sqlite3_file_control - c3ref/file_control.html
  • sqlite3_finalize - c3ref/finalize.html
  • sqlite3_free - c3ref/free.html
  • sqlite3_free_table - c3ref/free_table.html
  • sqlite3_get_autocommit - c3ref/get_autocommit.html
  • sqlite3_get_auxdata - c3ref/get_auxdata.html
  • sqlite3_get_table - c3ref/free_table.html
  • sqlite3_global_recover - c3ref/aggregate_count.html
  • sqlite3_index_info - c3ref/index_info.html
  • sqlite3_initialize - c3ref/initialize.html
  • sqlite3_int64 - c3ref/int64.html
  • sqlite3_interrupt - c3ref/interrupt.html
  • sqlite3_io_methods - c3ref/io_methods.html
  • sqlite3_last_insert_rowid - c3ref/last_insert_rowid.html
  • sqlite3_libversion - c3ref/libversion.html
  • sqlite3_libversion_number - c3ref/libversion.html
  • sqlite3_limit - c3ref/limit.html
  • sqlite3_load_extension - c3ref/load_extension.html
  • sqlite3_log - c3ref/log.html
  • sqlite3_malloc - c3ref/free.html
  • sqlite3_mem_methods - c3ref/mem_methods.html
  • sqlite3_memory_alarm - c3ref/aggregate_count.html
  • sqlite3_memory_highwater - c3ref/memory_highwater.html
  • sqlite3_memory_used - c3ref/memory_highwater.html
  • sqlite3_module - c3ref/module.html
  • sqlite3_module.xBegin - vtab.html#xBegin
  • sqlite3_module.xBestIndex - vtab.html#xbestindex
  • sqlite3_module.xClose - vtab.html#xclose
  • sqlite3_module.xColumn - vtab.html#xcolumn
  • sqlite3_module.xCommit - vtab.html#xcommit
  • sqlite3_module.xConnect - vtab.html#xconnect
  • sqlite3_module.xCreate - vtab.html#xcreate
  • sqlite3_module.xDisconnect - vtab.html#xdisconnect
  • sqlite3_module.xEof - vtab.html#xeof
  • sqlite3_module.xFilter - vtab.html#xfilter
  • sqlite3_module.xFindFunction - vtab.html#xfindfunction
  • sqlite3_module.xNext - vtab.html#xnext
  • sqlite3_module.xOpen - vtab.html#xopen
  • sqlite3_module.xRename - vtab.html#xrename
  • sqlite3_module.xRollback - vtab.html#xrollback
  • sqlite3_module.xRowid - vtab.html#xrowid
  • sqlite3_module.xSavepoint - vtab.html#xsavepoint
  • sqlite3_module.xSync - vtab.html#xsync
  • sqlite3_module.xUpdate - vtab.html#xupdate
  • sqlite3_mprintf - c3ref/mprintf.html
  • sqlite3_mutex - c3ref/mutex.html
  • sqlite3_mutex_alloc - c3ref/mutex_alloc.html
  • sqlite3_mutex_enter - c3ref/mutex_alloc.html
  • sqlite3_mutex_free - c3ref/mutex_alloc.html
  • sqlite3_mutex_held - c3ref/mutex_held.html
  • sqlite3_mutex_leave - c3ref/mutex_alloc.html
  • sqlite3_mutex_methods - c3ref/mutex_methods.html
  • sqlite3_mutex_notheld - c3ref/mutex_held.html
  • sqlite3_mutex_try - c3ref/mutex_alloc.html
  • sqlite3_next_stmt - c3ref/next_stmt.html
  • sqlite3_open - c3ref/open.html
  • sqlite3_open16 - c3ref/open.html
  • sqlite3_open_v2 - c3ref/open.html
  • sqlite3_os_end - c3ref/initialize.html
  • sqlite3_os_init - c3ref/initialize.html
  • sqlite3_overload_function - c3ref/overload_function.html
  • sqlite3_pcache - c3ref/pcache.html
  • sqlite3_pcache_methods - c3ref/pcache_methods.html
  • sqlite3_prepare - c3ref/prepare.html
  • sqlite3_prepare16 - c3ref/prepare.html
  • sqlite3_prepare16_v2 - c3ref/prepare.html
  • sqlite3_prepare_v2 - c3ref/prepare.html
  • sqlite3_profile - c3ref/profile.html
  • sqlite3_progress_handler - c3ref/progress_handler.html
  • sqlite3_randomness - c3ref/randomness.html
  • sqlite3_realloc - c3ref/free.html
  • sqlite3_release_memory - c3ref/release_memory.html
  • sqlite3_reset - c3ref/reset.html
  • sqlite3_reset_auto_extension - c3ref/reset_auto_extension.html
  • sqlite3_result_blob - c3ref/result_blob.html
  • sqlite3_result_double - c3ref/result_blob.html
  • sqlite3_result_error - c3ref/result_blob.html
  • sqlite3_result_error16 - c3ref/result_blob.html
  • sqlite3_result_error_code - c3ref/result_blob.html
  • sqlite3_result_error_nomem - c3ref/result_blob.html
  • sqlite3_result_error_toobig - c3ref/result_blob.html
  • sqlite3_result_int - c3ref/result_blob.html
  • sqlite3_result_int64 - c3ref/result_blob.html
  • sqlite3_result_null - c3ref/result_blob.html
  • sqlite3_result_text - c3ref/result_blob.html
  • sqlite3_result_text16 - c3ref/result_blob.html
  • sqlite3_result_text16be - c3ref/result_blob.html
  • sqlite3_result_text16le - c3ref/result_blob.html
  • sqlite3_result_value - c3ref/result_blob.html
  • sqlite3_result_zeroblob - c3ref/result_blob.html
  • sqlite3_rollback_hook - c3ref/commit_hook.html
  • sqlite3_set_authorizer - c3ref/set_authorizer.html
  • sqlite3_set_auxdata - c3ref/get_auxdata.html
  • sqlite3_shutdown - c3ref/initialize.html
  • sqlite3_sleep - c3ref/sleep.html
  • sqlite3_snprintf - c3ref/mprintf.html
  • sqlite3_soft_heap_limit - c3ref/soft_heap_limit.html
  • sqlite3_soft_heap_limit64 - c3ref/soft_heap_limit64.html
  • sqlite3_sourceid - c3ref/libversion.html
  • sqlite3_sql - c3ref/sql.html
  • sqlite3_status - c3ref/status.html
  • sqlite3_step - c3ref/step.html
  • sqlite3_stmt - c3ref/stmt.html
  • sqlite3_stmt_readonly - c3ref/stmt_readonly.html
  • sqlite3_stmt_status - c3ref/stmt_status.html
  • sqlite3_strnicmp - c3ref/strnicmp.html
  • sqlite3_table_column_metadata - c3ref/table_column_metadata.html
  • sqlite3_temp_directory - c3ref/temp_directory.html
  • sqlite3_test_control - c3ref/test_control.html
  • sqlite3_thread_cleanup - c3ref/aggregate_count.html
  • sqlite3_threadsafe - c3ref/threadsafe.html
  • sqlite3_total_changes - c3ref/total_changes.html
  • sqlite3_trace - c3ref/profile.html
  • sqlite3_transfer_bindings - c3ref/aggregate_count.html
  • sqlite3_uint64 - c3ref/int64.html
  • sqlite3_unlock_notify - c3ref/unlock_notify.html
  • sqlite3_update_hook - c3ref/update_hook.html
  • sqlite3_uri_parameter - c3ref/uri_parameter.html
  • sqlite3_user_data - c3ref/user_data.html
  • sqlite3_value - c3ref/value.html
  • sqlite3_value_blob - c3ref/value_blob.html
  • sqlite3_value_bytes - c3ref/value_blob.html
  • sqlite3_value_bytes16 - c3ref/value_blob.html
  • sqlite3_value_double - c3ref/value_blob.html
  • sqlite3_value_int - c3ref/value_blob.html
  • sqlite3_value_int64 - c3ref/value_blob.html
  • sqlite3_value_numeric_type - c3ref/value_blob.html
  • sqlite3_value_text - c3ref/value_blob.html
  • sqlite3_value_text16 - c3ref/value_blob.html
  • sqlite3_value_text16be - c3ref/value_blob.html
  • sqlite3_value_text16le - c3ref/value_blob.html
  • sqlite3_value_type - c3ref/value_blob.html
  • sqlite3_version - c3ref/libversion.html
  • sqlite3_vfs - c3ref/vfs.html
  • sqlite3_vfs.xAccess - c3ref/vfs.html#sqlite3vfsxaccess
  • sqlite3_vfs.xOpen - c3ref/vfs.html#sqlite3vfsxopen
  • sqlite3_vfs_find - c3ref/vfs_find.html
  • sqlite3_vfs_register - c3ref/vfs_find.html
  • sqlite3_vfs_unregister - c3ref/vfs_find.html
  • sqlite3_vmprintf - c3ref/mprintf.html
  • sqlite3_vsnprintf - c3ref/mprintf.html
  • sqlite3_vtab - c3ref/vtab.html
  • sqlite3_vtab_config - c3ref/vtab_config.html
  • sqlite3_vtab_cursor - c3ref/vtab_cursor.html
  • sqlite3_vtab_on_conflict - c3ref/vtab_on_conflict.html
  • sqlite3_wal_autocheckpoint - c3ref/wal_autocheckpoint.html
  • sqlite3_wal_checkpoint - c3ref/wal_checkpoint.html
  • sqlite3_wal_checkpoint_v2 - c3ref/wal_checkpoint_v2.html
  • sqlite3_wal_hook - c3ref/wal_hook.html
  • SQLITE_4_BYTE_ALIGNED_MALLOC - compile.html#4_byte_aligned_malloc
  • SQLITE_ABORT - c3ref/c_abort.html
  • SQLITE_ACCESS_EXISTS - c3ref/c_access_exists.html
  • SQLITE_ACCESS_READ - c3ref/c_access_exists.html
  • SQLITE_ACCESS_READWRITE - c3ref/c_access_exists.html
  • SQLITE_ALTER_TABLE - c3ref/c_alter_table.html
  • SQLITE_ANALYZE - c3ref/c_alter_table.html
  • SQLITE_ANY - c3ref/c_any.html
  • SQLITE_ATTACH - c3ref/c_alter_table.html
  • SQLITE_AUTH - c3ref/c_abort.html
  • SQLITE_BLOB - c3ref/c_blob.html
  • SQLITE_BUSY - c3ref/c_abort.html
  • SQLITE_BUSY_RECOVERY - c3ref/c_busy_recovery.html
  • SQLITE_CANTOPEN - c3ref/c_abort.html
  • SQLITE_CANTOPEN_NOTEMPDIR - c3ref/c_busy_recovery.html
  • SQLITE_CASE_SENSITIVE_LIKE - compile.html#case_sensitive_like
  • SQLITE_CHECKPOINT_FULL - c3ref/c_checkpoint_full.html
  • SQLITE_CHECKPOINT_PASSIVE - c3ref/c_checkpoint_full.html
  • SQLITE_CHECKPOINT_RESTART - c3ref/c_checkpoint_full.html
  • sqlite_compileoption_get - lang_corefunc.html#sqlite_compileoption_get
  • sqlite_compileoption_get SQL function - lang_corefunc.html#sqlite_compileoption_get
  • sqlite_compileoption_used - lang_corefunc.html#sqlite_compileoption_used
  • sqlite_compileoption_used SQL function - lang_corefunc.html#sqlite_compileoption_used
  • SQLITE_CONFIG_GETMALLOC - c3ref/c_config_getmalloc.html#sqliteconfiggetmalloc
  • SQLITE_CONFIG_GETMUTEX - c3ref/c_config_getmalloc.html#sqliteconfiggetmutex
  • SQLITE_CONFIG_GETPCACHE - c3ref/c_config_getmalloc.html#sqliteconfiggetpcache
  • SQLITE_CONFIG_HEAP - c3ref/c_config_getmalloc.html#sqliteconfigheap
  • SQLITE_CONFIG_LOG - c3ref/c_config_getmalloc.html#sqliteconfiglog
  • SQLITE_CONFIG_LOOKASIDE - c3ref/c_config_getmalloc.html#sqliteconfiglookaside
  • SQLITE_CONFIG_MALLOC - c3ref/c_config_getmalloc.html#sqliteconfigmalloc
  • SQLITE_CONFIG_MEMSTATUS - c3ref/c_config_getmalloc.html#sqliteconfigmemstatus
  • SQLITE_CONFIG_MULTITHREAD - c3ref/c_config_getmalloc.html#sqliteconfigmultithread
  • SQLITE_CONFIG_MUTEX - c3ref/c_config_getmalloc.html#sqliteconfigmutex
  • SQLITE_CONFIG_PAGECACHE - c3ref/c_config_getmalloc.html#sqliteconfigpagecache
  • SQLITE_CONFIG_PCACHE - c3ref/c_config_getmalloc.html#sqliteconfigpcache
  • SQLITE_CONFIG_SCRATCH - c3ref/c_config_getmalloc.html#sqliteconfigscratch
  • SQLITE_CONFIG_SERIALIZED - c3ref/c_config_getmalloc.html#sqliteconfigserialized
  • SQLITE_CONFIG_SINGLETHREAD - c3ref/c_config_getmalloc.html#sqliteconfigsinglethread
  • SQLITE_CONFIG_URI - c3ref/c_config_getmalloc.html#sqliteconfiguri
  • SQLITE_CONSTRAINT - c3ref/c_abort.html
  • SQLITE_COPY - c3ref/c_alter_table.html
  • SQLITE_CORRUPT - c3ref/c_abort.html
  • SQLITE_CORRUPT_VTAB - c3ref/c_busy_recovery.html
  • SQLITE_CREATE_INDEX - c3ref/c_alter_table.html
  • SQLITE_CREATE_TABLE - c3ref/c_alter_table.html
  • SQLITE_CREATE_TEMP_INDEX - c3ref/c_alter_table.html
  • SQLITE_CREATE_TEMP_TABLE - c3ref/c_alter_table.html
  • SQLITE_CREATE_TEMP_TRIGGER - c3ref/c_alter_table.html
  • SQLITE_CREATE_TEMP_VIEW - c3ref/c_alter_table.html
  • SQLITE_CREATE_TRIGGER - c3ref/c_alter_table.html
  • SQLITE_CREATE_VIEW - c3ref/c_alter_table.html
  • SQLITE_CREATE_VTABLE - c3ref/c_alter_table.html
  • SQLITE_DBCONFIG_ENABLE_FKEY - c3ref/c_dbconfig_enable_fkey.html
  • SQLITE_DBCONFIG_ENABLE_TRIGGER - c3ref/c_dbconfig_enable_fkey.html
  • SQLITE_DBCONFIG_LOOKASIDE - c3ref/c_dbconfig_enable_fkey.html
  • SQLITE_DBSTATUS options - c3ref/c_dbstatus_options.html
  • SQLITE_DBSTATUS_CACHE_HIT - c3ref/c_dbstatus_options.html#sqlitedbstatuscachehit
  • SQLITE_DBSTATUS_CACHE_MISS - c3ref/c_dbstatus_options.html#sqlitedbstatuscachemiss
  • SQLITE_DBSTATUS_CACHE_USED - c3ref/c_dbstatus_options.html#sqlitedbstatuscacheused
  • SQLITE_DBSTATUS_LOOKASIDE_HIT - c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidehit
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL - c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidemissfull
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE - c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidemisssize
  • SQLITE_DBSTATUS_LOOKASIDE_USED - c3ref/c_dbstatus_options.html#sqlitedbstatuslookasideused
  • SQLITE_DBSTATUS_MAX - c3ref/c_dbstatus_options.html
  • SQLITE_DBSTATUS_SCHEMA_USED - c3ref/c_dbstatus_options.html#sqlitedbstatusschemaused
  • SQLITE_DBSTATUS_STMT_USED - c3ref/c_dbstatus_options.html#sqlitedbstatusstmtused
  • SQLITE_DEBUG - compile.html#debug
  • SQLITE_DEFAULT_AUTOVACUUM - compile.html#default_autovacuum
  • SQLITE_DEFAULT_CACHE_SIZE - compile.html#default_cache_size
  • SQLITE_DEFAULT_FILE_FORMAT - compile.html#default_file_format
  • SQLITE_DEFAULT_FILE_PERMISSIONS - compile.html#default_file_permissions
  • SQLITE_DEFAULT_FOREIGN_KEYS - compile.html#default_foreign_keys
  • SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT - compile.html#default_journal_size_limit
  • SQLITE_DEFAULT_LOCKING_MODE - compile.html#default_locking_mode
  • SQLITE_DEFAULT_MEMSTATUS - compile.html#default_memstatus
  • SQLITE_DEFAULT_PAGE_SIZE - compile.html#default_page_size
  • SQLITE_DEFAULT_TEMP_CACHE_SIZE - compile.html#default_temp_cache_size
  • SQLITE_DEFAULT_WAL_AUTOCHECKPOINT - compile.html#default_wal_autocheckpoint
  • SQLITE_DELETE - c3ref/c_alter_table.html
  • SQLITE_DENY - c3ref/c_deny.html
  • SQLITE_DETACH - c3ref/c_alter_table.html
  • SQLITE_DIRECT_OVERFLOW_READ - compile.html#direct_overflow_read
  • SQLITE_DISABLE_DIRSYNC - compile.html#disable_dirsync
  • SQLITE_DISABLE_LFS - compile.html#disable_lfs
  • SQLITE_DONE - c3ref/c_abort.html
  • SQLITE_DROP_INDEX - c3ref/c_alter_table.html
  • SQLITE_DROP_TABLE - c3ref/c_alter_table.html
  • SQLITE_DROP_TEMP_INDEX - c3ref/c_alter_table.html
  • SQLITE_DROP_TEMP_TABLE - c3ref/c_alter_table.html
  • SQLITE_DROP_TEMP_TRIGGER - c3ref/c_alter_table.html
  • SQLITE_DROP_TEMP_VIEW - c3ref/c_alter_table.html
  • SQLITE_DROP_TRIGGER - c3ref/c_alter_table.html
  • SQLITE_DROP_VIEW - c3ref/c_alter_table.html
  • SQLITE_DROP_VTABLE - c3ref/c_alter_table.html
  • SQLITE_EMPTY - c3ref/c_abort.html
  • SQLITE_ENABLE_8_3_NAMES - compile.html#enable_8_3_names
  • SQLITE_ENABLE_ATOMIC_WRITE - compile.html#enable_atomic_write
  • SQLITE_ENABLE_COLUMN_METADATA - compile.html#enable_column_metadata
  • SQLITE_ENABLE_FTS3 - compile.html#enable_fts3
  • SQLITE_ENABLE_FTS3_PARENTHESIS - compile.html#enable_fts3_parenthesis
  • SQLITE_ENABLE_FTS4 - compile.html#enable_fts4
  • SQLITE_ENABLE_ICU - compile.html#enable_icu
  • SQLITE_ENABLE_IOTRACE - compile.html#enable_iotrace
  • SQLITE_ENABLE_LOCKING_STYLE - compile.html#enable_locking_style
  • SQLITE_ENABLE_MEMORY_MANAGEMENT - compile.html#enable_memory_management
  • SQLITE_ENABLE_MEMSYS3 - compile.html#enable_memsys3
  • SQLITE_ENABLE_MEMSYS5 - compile.html#enable_memsys5
  • SQLITE_ENABLE_RTREE - compile.html#enable_rtree
  • SQLITE_ENABLE_STAT2 - compile.html#enable_stat2
  • SQLITE_ENABLE_STAT3 - compile.html#enable_stat3
  • SQLITE_ENABLE_UNLOCK_NOTIFY - compile.html#enable_unlock_notify
  • SQLITE_ENABLE_UPDATE_DELETE_LIMIT - compile.html#enable_update_delete_limit
  • SQLITE_ERROR - c3ref/c_abort.html
  • SQLITE_FAIL - c3ref/c_fail.html
  • SQLITE_FCNTL_CHUNK_SIZE - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_FILE_POINTER - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_LOCKSTATE - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_OVERWRITE - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_PERSIST_WAL - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_SIZE_HINT - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_SYNC_OMITTED - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FCNTL_WIN32_AV_RETRY - c3ref/c_fcntl_chunk_size.html
  • SQLITE_FLOAT - c3ref/c_blob.html
  • SQLITE_FORMAT - c3ref/c_abort.html
  • SQLITE_FULL - c3ref/c_abort.html
  • SQLITE_FUNCTION - c3ref/c_alter_table.html
  • SQLITE_GET_LOCKPROXYFILE - c3ref/c_fcntl_chunk_size.html
  • SQLITE_HAVE_ISNAN - compile.html#have_isnan
  • SQLITE_IGNORE - c3ref/c_deny.html
  • SQLITE_INDEX_CONSTRAINT_EQ - c3ref/c_index_constraint_eq.html
  • SQLITE_INDEX_CONSTRAINT_GE - c3ref/c_index_constraint_eq.html
  • SQLITE_INDEX_CONSTRAINT_GT - c3ref/c_index_constraint_eq.html
  • SQLITE_INDEX_CONSTRAINT_LE - c3ref/c_index_constraint_eq.html
  • SQLITE_INDEX_CONSTRAINT_LT - c3ref/c_index_constraint_eq.html
  • SQLITE_INDEX_CONSTRAINT_MATCH - c3ref/c_index_constraint_eq.html
  • SQLITE_INSERT - c3ref/c_alter_table.html
  • sqlite_int64 - c3ref/int64.html
  • SQLITE_INTEGER - c3ref/c_blob.html
  • SQLITE_INTERNAL - c3ref/c_abort.html
  • SQLITE_INTERRUPT - c3ref/c_abort.html
  • SQLITE_IOCAP_ATOMIC - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC1K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC2K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC4K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC8K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC16K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC32K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC64K - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_ATOMIC512 - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_SAFE_APPEND - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_SEQUENTIAL - c3ref/c_iocap_atomic.html
  • SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN - c3ref/c_iocap_atomic.html
  • SQLITE_IOERR - c3ref/c_abort.html
  • SQLITE_IOERR_ACCESS - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_BLOCKED - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_CHECKRESERVEDLOCK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_CLOSE - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_DELETE - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_DIR_CLOSE - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_DIR_FSYNC - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_FSTAT - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_FSYNC - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_LOCK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_NOMEM - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_RDLOCK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_READ - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SEEK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SHMLOCK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SHMMAP - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SHMOPEN - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SHMSIZE - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_SHORT_READ - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_TRUNCATE - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_UNLOCK - c3ref/c_busy_recovery.html
  • SQLITE_IOERR_WRITE - c3ref/c_busy_recovery.html
  • SQLITE_LAST_ERRNO - c3ref/c_fcntl_chunk_size.html
  • SQLITE_LIMIT_ATTACHED - c3ref/c_limit_attached.html#sqlitelimitattached
  • SQLITE_LIMIT_COLUMN - c3ref/c_limit_attached.html#sqlitelimitcolumn
  • SQLITE_LIMIT_COMPOUND_SELECT - c3ref/c_limit_attached.html#sqlitelimitcompoundselect
  • SQLITE_LIMIT_EXPR_DEPTH - c3ref/c_limit_attached.html#sqlitelimitexprdepth
  • SQLITE_LIMIT_FUNCTION_ARG - c3ref/c_limit_attached.html#sqlitelimitfunctionarg
  • SQLITE_LIMIT_LENGTH - c3ref/c_limit_attached.html#sqlitelimitlength
  • SQLITE_LIMIT_LIKE_PATTERN_LENGTH - c3ref/c_limit_attached.html#sqlitelimitlikepatternlength
  • SQLITE_LIMIT_SQL_LENGTH - c3ref/c_limit_attached.html#sqlitelimitsqllength
  • SQLITE_LIMIT_TRIGGER_DEPTH - c3ref/c_limit_attached.html#sqlitelimittriggerdepth
  • SQLITE_LIMIT_VARIABLE_NUMBER - c3ref/c_limit_attached.html#sqlitelimitvariablenumber
  • SQLITE_LIMIT_VDBE_OP - c3ref/c_limit_attached.html#sqlitelimitvdbeop
  • SQLITE_LOCK_EXCLUSIVE - c3ref/c_lock_exclusive.html
  • SQLITE_LOCK_NONE - c3ref/c_lock_exclusive.html
  • SQLITE_LOCK_PENDING - c3ref/c_lock_exclusive.html
  • SQLITE_LOCK_RESERVED - c3ref/c_lock_exclusive.html
  • SQLITE_LOCK_SHARED - c3ref/c_lock_exclusive.html
  • SQLITE_LOCKED - c3ref/c_abort.html
  • SQLITE_LOCKED_SHAREDCACHE - c3ref/c_busy_recovery.html
  • SQLITE_MAX_ATTACHED - limits.html#max_attached
  • SQLITE_MAX_COLUMN - limits.html#max_column
  • SQLITE_MAX_COMPOUND_SELECT - limits.html#max_compound_select
  • SQLITE_MAX_EXPR_DEPTH - limits.html#max_expr_depth
  • SQLITE_MAX_FUNCTION_ARG - limits.html#max_function_arg
  • SQLITE_MAX_LENGTH - limits.html#max_length
  • SQLITE_MAX_LIKE_PATTERN_LENGTH - limits.html#max_like_pattern_length
  • SQLITE_MAX_PAGE_COUNT - limits.html#max_page_count
  • SQLITE_MAX_SCHEMA_RETRY - compile.html#max_schema_retry
  • SQLITE_MAX_SQL_LENGTH - limits.html#max_sql_length
  • SQLITE_MAX_TRIGGER_DEPTH - limits.html#max_trigger_depth
  • SQLITE_MAX_VARIABLE_NUMBER - limits.html#max_variable_number
  • SQLITE_MEMDEBUG - compile.html#memdebug
  • SQLITE_MISMATCH - c3ref/c_abort.html
  • SQLITE_MISUSE - c3ref/c_abort.html
  • SQLITE_MUTEX_FAST - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_RECURSIVE - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_LRU - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_LRU2 - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_MASTER - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_MEM - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_MEM2 - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_OPEN - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_PMEM - c3ref/c_mutex_fast.html
  • SQLITE_MUTEX_STATIC_PRNG - c3ref/c_mutex_fast.html
  • SQLITE_NOLFS - c3ref/c_abort.html
  • SQLITE_NOMEM - c3ref/c_abort.html
  • SQLITE_NOTADB - c3ref/c_abort.html
  • SQLITE_NOTFOUND - c3ref/c_abort.html
  • SQLITE_NULL - c3ref/c_blob.html
  • SQLITE_OK - c3ref/c_abort.html
  • SQLITE_OMIT_ALTERTABLE - compile.html#omit_altertable
  • SQLITE_OMIT_ANALYZE - compile.html#omit_analyze
  • SQLITE_OMIT_ATTACH - compile.html#omit_attach
  • SQLITE_OMIT_AUTHORIZATION - compile.html#omit_authorization
  • SQLITE_OMIT_AUTOINCREMENT - compile.html#omit_autoincrement
  • SQLITE_OMIT_AUTOINIT - compile.html#omit_autoinit
  • SQLITE_OMIT_AUTOMATIC_INDEX - compile.html#omit_automatic_index
  • SQLITE_OMIT_AUTORESET - compile.html#omit_autoreset
  • SQLITE_OMIT_AUTOVACUUM - compile.html#omit_autovacuum
  • SQLITE_OMIT_BETWEEN_OPTIMIZATION - compile.html#omit_between_optimization
  • SQLITE_OMIT_BLOB_LITERAL - compile.html#omit_blob_literal
  • SQLITE_OMIT_BTREECOUNT - compile.html#omit_btreecount
  • SQLITE_OMIT_BUILTIN_TEST - compile.html#omit_builtin_test
  • SQLITE_OMIT_CAST - compile.html#omit_cast
  • SQLITE_OMIT_CHECK - compile.html#omit_check
  • SQLITE_OMIT_COMPILEOPTION_DIAGS - compile.html#omit_compileoption_diags
  • SQLITE_OMIT_COMPLETE - compile.html#omit_complete
  • SQLITE_OMIT_COMPOUND_SELECT - compile.html#omit_compound_select
  • SQLITE_OMIT_DATETIME_FUNCS - compile.html#omit_datetime_funcs
  • SQLITE_OMIT_DECLTYPE - compile.html#omit_decltype
  • SQLITE_OMIT_DEPRECATED - compile.html#omit_deprecated
  • SQLITE_OMIT_DISKIO - compile.html#omit_diskio
  • SQLITE_OMIT_EXPLAIN - compile.html#omit_explain
  • SQLITE_OMIT_FLAG_PRAGMAS - compile.html#omit_flag_pragmas
  • SQLITE_OMIT_FLOATING_POINT - compile.html#omit_floating_point
  • SQLITE_OMIT_FOREIGN_KEY - compile.html#omit_foreign_key
  • SQLITE_OMIT_GET_TABLE - compile.html#omit_get_table
  • SQLITE_OMIT_INCRBLOB - compile.html#omit_incrblob
  • SQLITE_OMIT_INTEGRITY_CHECK - compile.html#omit_integrity_check
  • SQLITE_OMIT_LIKE_OPTIMIZATION - compile.html#omit_like_optimization
  • SQLITE_OMIT_LOAD_EXTENSION - compile.html#omit_load_extension
  • SQLITE_OMIT_LOCALTIME - compile.html#omit_localtime
  • SQLITE_OMIT_LOOKASIDE - compile.html#omit_lookaside
  • SQLITE_OMIT_MEMORYDB - compile.html#omit_memorydb
  • SQLITE_OMIT_MERGE_SORT - compile.html#omit_merge_sort
  • SQLITE_OMIT_OR_OPTIMIZATION - compile.html#omit_or_optimization
  • SQLITE_OMIT_PAGER_PRAGMAS - compile.html#omit_pager_pragmas
  • SQLITE_OMIT_PRAGMA - compile.html#omit_pragma
  • SQLITE_OMIT_PROGRESS_CALLBACK - compile.html#omit_progress_callback
  • SQLITE_OMIT_QUICKBALANCE - compile.html#omit_quickbalance
  • SQLITE_OMIT_REINDEX - compile.html#omit_reindex
  • SQLITE_OMIT_SCHEMA_PRAGMAS - compile.html#omit_schema_pragmas
  • SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS - compile.html#omit_schema_version_pragmas
  • SQLITE_OMIT_SHARED_CACHE - compile.html#omit_shared_cache
  • SQLITE_OMIT_SUBQUERY - compile.html#omit_subquery
  • SQLITE_OMIT_TCL_VARIABLE - compile.html#omit_tcl_variable
  • SQLITE_OMIT_TEMPDB - compile.html#omit_tempdb
  • SQLITE_OMIT_TRACE - compile.html#omit_trace
  • SQLITE_OMIT_TRIGGER - compile.html#omit_trigger
  • SQLITE_OMIT_TRUNCATE_OPTIMIZATION - compile.html#omit_truncate_optimization
  • SQLITE_OMIT_UTF16 - compile.html#omit_utf16
  • SQLITE_OMIT_VACUUM - compile.html#omit_vacuum
  • SQLITE_OMIT_VIEW - compile.html#omit_view
  • SQLITE_OMIT_VIRTUALTABLE - compile.html#omit_virtualtable
  • SQLITE_OMIT_WAL - compile.html#omit_wal
  • SQLITE_OMIT_WSD - compile.html#omit_wsd
  • SQLITE_OMIT_XFER_OPT - compile.html#omit_xfer_opt
  • SQLITE_OPEN_AUTOPROXY - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_CREATE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_DELETEONCLOSE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_EXCLUSIVE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_FULLMUTEX - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_MAIN_DB - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_MAIN_JOURNAL - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_MASTER_JOURNAL - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_NOMUTEX - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_PRIVATECACHE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_READONLY - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_READWRITE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_SHAREDCACHE - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_SUBJOURNAL - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_TEMP_DB - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_TEMP_JOURNAL - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_TRANSIENT_DB - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_URI - c3ref/c_open_autoproxy.html
  • SQLITE_OPEN_WAL - c3ref/c_open_autoproxy.html
  • SQLITE_OS_OTHER - compile.html#os_other
  • SQLITE_PERM - c3ref/c_abort.html
  • SQLITE_PRAGMA - c3ref/c_alter_table.html
  • SQLITE_PROTOCOL - c3ref/c_abort.html
  • SQLITE_RANGE - c3ref/c_abort.html
  • SQLITE_READ - c3ref/c_alter_table.html
  • SQLITE_READONLY - c3ref/c_abort.html
  • SQLITE_READONLY_CANTLOCK - c3ref/c_busy_recovery.html
  • SQLITE_READONLY_RECOVERY - c3ref/c_busy_recovery.html
  • SQLITE_REINDEX - c3ref/c_alter_table.html
  • SQLITE_REPLACE - c3ref/c_fail.html
  • SQLITE_ROLLBACK - c3ref/c_fail.html
  • SQLITE_ROW - c3ref/c_abort.html
  • SQLITE_SAVEPOINT - c3ref/c_alter_table.html
  • SQLITE_SCHEMA - c3ref/c_abort.html
  • SQLITE_SECURE_DELETE - compile.html#secure_delete
  • SQLITE_SELECT - c3ref/c_alter_table.html
  • SQLITE_SET_LOCKPROXYFILE - c3ref/c_fcntl_chunk_size.html
  • SQLITE_SHM_EXCLUSIVE - c3ref/c_shm_exclusive.html
  • SQLITE_SHM_LOCK - c3ref/c_shm_exclusive.html
  • SQLITE_SHM_NLOCK - c3ref/c_shm_nlock.html
  • SQLITE_SHM_SHARED - c3ref/c_shm_exclusive.html
  • SQLITE_SHM_UNLOCK - c3ref/c_shm_exclusive.html
  • SQLITE_SOUNDEX - compile.html#soundex
  • SQLITE_SOURCE_ID - c3ref/c_source_id.html
  • sqlite_source_id - lang_corefunc.html#sqlite_source_id
  • sqlite_source_id SQL function - lang_corefunc.html#sqlite_source_id
  • SQLITE_STATIC - c3ref/c_static.html
  • SQLITE_STATUS_MALLOC_COUNT - c3ref/c_status_malloc_count.html#sqlitestatusmalloccount
  • SQLITE_STATUS_MALLOC_SIZE - c3ref/c_status_malloc_count.html#sqlitestatusmallocsize
  • SQLITE_STATUS_MEMORY_USED - c3ref/c_status_malloc_count.html#sqlitestatusmemoryused
  • SQLITE_STATUS_PAGECACHE_OVERFLOW - c3ref/c_status_malloc_count.html#sqlitestatuspagecacheoverflow
  • SQLITE_STATUS_PAGECACHE_SIZE - c3ref/c_status_malloc_count.html#sqlitestatuspagecachesize
  • SQLITE_STATUS_PAGECACHE_USED - c3ref/c_status_malloc_count.html#sqlitestatuspagecacheused
  • SQLITE_STATUS_PARSER_STACK - c3ref/c_status_malloc_count.html#sqlitestatusparserstack
  • SQLITE_STATUS_SCRATCH_OVERFLOW - c3ref/c_status_malloc_count.html#sqlitestatusscratchoverflow
  • SQLITE_STATUS_SCRATCH_SIZE - c3ref/c_status_malloc_count.html#sqlitestatusscratchsize
  • SQLITE_STATUS_SCRATCH_USED - c3ref/c_status_malloc_count.html#sqlitestatusscratchused
  • SQLITE_STMTSTATUS counter - c3ref/c_stmtstatus_counter.html
  • SQLITE_STMTSTATUS counters - c3ref/c_stmtstatus_counter.html
  • SQLITE_STMTSTATUS_AUTOINDEX - c3ref/c_stmtstatus_counter.html#sqlitestmtstatusautoindex
  • SQLITE_STMTSTATUS_FULLSCAN_STEP - c3ref/c_stmtstatus_counter.html#sqlitestmtstatusfullscanstep
  • SQLITE_STMTSTATUS_SORT - c3ref/c_stmtstatus_counter.html#sqlitestmtstatussort
  • SQLITE_SYNC_DATAONLY - c3ref/c_sync_dataonly.html
  • SQLITE_SYNC_FULL - c3ref/c_sync_dataonly.html
  • SQLITE_SYNC_NORMAL - c3ref/c_sync_dataonly.html
  • SQLITE_TEMP_STORE - compile.html#temp_store
  • SQLITE_TESTCTRL_ALWAYS - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_ASSERT - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_BITVEC_TEST - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_FAULT_INSTALL - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_FIRST - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_ISKEYWORD - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_LAST - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_LOCALTIME_FAULT - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_OPTIMIZATIONS - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_PENDING_BYTE - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_PGHDRSZ - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_PRNG_RESET - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_PRNG_RESTORE - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_PRNG_SAVE - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_RESERVE - c3ref/c_testctrl_always.html
  • SQLITE_TESTCTRL_SCRATCHMALLOC - c3ref/c_testctrl_always.html
  • SQLITE_TEXT - c3ref/c_blob.html
  • SQLITE_THREADSAFE - compile.html#threadsafe
  • SQLITE_TOOBIG - c3ref/c_abort.html
  • SQLITE_TRANSACTION - c3ref/c_alter_table.html
  • SQLITE_TRANSIENT - c3ref/c_static.html
  • sqlite_uint64 - c3ref/int64.html
  • SQLITE_UPDATE - c3ref/c_alter_table.html
  • SQLITE_USE_URI - compile.html#use_uri
  • SQLITE_UTF8 - c3ref/c_any.html
  • SQLITE_UTF16 - c3ref/c_any.html
  • SQLITE_UTF16_ALIGNED - c3ref/c_any.html
  • SQLITE_UTF16BE - c3ref/c_any.html
  • SQLITE_UTF16LE - c3ref/c_any.html
  • SQLITE_VERSION - c3ref/c_source_id.html
  • sqlite_version - lang_corefunc.html#sqlite_version
  • sqlite_version SQL function - lang_corefunc.html#sqlite_version
  • SQLITE_VERSION_NUMBER - c3ref/c_source_id.html
  • SQLITE_VTAB_CONSTRAINT_SUPPORT - c3ref/c_vtab_constraint_support.html
  • SQLITE_ZERO_MALLOC - compile.html#zero_malloc
  • status parameters - c3ref/c_status_malloc_count.html
  • storage class - datatype3.html#storageclasses
  • strategies - queryplanner.html#searching
  • strftime SQL function - lang_datefunc.html
  • substr - lang_corefunc.html#substr
  • substr SQL function - lang_corefunc.html#substr
  • sum - lang_aggfunc.html#sumunc
  • sum aggregate function - lang_aggfunc.html#sumunc
  • sumFunc - lang_aggfunc.html#sumunc
  • synchronous - pragma.html#pragma_synchronous
  • synchronous pragma - pragma.html#pragma_synchronous
  • syntax diagrams - syntaxdiagrams.html
  • table-constraint - syntaxdiagrams.html#table-constraint
  • table-constraint syntax diagram - syntaxdiagrams.html#table-constraint
  • table_info - pragma.html#pragma_table_info
  • table_info pragma - pragma.html#pragma_table_info
  • Tcl extension - tclsqlite.html
  • TCL Interface - tclsqlite.html
  • TCL test suite - testing.html#tcl
  • TCL variable substitution - tclsqlite.html#varsubst
  • TEA tarball - download.html
  • temp_store - pragma.html#pragma_temp_store
  • temp_store pragma - pragma.html#pragma_temp_store
  • temp_store_directory - pragma.html#pragma_temp_store_directory
  • temp_store_directory pragma - pragma.html#pragma_temp_store_directory
  • temporary databases - inmemorydb.html#temp_db
  • temporary disk files - tempfiles.html
  • temporary tables - inmemorydb.html#temp_db
  • tempstore - tempfiles.html#tempstore
  • test coverage - testing.html#coverage
  • test harness - testing.html#harnesses
  • test suite - testing.html
  • testcase macros - testing.html#testcase
  • tested - testing.html
  • testing - testing.html
  • TH3 - th3.html
  • the amalgamation - amalgamation.html
  • the ext3 barrier problem - lockingv3.html#ext3-barrier-problem
  • the xCachesize page cache method - c3ref/pcache_methods.html#thexcachesizepagecachemethod
  • the xCreate page cache methods - c3ref/pcache_methods.html#thexcreatepagecachemethods
  • the xDestroy page cache method - c3ref/pcache_methods.html#thexdestroypagecachemethod
  • the xFetch page cache methods - c3ref/pcache_methods.html#thexfetchpagecachemethods
  • the xInit page cache method - c3ref/pcache_methods.html#thexinitpagecachemethod
  • the xPagecount page cache methods - c3ref/pcache_methods.html#thexpagecountpagecachemethods
  • the xRekey page cache methods - c3ref/pcache_methods.html#thexrekeypagecachemethods
  • the xShutdown page cache method - c3ref/pcache_methods.html#thexshutdownpagecachemethod
  • the xUnpin page cache method - c3ref/pcache_methods.html#thexunpinpagecachemethod
  • Things That Can Go Wrong - atomiccommit.html#sect_9_0
  • threading mode - threadsafe.html
  • three test harnesses - testing.html#harnesses
  • time SQL function - lang_datefunc.html
  • tokenizer - fts3.html#tokenizer
  • total - lang_aggfunc.html#sumunc
  • total aggregate function - lang_aggfunc.html#sumunc
  • total_changes - lang_corefunc.html#total_changes
  • total_changes SQL function - lang_corefunc.html#total_changes
  • trim - lang_corefunc.html#trim
  • trim SQL function - lang_corefunc.html#trim
  • truncate optimization - lang_delete.html#truncateopt
  • type affinity - datatype3.html#affinity
  • type-name - syntaxdiagrams.html#type-name
  • type-name syntax diagram - syntaxdiagrams.html#type-name
  • typeof - lang_corefunc.html#typeof
  • typeof SQL function - lang_corefunc.html#typeof
  • undefined BEFORE trigger behavior - lang_createtrigger.html#undef_before
  • Uniform Resource Identifier - uri.html
  • unprotected sqlite3_value - c3ref/value.html
  • UPDATE - lang_update.html
  • update-stmt - syntaxdiagrams.html#update-stmt
  • update-stmt syntax diagram - syntaxdiagrams.html#update-stmt
  • update-stmt-limited - syntaxdiagrams.html#update-stmt-limited
  • update-stmt-limited syntax diagram - syntaxdiagrams.html#update-stmt-limited
  • UPDATEs - lang_update.html
  • upper - lang_corefunc.html#upper
  • upper SQL function - lang_corefunc.html#upper
  • URI - uri.html
  • URI filename - uri.html
  • URI filename examples - c3ref/open.html#urifilenameexamples
  • URI filenames - uri.html
  • URI filenames in sqlite3_open - c3ref/open.html#urifilenamesinsqlite3open
  • usable size - fileformat2.html#usable_size
  • user_version - pragma.html#pragma_schema_version
  • user_version pragma - pragma.html#pragma_schema_version
  • Using the SQLite Online Backup API - backup.html
  • Using the SQLite Unlock Notification Feature - unlock_notify.html
  • VACUUM - lang_vacuum.html
  • vacuum-stmt - syntaxdiagrams.html#vacuum-stmt
  • vacuum-stmt syntax diagram - syntaxdiagrams.html#vacuum-stmt
  • variable-length integer - fileformat2.html#varint
  • varint - fileformat2.html#varint
  • vdbe_listing - pragma.html#pragma_vdbe_listing
  • vdbe_listing pragma - pragma.html#pragma_vdbe_listing
  • vdbe_trace - pragma.html#pragma_vdbe_trace
  • vdbe_trace pragma - pragma.html#pragma_vdbe_trace
  • Version 3.0.0 - releaselog/3_0_0.html
  • version 3.0.0 - releaselog/3_0_0.html
  • Version 3.0.1 - releaselog/3_0_1.html
  • version 3.0.1 - releaselog/3_0_1.html
  • Version 3.0.2 - releaselog/3_0_2.html
  • version 3.0.2 - releaselog/3_0_2.html
  • Version 3.0.3 - releaselog/3_0_3.html
  • version 3.0.3 - releaselog/3_0_3.html
  • Version 3.0.4 - releaselog/3_0_4.html
  • version 3.0.4 - releaselog/3_0_4.html
  • Version 3.0.5 - releaselog/3_0_5.html
  • version 3.0.5 - releaselog/3_0_5.html
  • Version 3.0.6 - releaselog/3_0_6.html
  • version 3.0.6 - releaselog/3_0_6.html
  • Version 3.0.7 - releaselog/3_0_7.html
  • version 3.0.7 - releaselog/3_0_7.html
  • Version 3.0.8 - releaselog/3_0_8.html
  • version 3.0.8 - releaselog/3_0_8.html
  • Version 3.1.0 - releaselog/3_1_0.html
  • version 3.1.0 - releaselog/3_1_0.html
  • Version 3.1.1 - releaselog/3_1_1.html
  • version 3.1.1 - releaselog/3_1_1.html
  • Version 3.1.2 - releaselog/3_1_2.html
  • version 3.1.2 - releaselog/3_1_2.html
  • Version 3.1.3 - releaselog/3_1_3.html
  • version 3.1.3 - releaselog/3_1_3.html
  • Version 3.1.4 - releaselog/3_1_4.html
  • version 3.1.4 - releaselog/3_1_4.html
  • Version 3.1.5 - releaselog/3_1_5.html
  • version 3.1.5 - releaselog/3_1_5.html
  • Version 3.1.6 - releaselog/3_1_6.html
  • version 3.1.6 - releaselog/3_1_6.html
  • Version 3.2.0 - releaselog/3_2_0.html
  • version 3.2.0 - releaselog/3_2_0.html
  • Version 3.2.1 - releaselog/3_2_1.html
  • version 3.2.1 - releaselog/3_2_1.html
  • Version 3.2.2 - releaselog/3_2_2.html
  • version 3.2.2 - releaselog/3_2_2.html
  • Version 3.2.3 - releaselog/3_2_3.html
  • version 3.2.3 - releaselog/3_2_3.html
  • Version 3.2.4 - releaselog/3_2_4.html
  • version 3.2.4 - releaselog/3_2_4.html
  • Version 3.2.5 - releaselog/3_2_5.html
  • version 3.2.5 - releaselog/3_2_5.html
  • Version 3.2.6 - releaselog/3_2_6.html
  • version 3.2.6 - releaselog/3_2_6.html
  • Version 3.2.7 - releaselog/3_2_7.html
  • version 3.2.7 - releaselog/3_2_7.html
  • Version 3.2.8 - releaselog/3_2_8.html
  • version 3.2.8 - releaselog/3_2_8.html
  • Version 3.3.0 - releaselog/3_3_0.html
  • version 3.3.0 - releaselog/3_3_0.html
  • Version 3.3.1 - releaselog/3_3_1.html
  • version 3.3.1 - releaselog/3_3_1.html
  • Version 3.3.2 - releaselog/3_3_2.html
  • version 3.3.2 - releaselog/3_3_2.html
  • Version 3.3.3 - releaselog/3_3_3.html
  • version 3.3.3 - releaselog/3_3_3.html
  • Version 3.3.4 - releaselog/3_3_4.html
  • version 3.3.4 - releaselog/3_3_4.html
  • Version 3.3.5 - releaselog/3_3_5.html
  • version 3.3.5 - releaselog/3_3_5.html
  • Version 3.3.6 - releaselog/3_3_6.html
  • version 3.3.6 - releaselog/3_3_6.html
  • Version 3.3.7 - releaselog/3_3_7.html
  • version 3.3.7 - releaselog/3_3_7.html
  • Version 3.3.8 - releaselog/3_3_8.html
  • version 3.3.8 - releaselog/3_3_8.html
  • Version 3.3.9 - releaselog/3_3_9.html
  • version 3.3.9 - releaselog/3_3_9.html
  • Version 3.3.10 - releaselog/3_3_10.html
  • version 3.3.10 - releaselog/3_3_10.html
  • Version 3.3.11 - releaselog/3_3_11.html
  • version 3.3.11 - releaselog/3_3_11.html
  • Version 3.3.12 - releaselog/3_3_12.html
  • version 3.3.12 - releaselog/3_3_12.html
  • Version 3.3.13 - releaselog/3_3_13.html
  • version 3.3.13 - releaselog/3_3_13.html
  • Version 3.3.14 - releaselog/3_3_14.html
  • version 3.3.14 - releaselog/3_3_14.html
  • Version 3.3.15 - releaselog/3_3_15.html
  • version 3.3.15 - releaselog/3_3_15.html
  • Version 3.3.16 - releaselog/3_3_16.html
  • version 3.3.16 - releaselog/3_3_16.html
  • Version 3.3.17 - releaselog/3_3_17.html
  • version 3.3.17 - releaselog/3_3_17.html
  • Version 3.4.0 - releaselog/3_4_0.html
  • version 3.4.0 - releaselog/3_4_0.html
  • Version 3.4.1 - releaselog/3_4_1.html
  • version 3.4.1 - releaselog/3_4_1.html
  • Version 3.4.2 - releaselog/3_4_2.html
  • version 3.4.2 - releaselog/3_4_2.html
  • Version 3.5.0 - releaselog/3_5_0.html
  • version 3.5.0 - releaselog/3_5_0.html
  • Version 3.5.1 - releaselog/3_5_1.html
  • version 3.5.1 - releaselog/3_5_1.html
  • Version 3.5.2 - releaselog/3_5_2.html
  • version 3.5.2 - releaselog/3_5_2.html
  • Version 3.5.3 - releaselog/3_5_3.html
  • version 3.5.3 - releaselog/3_5_3.html
  • Version 3.5.4 - releaselog/3_5_4.html
  • version 3.5.4 - releaselog/3_5_4.html
  • Version 3.5.5 - releaselog/3_5_5.html
  • version 3.5.5 - releaselog/3_5_5.html
  • Version 3.5.6 - releaselog/3_5_6.html
  • version 3.5.6 - releaselog/3_5_6.html
  • Version 3.5.7 - releaselog/3_5_7.html
  • version 3.5.7 - releaselog/3_5_7.html
  • Version 3.5.8 - releaselog/3_5_8.html
  • version 3.5.8 - releaselog/3_5_8.html
  • Version 3.5.9 - releaselog/3_5_9.html
  • version 3.5.9 - releaselog/3_5_9.html
  • Version 3.6.0 - releaselog/3_6_0.html
  • version 3.6.0 - releaselog/3_6_0.html
  • Version 3.6.1 - releaselog/3_6_1.html
  • version 3.6.1 - releaselog/3_6_1.html
  • Version 3.6.2 - releaselog/3_6_2.html
  • version 3.6.2 - releaselog/3_6_2.html
  • Version 3.6.3 - releaselog/3_6_3.html
  • version 3.6.3 - releaselog/3_6_3.html
  • Version 3.6.4 - releaselog/3_6_4.html
  • version 3.6.4 - releaselog/3_6_4.html
  • Version 3.6.5 - releaselog/3_6_5.html
  • version 3.6.5 - releaselog/3_6_5.html
  • Version 3.6.6 - releaselog/3_6_6.html
  • version 3.6.6 - releaselog/3_6_6.html
  • Version 3.6.6.1 - releaselog/3_6_6_1.html
  • version 3.6.6.1 - releaselog/3_6_6_1.html
  • Version 3.6.6.2 - releaselog/3_6_6_2.html
  • version 3.6.6.2 - releaselog/3_6_6_2.html
  • Version 3.6.7 - releaselog/3_6_7.html
  • version 3.6.7 - releaselog/3_6_7.html
  • Version 3.6.8 - releaselog/3_6_8.html
  • version 3.6.8 - releaselog/3_6_8.html
  • Version 3.6.9 - releaselog/3_6_9.html
  • version 3.6.9 - releaselog/3_6_9.html
  • Version 3.6.10 - releaselog/3_6_10.html
  • version 3.6.10 - releaselog/3_6_10.html
  • Version 3.6.11 - releaselog/3_6_11.html
  • version 3.6.11 - releaselog/3_6_11.html
  • Version 3.6.12 - releaselog/3_6_12.html
  • version 3.6.12 - releaselog/3_6_12.html
  • Version 3.6.13 - releaselog/3_6_13.html
  • version 3.6.13 - releaselog/3_6_13.html
  • Version 3.6.14 - releaselog/3_6_14.html
  • version 3.6.14 - releaselog/3_6_14.html
  • Version 3.6.14.1 - releaselog/3_6_14_1.html
  • version 3.6.14.1 - releaselog/3_6_14_1.html
  • Version 3.6.14.2 - releaselog/3_6_14_2.html
  • version 3.6.14.2 - releaselog/3_6_14_2.html
  • Version 3.6.15 - releaselog/3_6_15.html
  • version 3.6.15 - releaselog/3_6_15.html
  • Version 3.6.16 - releaselog/3_6_16.html
  • version 3.6.16 - releaselog/3_6_16.html
  • Version 3.6.16.1 - releaselog/3_6_16_1.html
  • version 3.6.16.1 - releaselog/3_6_16_1.html
  • Version 3.6.17 - releaselog/3_6_17.html
  • version 3.6.17 - releaselog/3_6_17.html
  • Version 3.6.18 - releaselog/3_6_18.html
  • version 3.6.18 - releaselog/3_6_18.html
  • Version 3.6.19 - releaselog/3_6_19.html
  • version 3.6.19 - releaselog/3_6_19.html
  • Version 3.6.20 - releaselog/3_6_20.html
  • version 3.6.20 - releaselog/3_6_20.html
  • Version 3.6.21 - releaselog/3_6_21.html
  • version 3.6.21 - releaselog/3_6_21.html
  • Version 3.6.22 - releaselog/3_6_22.html
  • version 3.6.22 - releaselog/3_6_22.html
  • Version 3.6.23 - releaselog/3_6_23.html
  • version 3.6.23 - releaselog/3_6_23.html
  • Version 3.6.23.1 - releaselog/3_6_23_1.html
  • version 3.6.23.1 - releaselog/3_6_23_1.html
  • Version 3.7.0 - releaselog/3_7_0.html
  • version 3.7.0 - releaselog/3_7_0.html
  • Version 3.7.0.1 - releaselog/3_7_0_1.html
  • version 3.7.0.1 - releaselog/3_7_0_1.html
  • Version 3.7.1 - releaselog/3_7_1.html
  • version 3.7.1 - releaselog/3_7_1.html
  • Version 3.7.2 - releaselog/3_7_2.html
  • version 3.7.2 - releaselog/3_7_2.html
  • Version 3.7.3 - releaselog/3_7_3.html
  • version 3.7.3 - releaselog/3_7_3.html
  • Version 3.7.4 - releaselog/3_7_4.html
  • version 3.7.4 - releaselog/3_7_4.html
  • Version 3.7.5 - releaselog/3_7_5.html
  • version 3.7.5 - releaselog/3_7_5.html
  • Version 3.7.6 - releaselog/3_7_6.html
  • version 3.7.6 - releaselog/3_7_6.html
  • Version 3.7.6.1 - releaselog/3_7_6_1.html
  • version 3.7.6.1 - releaselog/3_7_6_1.html
  • Version 3.7.6.2 - releaselog/3_7_6_2.html
  • version 3.7.6.2 - releaselog/3_7_6_2.html
  • Version 3.7.6.3 - releaselog/3_7_6_3.html
  • version 3.7.6.3 - releaselog/3_7_6_3.html
  • Version 3.7.7 - releaselog/3_7_7.html
  • version 3.7.7 - releaselog/3_7_7.html
  • Version 3.7.7.1 - releaselog/3_7_7_1.html
  • version 3.7.7.1 - releaselog/3_7_7_1.html
  • Version 3.7.8 - releaselog/3_7_8.html
  • version 3.7.8 - releaselog/3_7_8.html
  • Version 3.7.9 - releaselog/3_7_9.html
  • version 3.7.9 - releaselog/3_7_9.html
  • version-valid-for number - fileformat2.html#validfor
  • VFS - vfs.html
  • VFSes - vfs.html
  • view - lang_createview.html
  • views - lang_createview.html
  • virtual machine instructions - opcode.html
  • virtual table - vtab.html
  • virtual table cursor - c3ref/vtab_cursor.html
  • virtual table module - c3ref/module.html
  • virtual tables - vtab.html
  • WAL - wal.html
  • WAL backwards compatibility - wal.html#bkwrds
  • WAL checksum algorithm - fileformat2.html#walcksm
  • WAL concurrency - wal.html#concurrency
  • WAL format - fileformat2.html#walformat
  • WAL mode - wal.html
  • WAL read algorithm - fileformat2.html#walread
  • WAL without shared memory - wal.html#noshm
  • wal-index - fileformat2.html#walindexformat
  • WAL-index format - fileformat2.html#walindexformat
  • wal_autocheckpoint - pragma.html#pragma_wal_autocheckpoint
  • wal_autocheckpoint pragma - pragma.html#pragma_wal_autocheckpoint
  • wal_checkpoint - pragma.html#pragma_wal_checkpoint
  • wal_checkpoint pragma - pragma.html#pragma_wal_checkpoint
  • WHERE clause - lang_select.html#whereclause
  • writable_schema - pragma.html#pragma_writable_schema
  • writable_schema pragma - pragma.html#pragma_writable_schema
  • write-ahead log - wal.html
  • writer starvation - lockingv3.html#writer_starvation
  • xBegin - vtab.html#xBegin
  • xBestIndex - vtab.html#xbestindex
  • xColumn - vtab.html#xcolumn
  • xCommit - vtab.html#xcommit
  • xConnect - vtab.html#xconnect
  • xCreate - vtab.html#xcreate
  • xDestroy - vtab.html#sqlite3_module.xDestroy
  • xDisconnect - vtab.html#xdisconnect
  • xEof - vtab.html#xeof
  • xFilter - vtab.html#xfilter
  • xFindFunction - vtab.html#xfindfunction
  • xNext - vtab.html#xnext
  • xRelease - vtab.html#xsavepoint
  • xRename - vtab.html#xrename
  • xRollback - vtab.html#xrollback
  • xRollbackTo - vtab.html#xsavepoint
  • xRowid - vtab.html#xrowid
  • xSavepoint - vtab.html#xsavepoint
  • xUpdate - vtab.html#xupdate
  • YYSTACKDEPTH - compile.html#yystackdepth
  • YYTRACKMAXSTACKDEPTH - compile.html#yytrackmaxstackdepth
  • zero-malloc memory allocator - malloc.html#memsys5
  • zeroblob - lang_corefunc.html#zeroblob
  • zeroblob SQL function - lang_corefunc.html#zeroblob


Pagelink Crossreference

Choose any three.
About Sitemap Documentation Download License News Support

Target Page - Which pages reference it.

Pages matching (news|changes|releaselog|[0-9]to[0-9]|^doc_.*_crossref) are skipped.

  • about.html - doclist.html docs.html sitemap.html
  • amalgamation.html - compile.html custombuild.html doclist.html faq.html features.html howtocompile.html keyword_index.html malloc.html privatebranch.html rtree.html selfcontained.html sitemap.html sqlite.html
  • arch.html - doclist.html docs.html sitemap.html vdbe.html
  • asyncvfs.html - doclist.html docs.html keyword_index.html sitemap.html
  • atomiccommit.html - doclist.html docs.html faq.html keyword_index.html lockingv3.html pragma.html sitemap.html tempfiles.html testing.html transactional.html wal.html
  • autoinc.html - c3ref/table_column_metadata.html capi3ref.html compile.html doclist.html faq.html keyword_index.html lang_createtable.html sitemap.html
  • backup.html - c3ref/backup.html c3ref/backup_finish.html capi3ref.html doclist.html docs.html howtocorrupt.html keyword_index.html sitemap.html wal.html
  • books.html - about.html doclist.html docs.html keyword_index.html sitemap.html
  • btreemodule.html - keyword_index.html
  • c3ref/aggregate_context.html - c3ref/context.html c3ref/funclist.html capi3ref.html cintro.html keyword_index.html
  • c3ref/aggregate_count.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/auto_extension.html - c3ref/funclist.html c3ref/reset_auto_extension.html capi3ref.html keyword_index.html
  • c3ref/backup.html - backup.html c3ref/backup_finish.html c3ref/objlist.html capi3ref.html keyword_index.html
  • c3ref/backup_finish.html - backup.html c3ref/backup.html c3ref/funclist.html capi3ref.html docs.html keyword_index.html
  • c3ref/bind_blob.html - c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/blob_open.html c3ref/clear_bindings.html c3ref/column_blob.html c3ref/funclist.html c3ref/prepare.html c3ref/reset.html c3ref/result_blob.html c3ref/stmt.html c3ref/value.html capi3.html capi3ref.html cintro.html compile.html keyword_index.html lang_expr.html limits.html optoverview.html
  • c3ref/bind_parameter_count.html - c3ref/bind_blob.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/bind_parameter_index.html - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_name.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/bind_parameter_name.html - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/funclist.html capi3ref.html keyword_index.html lang_expr.html
  • c3ref/blob.html - c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/close.html c3ref/objlist.html capi3ref.html compile.html keyword_index.html lang_transaction.html malloc.html
  • c3ref/blob_bytes.html - c3ref/blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/blob_close.html - c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/close.html c3ref/funclist.html capi3ref.html keyword_index.html lang_transaction.html
  • c3ref/blob_open.html - c3ref/bind_blob.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html keyword_index.html lang_corefunc.html tclsqlite.html
  • c3ref/blob_read.html - c3ref/blob.html c3ref/blob_open.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/blob_reopen.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/blob_write.html - c3ref/blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/busy_handler.html - backup.html c3ref/backup_finish.html c3ref/busy_timeout.html c3ref/funclist.html capi3ref.html faq.html keyword_index.html
  • c3ref/busy_timeout.html - backup.html c3ref/busy_handler.html c3ref/funclist.html c3ref/sqlite3.html capi3ref.html faq.html keyword_index.html
  • c3ref/c_abort.html - autoinc.html backup.html c3ref/auto_extension.html c3ref/backup_finish.html c3ref/bind_blob.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_busy_recovery.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_vtab_constraint_support.html c3ref/column_blob.html c3ref/config.html c3ref/constlist.html c3ref/create_function.html c3ref/data_count.html c3ref/db_status.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/finalize.html c3ref/free.html c3ref/get_autocommit.html c3ref/initialize.html c3ref/interrupt.html c3ref/intro.html c3ref/io_methods.html c3ref/load_extension.html c3ref/mutex_alloc.html c3ref/open.html c3ref/prepare.html c3ref/reset.html c3ref/set_authorizer.html c3ref/soft_heap_limit64.html c3ref/status.html c3ref/step.html c3ref/table_column_metadata.html c3ref/unlock_notify.html c3ref/vfs.html c3ref/vtab_on_conflict.html c3ref/wal_hook.html capi3ref.html compile.html faq.html keyword_index.html lang_createtrigger.html lang_transaction.html malloc.html pragma.html testing.html vfs.html vtab.html
  • c3ref/c_access_exists.html - c3ref/constlist.html c3ref/vfs.html capi3ref.html keyword_index.html
  • c3ref/c_alter_table.html - c3ref/constlist.html c3ref/set_authorizer.html c3ref/update_hook.html capi3ref.html keyword_index.html lang_delete.html
  • c3ref/c_any.html - c3ref/collation_needed.html c3ref/constlist.html c3ref/create_collation.html c3ref/create_function.html capi3ref.html keyword_index.html
  • c3ref/c_blob.html - c3ref/column_blob.html c3ref/constlist.html c3ref/value_blob.html capi3ref.html keyword_index.html
  • c3ref/c_busy_recovery.html - c3ref/backup_finish.html c3ref/blob_read.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_abort.html c3ref/c_config_getmalloc.html c3ref/constlist.html c3ref/errcode.html c3ref/extended_result_codes.html c3ref/finalize.html c3ref/prepare.html c3ref/step.html capi3ref.html keyword_index.html unlock_notify.html
  • c3ref/c_checkpoint_full.html - c3ref/constlist.html capi3ref.html keyword_index.html pragma.html
  • c3ref/c_config_getmalloc.html - c3ref/c_dbconfig_enable_fkey.html c3ref/c_status_malloc_count.html c3ref/config.html c3ref/constlist.html c3ref/log.html c3ref/mem_methods.html c3ref/mutex_alloc.html c3ref/mutex_methods.html c3ref/open.html c3ref/pcache_methods.html c3ref/soft_heap_limit64.html c3ref/threadsafe.html c3ref/value.html capi3ref.html compile.html custombuild.html keyword_index.html malloc.html selfcontained.html testing.html threadsafe.html uri.html
  • c3ref/c_dbconfig_enable_fkey.html - c3ref/c_config_getmalloc.html c3ref/constlist.html c3ref/db_config.html capi3ref.html keyword_index.html malloc.html
  • c3ref/c_dbstatus_options.html - c3ref/constlist.html c3ref/db_status.html capi3ref.html keyword_index.html malloc.html
  • c3ref/c_deny.html - c3ref/c_fail.html c3ref/constlist.html c3ref/set_authorizer.html c3ref/vtab_on_conflict.html capi3ref.html keyword_index.html lang_delete.html
  • c3ref/c_fail.html - c3ref/c_abort.html c3ref/c_deny.html c3ref/constlist.html c3ref/vtab_on_conflict.html capi3ref.html keyword_index.html
  • c3ref/c_fcntl_chunk_size.html - c3ref/constlist.html c3ref/file_control.html c3ref/io_methods.html capi3ref.html keyword_index.html
  • c3ref/c_index_constraint_eq.html - c3ref/constlist.html c3ref/index_info.html capi3ref.html keyword_index.html
  • c3ref/c_iocap_atomic.html - c3ref/constlist.html c3ref/io_methods.html capi3ref.html compile.html keyword_index.html
  • c3ref/c_limit_attached.html - c3ref/bind_blob.html c3ref/constlist.html c3ref/create_function.html c3ref/limit.html capi3ref.html foreignkeys.html keyword_index.html lang_attach.html lang_createindex.html lang_expr.html limits.html pragma.html
  • c3ref/c_lock_exclusive.html - c3ref/c_fcntl_chunk_size.html c3ref/constlist.html c3ref/io_methods.html capi3ref.html keyword_index.html
  • c3ref/c_mutex_fast.html - c3ref/constlist.html c3ref/mem_methods.html capi3ref.html keyword_index.html
  • c3ref/c_open_autoproxy.html - c3ref/c_config_getmalloc.html c3ref/constlist.html c3ref/intro.html c3ref/open.html c3ref/vfs.html capi3ref.html compile.html keyword_index.html sharedcache.html threadsafe.html uri.html
  • c3ref/c_shm_exclusive.html - c3ref/constlist.html capi3ref.html keyword_index.html
  • c3ref/c_shm_nlock.html - c3ref/constlist.html capi3ref.html keyword_index.html
  • c3ref/c_source_id.html - c3ref/constlist.html c3ref/libversion.html capi3ref.html fileformat2.html keyword_index.html
  • c3ref/c_static.html - c3ref/bind_blob.html c3ref/constlist.html capi3ref.html keyword_index.html
  • c3ref/c_status_malloc_count.html - c3ref/constlist.html c3ref/status.html capi3ref.html compile.html keyword_index.html malloc.html
  • c3ref/c_stmtstatus_counter.html - c3ref/constlist.html c3ref/stmt_status.html capi3ref.html keyword_index.html lang_indexedby.html
  • c3ref/c_sync_dataonly.html - c3ref/constlist.html c3ref/io_methods.html capi3ref.html keyword_index.html
  • c3ref/c_testctrl_always.html - c3ref/constlist.html capi3ref.html keyword_index.html testing.html
  • c3ref/c_vtab_constraint_support.html - c3ref/constlist.html c3ref/vtab_config.html capi3ref.html keyword_index.html
  • c3ref/clear_bindings.html - c3ref/funclist.html c3ref/reset.html capi3ref.html keyword_index.html
  • c3ref/close.html - backup.html c3ref/create_collation.html c3ref/funclist.html c3ref/open.html c3ref/sqlite3.html c3ref/unlock_notify.html capi3.html capi3ref.html cintro.html keyword_index.html malloc.html quickstart.html tempfiles.html
  • c3ref/collation_needed.html - c3ref/create_collation.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/column_blob.html - c3ref/data_count.html c3ref/exec.html c3ref/free_table.html c3ref/funclist.html c3ref/step.html c3ref/value.html c3ref/value_blob.html capi3.html capi3ref.html cintro.html compile.html keyword_index.html
  • c3ref/column_count.html - c3ref/column_blob.html c3ref/data_count.html c3ref/funclist.html capi3.html capi3ref.html cintro.html keyword_index.html
  • c3ref/column_database_name.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/column_decltype.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/column_name.html - c3ref/exec.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/commit_hook.html - c3ref/funclist.html c3ref/update_hook.html capi3ref.html keyword_index.html
  • c3ref/compileoption_get.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html lang_corefunc.html pragma.html
  • c3ref/complete.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html tclsqlite.html
  • c3ref/config.html - c3ref/c_config_getmalloc.html c3ref/db_config.html c3ref/funclist.html c3ref/initialize.html c3ref/log.html c3ref/mem_methods.html c3ref/open.html c3ref/pcache_methods.html c3ref/soft_heap_limit64.html c3ref/threadsafe.html capi3ref.html compile.html custombuild.html keyword_index.html malloc.html privatebranch.html selfcontained.html testing.html threadsafe.html uri.html
  • c3ref/constlist.html -
  • c3ref/context.html - c3ref/aggregate_context.html c3ref/objlist.html c3ref/result_blob.html capi3ref.html keyword_index.html
  • c3ref/context_db_handle.html - c3ref/context.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/create_collation.html - c3ref/collation_needed.html c3ref/funclist.html capi3ref.html cintro.html datatype3.html different.html faq.html fileformat2.html keyword_index.html
  • c3ref/create_function.html - c3ref/context.html c3ref/context_db_handle.html c3ref/funclist.html c3ref/result_blob.html c3ref/sqlite3.html c3ref/stmt_readonly.html c3ref/user_data.html c3ref/value.html c3ref/value_blob.html capi3ref.html cintro.html different.html faq.html fts3.html keyword_index.html lang_aggfunc.html lang_corefunc.html lang_expr.html pragma.html rtree.html
  • c3ref/create_module.html - c3ref/funclist.html c3ref/module.html capi3ref.html cintro.html keyword_index.html lang_createvtab.html rtree.html vtab.html
  • c3ref/data_count.html - c3ref/column_count.html c3ref/funclist.html capi3.html capi3ref.html keyword_index.html
  • c3ref/db_config.html - c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/funclist.html capi3ref.html keyword_index.html malloc.html privatebranch.html
  • c3ref/db_handle.html - c3ref/funclist.html capi3ref.html keyword_index.html unlock_notify.html
  • c3ref/db_mutex.html - c3ref/errcode.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/db_status.html - c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/funclist.html c3ref/status.html c3ref/stmt_status.html capi3ref.html keyword_index.html malloc.html
  • c3ref/declare_vtab.html - c3ref/funclist.html capi3ref.html fts3.html keyword_index.html vtab.html
  • c3ref/enable_load_extension.html - c3ref/funclist.html c3ref/load_extension.html capi3ref.html compile.html keyword_index.html tclsqlite.html
  • c3ref/enable_shared_cache.html - c3ref/funclist.html c3ref/open.html capi3ref.html compile.html keyword_index.html pragma.html sharedcache.html
  • c3ref/errcode.html - backup.html c3ref/backup_finish.html c3ref/blob_open.html c3ref/column_blob.html c3ref/file_control.html c3ref/free_table.html c3ref/funclist.html c3ref/open.html c3ref/step.html capi3ref.html keyword_index.html
  • c3ref/exec.html - backup.html c3ref/free_table.html c3ref/funclist.html c3ref/progress_handler.html c3ref/stmt_readonly.html capi3.html capi3ref.html cintro.html faq.html keyword_index.html lang.html pragma.html quickstart.html
  • c3ref/experimental.html - c3ref/aggregate_count.html c3ref/constlist.html c3ref/funclist.html c3ref/objlist.html capi3ref.html keyword_index.html
  • c3ref/extended_result_codes.html - c3ref/c_busy_recovery.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/file.html - c3ref/c_fcntl_chunk_size.html c3ref/file_control.html c3ref/io_methods.html c3ref/objlist.html c3ref/vfs.html capi3ref.html keyword_index.html vfs.html
  • c3ref/file_control.html - c3ref/c_fcntl_chunk_size.html c3ref/funclist.html c3ref/io_methods.html capi3ref.html keyword_index.html
  • c3ref/finalize.html - c3ref/close.html c3ref/column_blob.html c3ref/column_database_name.html c3ref/column_name.html c3ref/exec.html c3ref/funclist.html c3ref/prepare.html c3ref/step.html c3ref/stmt.html capi3ref.html cintro.html faq.html keyword_index.html lang_transaction.html malloc.html pragma.html tclsqlite.html
  • c3ref/free.html - c3ref/auto_extension.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_status_malloc_count.html c3ref/column_blob.html c3ref/exec.html c3ref/free_table.html c3ref/funclist.html c3ref/index_info.html c3ref/load_extension.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/mprintf.html c3ref/mutex_methods.html c3ref/result_blob.html c3ref/temp_directory.html c3ref/vtab.html capi3ref.html custombuild.html keyword_index.html malloc.html vtab.html
  • c3ref/free_table.html - c3ref/funclist.html c3ref/progress_handler.html capi3ref.html cintro.html compile.html keyword_index.html lang.html
  • c3ref/funclist.html - about.html cintro.html index.html keyword_index.html sitemap.html
  • c3ref/get_autocommit.html - c3ref/blob_close.html c3ref/funclist.html capi3ref.html foreignkeys.html keyword_index.html lang_transaction.html
  • c3ref/get_auxdata.html - c3ref/context.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/index_info.html - c3ref/c_index_constraint_eq.html c3ref/objlist.html capi3ref.html keyword_index.html vtab.html
  • c3ref/initialize.html - c3ref/complete.html c3ref/config.html c3ref/funclist.html c3ref/mem_methods.html c3ref/mutex_methods.html c3ref/pcache_methods.html capi3ref.html compile.html custombuild.html keyword_index.html
  • c3ref/int64.html - c3ref/intro.html c3ref/objlist.html capi3ref.html keyword_index.html
  • c3ref/interrupt.html - c3ref/funclist.html capi3ref.html keyword_index.html lang_transaction.html
  • c3ref/intro.html - about.html capi3.html capi3ref.html cintro.html docs.html features.html index.html keyword_index.html quickstart.html sitemap.html
  • c3ref/io_methods.html - c3ref/c_fcntl_chunk_size.html c3ref/c_iocap_atomic.html c3ref/c_lock_exclusive.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_sync_dataonly.html c3ref/file.html c3ref/file_control.html c3ref/objlist.html c3ref/vfs.html capi3ref.html compile.html fileformat2.html keyword_index.html pragma.html vfs.html wal.html
  • c3ref/last_insert_rowid.html - c3ref/funclist.html capi3ref.html faq.html keyword_index.html lang_corefunc.html vtab.html
  • c3ref/libversion.html - c3ref/c_source_id.html c3ref/funclist.html capi3ref.html keyword_index.html lang_corefunc.html
  • c3ref/limit.html - c3ref/bind_blob.html c3ref/c_limit_attached.html c3ref/create_function.html c3ref/funclist.html c3ref/set_authorizer.html capi3ref.html compile.html keyword_index.html lang_attach.html lang_createindex.html lang_createtable.html lang_expr.html limits.html pragma.html privatebranch.html
  • c3ref/load_extension.html - c3ref/enable_load_extension.html c3ref/funclist.html capi3ref.html compile.html howtocompile.html keyword_index.html lang_corefunc.html vtab.html
  • c3ref/log.html - c3ref/c_config_getmalloc.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/mem_methods.html - c3ref/c_config_getmalloc.html c3ref/c_status_malloc_count.html c3ref/objlist.html capi3ref.html custombuild.html keyword_index.html malloc.html
  • c3ref/memory_highwater.html - c3ref/c_config_getmalloc.html c3ref/funclist.html capi3ref.html custombuild.html keyword_index.html
  • c3ref/module.html - c3ref/create_module.html c3ref/declare_vtab.html c3ref/index_info.html c3ref/objlist.html c3ref/overload_function.html c3ref/vtab.html c3ref/vtab_cursor.html capi3ref.html keyword_index.html vtab.html
  • c3ref/mprintf.html - c3ref/auto_extension.html c3ref/c_config_getmalloc.html c3ref/column_blob.html c3ref/funclist.html c3ref/log.html c3ref/vtab.html capi3ref.html compile.html keyword_index.html lang_expr.html vtab.html
  • c3ref/mutex.html - c3ref/db_mutex.html c3ref/objlist.html capi3ref.html keyword_index.html
  • c3ref/mutex_alloc.html - c3ref/c_mutex_fast.html c3ref/errcode.html c3ref/funclist.html c3ref/mutex.html c3ref/mutex_methods.html capi3ref.html custombuild.html keyword_index.html
  • c3ref/mutex_held.html - c3ref/funclist.html c3ref/mutex_alloc.html c3ref/mutex_methods.html capi3ref.html keyword_index.html testing.html
  • c3ref/mutex_methods.html - c3ref/c_config_getmalloc.html c3ref/objlist.html capi3ref.html keyword_index.html
  • c3ref/next_stmt.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/objlist.html -
  • c3ref/open.html - atomiccommit.html backup.html c3ref/auto_extension.html c3ref/c_config_getmalloc.html c3ref/c_open_autoproxy.html c3ref/close.html c3ref/enable_shared_cache.html c3ref/funclist.html c3ref/initialize.html c3ref/prepare.html c3ref/sqlite3.html c3ref/vfs.html capi3.html capi3ref.html cintro.html compile.html custombuild.html faq.html howtocorrupt.html inmemorydb.html keyword_index.html lang_attach.html malloc.html pragma.html quickstart.html sharedcache.html shortnames.html tempfiles.html threadsafe.html uri.html vfs.html
  • c3ref/overload_function.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/pcache.html - c3ref/objlist.html c3ref/pcache_methods.html capi3ref.html keyword_index.html
  • c3ref/pcache_methods.html - btreemodule.html c3ref/c_config_getmalloc.html c3ref/objlist.html c3ref/pcache.html capi3ref.html compile.html keyword_index.html pragma.html
  • c3ref/prepare.html - c3ref/bind_blob.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/column_blob.html c3ref/commit_hook.html c3ref/db_handle.html c3ref/exec.html c3ref/funclist.html c3ref/progress_handler.html c3ref/set_authorizer.html c3ref/sql.html c3ref/sqlite3.html c3ref/step.html c3ref/stmt.html c3ref/update_hook.html capi3.html capi3ref.html cintro.html compile.html faq.html keyword_index.html lang.html lang_comment.html limits.html malloc.html optoverview.html pragma.html tclsqlite.html unlock_notify.html vfs.html vtab.html
  • c3ref/profile.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/progress_handler.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/randomness.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/release_memory.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/reset.html - c3ref/bind_blob.html c3ref/clear_bindings.html c3ref/column_blob.html c3ref/finalize.html c3ref/funclist.html c3ref/prepare.html c3ref/step.html c3ref/stmt.html capi3ref.html cintro.html compile.html keyword_index.html lang_transaction.html unlock_notify.html
  • c3ref/reset_auto_extension.html - c3ref/auto_extension.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/result_blob.html - c3ref/blob_open.html c3ref/c_static.html c3ref/column_blob.html c3ref/context.html c3ref/funclist.html c3ref/value.html capi3ref.html cintro.html compile.html keyword_index.html lang_corefunc.html vtab.html
  • c3ref/set_authorizer.html - c3ref/c_alter_table.html c3ref/c_deny.html c3ref/c_fail.html c3ref/funclist.html c3ref/limit.html capi3ref.html compile.html fts3.html keyword_index.html lang_delete.html tclsqlite.html
  • c3ref/sleep.html - backup.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/soft_heap_limit.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/soft_heap_limit64.html - c3ref/c_config_getmalloc.html c3ref/funclist.html c3ref/soft_heap_limit.html capi3ref.html custombuild.html keyword_index.html malloc.html
  • c3ref/sql.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/sqlite3.html - atomiccommit.html backup.html c3ref/auto_extension.html c3ref/backup_finish.html c3ref/blob_open.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/close.html c3ref/collation_needed.html c3ref/commit_hook.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/initialize.html c3ref/interrupt.html c3ref/intro.html c3ref/last_insert_rowid.html c3ref/limit.html c3ref/module.html c3ref/next_stmt.html c3ref/objlist.html c3ref/open.html c3ref/prepare.html c3ref/progress_handler.html c3ref/set_authorizer.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/update_hook.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html capi3ref.html cintro.html compile.html custombuild.html fileformat2.html foreignkeys.html keyword_index.html lang_attach.html lang_expr.html lang_transaction.html malloc.html pragma.html requirements.html sharedcache.html tempfiles.html unlock_notify.html vfs.html vtab.html
  • c3ref/status.html - c3ref/c_config_getmalloc.html c3ref/c_status_malloc_count.html c3ref/db_status.html c3ref/funclist.html c3ref/stmt_status.html capi3ref.html compile.html keyword_index.html malloc.html
  • c3ref/step.html - backup.html c3ref/bind_blob.html c3ref/busy_timeout.html c3ref/column_blob.html c3ref/column_database_name.html c3ref/column_name.html c3ref/commit_hook.html c3ref/data_count.html c3ref/exec.html c3ref/finalize.html c3ref/funclist.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/reset.html c3ref/set_authorizer.html c3ref/stmt.html c3ref/unlock_notify.html c3ref/update_hook.html capi3.html capi3ref.html cintro.html compile.html faq.html keyword_index.html malloc.html optoverview.html pragma.html unlock_notify.html vfs.html
  • c3ref/stmt.html - c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_name.html c3ref/busy_handler.html c3ref/c_config_getmalloc.html c3ref/clear_bindings.html c3ref/close.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/data_count.html c3ref/db_handle.html c3ref/finalize.html c3ref/intro.html c3ref/next_stmt.html c3ref/objlist.html c3ref/prepare.html c3ref/reset.html c3ref/set_authorizer.html c3ref/sql.html c3ref/step.html c3ref/stmt_readonly.html c3ref/stmt_status.html c3ref/value_blob.html capi3ref.html cintro.html compile.html custombuild.html datatype3.html faq.html keyword_index.html malloc.html optoverview.html unlock_notify.html vfs.html
  • c3ref/stmt_readonly.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/stmt_status.html - c3ref/c_stmtstatus_counter.html c3ref/db_status.html c3ref/funclist.html capi3ref.html keyword_index.html lang_indexedby.html tclsqlite.html
  • c3ref/strnicmp.html - c3ref/create_collation.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/table_column_metadata.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html
  • c3ref/temp_directory.html - c3ref/objlist.html capi3ref.html keyword_index.html pragma.html
  • c3ref/test_control.html - c3ref/c_testctrl_always.html c3ref/funclist.html capi3ref.html compile.html keyword_index.html testing.html
  • c3ref/threadsafe.html - c3ref/funclist.html c3ref/value.html capi3ref.html compile.html custombuild.html faq.html keyword_index.html threadsafe.html
  • c3ref/unlock_notify.html - c3ref/funclist.html capi3ref.html compile.html keyword_index.html unlock_notify.html
  • c3ref/update_hook.html - c3ref/commit_hook.html c3ref/funclist.html capi3ref.html keyword_index.html lang_conflict.html
  • c3ref/uri_parameter.html - c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/user_data.html - c3ref/context.html c3ref/create_function.html c3ref/funclist.html capi3ref.html cintro.html keyword_index.html
  • c3ref/value.html - c3ref/column_blob.html c3ref/objlist.html c3ref/result_blob.html c3ref/value_blob.html capi3ref.html keyword_index.html
  • c3ref/value_blob.html - c3ref/column_blob.html c3ref/funclist.html c3ref/value.html capi3ref.html cintro.html compile.html keyword_index.html
  • c3ref/vfs.html - asyncvfs.html btreemodule.html c3ref/c_access_exists.html c3ref/c_open_autoproxy.html c3ref/file.html c3ref/initialize.html c3ref/io_methods.html c3ref/objlist.html c3ref/open.html c3ref/randomness.html c3ref/sleep.html c3ref/temp_directory.html c3ref/vfs_find.html capi3ref.html compile.html custombuild.html howtocorrupt.html keyword_index.html lang_datefunc.html testing.html vfs.html
  • c3ref/vfs_find.html - asyncvfs.html c3ref/funclist.html c3ref/vfs.html capi3ref.html compile.html custombuild.html keyword_index.html privatebranch.html uri.html vfs.html
  • c3ref/vtab.html - c3ref/objlist.html capi3ref.html compile.html keyword_index.html vtab.html
  • c3ref/vtab_config.html - c3ref/c_vtab_constraint_support.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/vtab_cursor.html - c3ref/objlist.html capi3ref.html keyword_index.html vtab.html
  • c3ref/vtab_on_conflict.html - c3ref/c_abort.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_vtab_constraint_support.html c3ref/funclist.html capi3ref.html keyword_index.html
  • c3ref/wal_autocheckpoint.html - c3ref/funclist.html c3ref/wal_checkpoint.html c3ref/wal_hook.html capi3ref.html keyword_index.html pragma.html wal.html
  • c3ref/wal_checkpoint.html - c3ref/funclist.html capi3ref.html keyword_index.html pragma.html wal.html
  • c3ref/wal_checkpoint_v2.html - c3ref/c_checkpoint_full.html c3ref/funclist.html c3ref/wal_checkpoint.html capi3ref.html keyword_index.html pragma.html
  • c3ref/wal_hook.html - c3ref/funclist.html c3ref/wal_autocheckpoint.html capi3ref.html keyword_index.html wal.html
  • c_interface.html - doclist.html docs.html sitemap.html
  • capi3.html - doclist.html docs.html sitemap.html
  • capi3ref.html - arch.html c3ref/intro.html doclist.html sitemap.html
  • cintro.html - about.html c3ref/intro.html capi3.html capi3ref.html doclist.html docs.html index.html quickstart.html sitemap.html
  • compile.html - c3ref/c_config_getmalloc.html c3ref/c_status_malloc_count.html c3ref/column_database_name.html c3ref/compileoption_get.html c3ref/free.html c3ref/initialize.html c3ref/open.html c3ref/prepare.html c3ref/release_memory.html c3ref/soft_heap_limit64.html c3ref/step.html c3ref/table_column_metadata.html c3ref/threadsafe.html c3ref/unlock_notify.html c3ref/value.html c3ref/wal_autocheckpoint.html capi3ref.html doclist.html docs.html faq.html fileformat2.html footprint.html foreignkeys.html fts3.html howtocompile.html inmemorydb.html keyword_index.html lang_analyze.html lang_corefunc.html lang_createtrigger.html lang_delete.html lang_keywords.html lang_update.html malloc.html optoverview.html pragma.html privatebranch.html rtree.html shortnames.html sitemap.html tempfiles.html testing.html threadsafe.html unlock_notify.html uri.html wal.html
  • conflict.html - doclist.html sitemap.html
  • consortium.html - doclist.html index.html keyword_index.html sitemap.html testing.html th3.html
  • consortium_agreement-20071201.html - consortium.html
  • constlist.html - c3ref/aggregate_context.html c3ref/aggregate_count.html c3ref/auto_extension.html c3ref/backup.html c3ref/backup_finish.html c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_abort.html c3ref/c_access_exists.html c3ref/c_alter_table.html c3ref/c_any.html c3ref/c_blob.html c3ref/c_busy_recovery.html c3ref/c_checkpoint_full.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_fcntl_chunk_size.html c3ref/c_index_constraint_eq.html c3ref/c_iocap_atomic.html c3ref/c_limit_attached.html c3ref/c_lock_exclusive.html c3ref/c_mutex_fast.html c3ref/c_open_autoproxy.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_source_id.html c3ref/c_static.html c3ref/c_status_malloc_count.html c3ref/c_stmtstatus_counter.html c3ref/c_sync_dataonly.html c3ref/c_testctrl_always.html c3ref/c_vtab_constraint_support.html c3ref/clear_bindings.html c3ref/close.html c3ref/collation_needed.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/commit_hook.html c3ref/compileoption_get.html c3ref/complete.html c3ref/config.html c3ref/context.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/data_count.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/declare_vtab.html c3ref/enable_load_extension.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/extended_result_codes.html c3ref/file.html c3ref/file_control.html c3ref/finalize.html c3ref/free.html c3ref/free_table.html c3ref/funclist.html c3ref/get_autocommit.html c3ref/get_auxdata.html c3ref/index_info.html c3ref/initialize.html c3ref/int64.html c3ref/interrupt.html c3ref/intro.html c3ref/io_methods.html c3ref/last_insert_rowid.html c3ref/libversion.html c3ref/limit.html c3ref/load_extension.html c3ref/log.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/module.html c3ref/mprintf.html c3ref/mutex.html c3ref/mutex_alloc.html c3ref/mutex_held.html c3ref/mutex_methods.html c3ref/next_stmt.html c3ref/objlist.html c3ref/open.html c3ref/overload_function.html c3ref/pcache.html c3ref/pcache_methods.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/randomness.html c3ref/release_memory.html c3ref/reset.html c3ref/reset_auto_extension.html c3ref/result_blob.html c3ref/set_authorizer.html c3ref/sleep.html c3ref/soft_heap_limit.html c3ref/soft_heap_limit64.html c3ref/sql.html c3ref/sqlite3.html c3ref/status.html c3ref/step.html c3ref/stmt.html c3ref/stmt_readonly.html c3ref/stmt_status.html c3ref/strnicmp.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/test_control.html c3ref/threadsafe.html c3ref/unlock_notify.html c3ref/update_hook.html c3ref/uri_parameter.html c3ref/user_data.html c3ref/value.html c3ref/value_blob.html c3ref/vfs.html c3ref/vfs_find.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_checkpoint_v2.html c3ref/wal_hook.html session/funclist.html session/intro.html session/objlist.html
  • copyright-release.html - copyright.html
  • copyright.html - about.html doclist.html docs.html famous.html faq.html features.html index.html sitemap.html support.html th3.html
  • crew.html - about.html doclist.html sitemap.html
  • custombuild.html - c3ref/initialize.html capi3ref.html doclist.html docs.html keyword_index.html sitemap.html
  • datatype3.html - c3ref/create_collation.html capi3ref.html doclist.html docs.html faq.html fileformat2.html foreignkeys.html fts3.html keyword_index.html lang_corefunc.html lang_createtable.html lang_expr.html lang_select.html optoverview.html sitemap.html version3.html
  • datatypes.html - doclist.html docs.html sitemap.html
  • dev.html - doclist.html sitemap.html
  • different.html - doclist.html docs.html sitemap.html tempfiles.html
  • doclist.html - docs.html keyword_index.html sitemap.html
  • docs.html - doclist.html keyword_index.html sitemap.html
  • download.html - amalgamation.html doclist.html howtocompile.html keyword_index.html quickstart.html sitemap.html
  • eqp.html - doclist.html keyword_index.html lang_explain.html sitemap.html
  • famous.html - about.html doclist.html index.html sitemap.html
  • faq.html - about.html doclist.html docs.html index.html sitemap.html
  • features.html - about.html doclist.html index.html sitemap.html
  • fileformat.html - btreemodule.html fts3.html vdbe.html
  • fileformat2.html - atomiccommit.html compile.html doclist.html docs.html keyword_index.html onefile.html opcode.html pragma.html sitemap.html version3.html vfs.html wal.html
  • fileio.html - keyword_index.html
  • footprint.html - about.html compile.html doclist.html features.html keyword_index.html sitemap.html
  • foreignkeys.html - c3ref/blob_open.html c3ref/c_dbconfig_enable_fkey.html capi3ref.html compile.html doclist.html docs.html faq.html keyword_index.html lang_altertable.html lang_conflict.html lang_createtable.html lang_droptable.html pragma.html sitemap.html
  • formatchng.html - doclist.html docs.html sitemap.html
  • fts3.html - amalgamation.html doclist.html docs.html keyword_index.html sitemap.html vtab.html
  • funclist.html - c3ref/aggregate_context.html c3ref/aggregate_count.html c3ref/auto_extension.html c3ref/backup.html c3ref/backup_finish.html c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_abort.html c3ref/c_access_exists.html c3ref/c_alter_table.html c3ref/c_any.html c3ref/c_blob.html c3ref/c_busy_recovery.html c3ref/c_checkpoint_full.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_fcntl_chunk_size.html c3ref/c_index_constraint_eq.html c3ref/c_iocap_atomic.html c3ref/c_limit_attached.html c3ref/c_lock_exclusive.html c3ref/c_mutex_fast.html c3ref/c_open_autoproxy.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_source_id.html c3ref/c_static.html c3ref/c_status_malloc_count.html c3ref/c_stmtstatus_counter.html c3ref/c_sync_dataonly.html c3ref/c_testctrl_always.html c3ref/c_vtab_constraint_support.html c3ref/clear_bindings.html c3ref/close.html c3ref/collation_needed.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/commit_hook.html c3ref/compileoption_get.html c3ref/complete.html c3ref/config.html c3ref/constlist.html c3ref/context.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/data_count.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/declare_vtab.html c3ref/enable_load_extension.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/extended_result_codes.html c3ref/file.html c3ref/file_control.html c3ref/finalize.html c3ref/free.html c3ref/free_table.html c3ref/get_autocommit.html c3ref/get_auxdata.html c3ref/index_info.html c3ref/initialize.html c3ref/int64.html c3ref/interrupt.html c3ref/intro.html c3ref/io_methods.html c3ref/last_insert_rowid.html c3ref/libversion.html c3ref/limit.html c3ref/load_extension.html c3ref/log.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/module.html c3ref/mprintf.html c3ref/mutex.html c3ref/mutex_alloc.html c3ref/mutex_held.html c3ref/mutex_methods.html c3ref/next_stmt.html c3ref/objlist.html c3ref/open.html c3ref/overload_function.html c3ref/pcache.html c3ref/pcache_methods.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/randomness.html c3ref/release_memory.html c3ref/reset.html c3ref/reset_auto_extension.html c3ref/result_blob.html c3ref/set_authorizer.html c3ref/sleep.html c3ref/soft_heap_limit.html c3ref/soft_heap_limit64.html c3ref/sql.html c3ref/sqlite3.html c3ref/status.html c3ref/step.html c3ref/stmt.html c3ref/stmt_readonly.html c3ref/stmt_status.html c3ref/strnicmp.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/test_control.html c3ref/threadsafe.html c3ref/unlock_notify.html c3ref/update_hook.html c3ref/uri_parameter.html c3ref/user_data.html c3ref/value.html c3ref/value_blob.html c3ref/vfs.html c3ref/vfs_find.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_checkpoint_v2.html c3ref/wal_hook.html session/constlist.html session/intro.html session/objlist.html
  • hlr10000.html - requirements.html
  • hlr20000.html - requirements.html
  • hlr30000.html - requirements.html
  • hlr40000.html - requirements.html
  • howtocompile.html - doclist.html keyword_index.html sitemap.html
  • howtocorrupt.html - doclist.html keyword_index.html shortnames.html sitemap.html
  • index.html - doclist.html sitemap.html
  • inmemorydb.html - compile.html doclist.html docs.html keyword_index.html lang_attach.html pragma.html sitemap.html tclsqlite.html
  • intern-v-extern-blob.html - doclist.html sitemap.html
  • intro.html - c3ref/aggregate_context.html c3ref/aggregate_count.html c3ref/auto_extension.html c3ref/backup.html c3ref/backup_finish.html c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_abort.html c3ref/c_access_exists.html c3ref/c_alter_table.html c3ref/c_any.html c3ref/c_blob.html c3ref/c_busy_recovery.html c3ref/c_checkpoint_full.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_fcntl_chunk_size.html c3ref/c_index_constraint_eq.html c3ref/c_iocap_atomic.html c3ref/c_limit_attached.html c3ref/c_lock_exclusive.html c3ref/c_mutex_fast.html c3ref/c_open_autoproxy.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_source_id.html c3ref/c_static.html c3ref/c_status_malloc_count.html c3ref/c_stmtstatus_counter.html c3ref/c_sync_dataonly.html c3ref/c_testctrl_always.html c3ref/c_vtab_constraint_support.html c3ref/clear_bindings.html c3ref/close.html c3ref/collation_needed.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/commit_hook.html c3ref/compileoption_get.html c3ref/complete.html c3ref/config.html c3ref/constlist.html c3ref/context.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/data_count.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/declare_vtab.html c3ref/enable_load_extension.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/experimental.html c3ref/extended_result_codes.html c3ref/file.html c3ref/file_control.html c3ref/finalize.html c3ref/free.html c3ref/free_table.html c3ref/funclist.html c3ref/get_autocommit.html c3ref/get_auxdata.html c3ref/index_info.html c3ref/initialize.html c3ref/int64.html c3ref/interrupt.html c3ref/io_methods.html c3ref/last_insert_rowid.html c3ref/libversion.html c3ref/limit.html c3ref/load_extension.html c3ref/log.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/module.html c3ref/mprintf.html c3ref/mutex.html c3ref/mutex_alloc.html c3ref/mutex_held.html c3ref/mutex_methods.html c3ref/next_stmt.html c3ref/objlist.html c3ref/open.html c3ref/overload_function.html c3ref/pcache.html c3ref/pcache_methods.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/randomness.html c3ref/release_memory.html c3ref/reset.html c3ref/reset_auto_extension.html c3ref/result_blob.html c3ref/set_authorizer.html c3ref/sleep.html c3ref/soft_heap_limit.html c3ref/soft_heap_limit64.html c3ref/sql.html c3ref/sqlite3.html c3ref/status.html c3ref/step.html c3ref/stmt.html c3ref/stmt_readonly.html c3ref/stmt_status.html c3ref/strnicmp.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/test_control.html c3ref/threadsafe.html c3ref/unlock_notify.html c3ref/update_hook.html c3ref/uri_parameter.html c3ref/user_data.html c3ref/value.html c3ref/value_blob.html c3ref/vfs.html c3ref/vfs_find.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_checkpoint_v2.html c3ref/wal_hook.html session/constlist.html session/funclist.html session/objlist.html
  • keyword_index.html - doclist.html docs.html sitemap.html
  • lang.html - about.html doclist.html docs.html index.html lang_aggfunc.html lang_altertable.html lang_analyze.html lang_attach.html lang_comment.html lang_conflict.html lang_corefunc.html lang_createindex.html lang_createtable.html lang_createtrigger.html lang_createview.html lang_createvtab.html lang_datefunc.html lang_delete.html lang_detach.html lang_dropindex.html lang_droptable.html lang_droptrigger.html lang_dropview.html lang_explain.html lang_expr.html lang_indexedby.html lang_insert.html lang_keywords.html lang_naming.html lang_reindex.html lang_replace.html lang_savepoint.html lang_select.html lang_transaction.html lang_update.html lang_vacuum.html sitemap.html syntaxdiagrams.html tclsqlite.html
  • lang_aggfunc.html - about.html index.html keyword_index.html lang.html lang_corefunc.html lang_expr.html sitemap.html
  • lang_altertable.html - compile.html faq.html fileformat2.html foreignkeys.html formatchng.html keyword_index.html lang.html lang_analyze.html lang_createtrigger.html lang_naming.html syntaxdiagrams.html vtab.html
  • lang_analyze.html - compile.html eqp.html keyword_index.html lang.html optoverview.html queryplanner.html syntaxdiagrams.html
  • lang_attach.html - atomiccommit.html c3ref/backup_finish.html c3ref/blob_open.html c3ref/c_config_getmalloc.html c3ref/c_dbstatus_options.html c3ref/c_limit_attached.html c3ref/file_control.html c3ref/stmt_readonly.html c3ref/wal_hook.html capi3ref.html cintro.html compile.html different.html inmemorydb.html keyword_index.html lang.html lang_createtable.html lang_detach.html lang_naming.html limits.html lockingv3.html pragma.html shortnames.html syntaxdiagrams.html tclsqlite.html tempfiles.html uri.html vfs.html vtab.html wal.html
  • lang_comment.html - keyword_index.html lang.html syntaxdiagrams.html
  • lang_conflict.html - c3ref/blob_open.html c3ref/c_fail.html c3ref/c_vtab_constraint_support.html c3ref/update_hook.html c3ref/vtab_on_conflict.html capi3ref.html different.html keyword_index.html lang.html lang_createtable.html lang_createtrigger.html lang_insert.html lang_replace.html lang_transaction.html lang_update.html syntaxdiagrams.html tempfiles.html
  • lang_corefunc.html - about.html c3ref/blob_open.html c3ref/c_source_id.html c3ref/compileoption_get.html c3ref/last_insert_rowid.html c3ref/libversion.html c3ref/load_extension.html capi3ref.html compile.html faq.html howtocompile.html index.html keyword_index.html lang.html lang_expr.html optoverview.html pragma.html sitemap.html tclsqlite.html
  • lang_createindex.html - compile.html fileformat2.html foreignkeys.html keyword_index.html lang.html lang_createtable.html lang_dropindex.html syntaxdiagrams.html vtab.html
  • lang_createtable.html - autoinc.html c3ref/blob_open.html c3ref/last_insert_rowid.html c3ref/randomness.html c3ref/table_column_metadata.html c3ref/update_hook.html capi3ref.html compile.html datatype3.html eqp.html faq.html fileformat2.html foreignkeys.html fts3.html keyword_index.html lang.html lang_altertable.html lang_corefunc.html lang_createindex.html lang_createvtab.html lang_droptable.html lang_expr.html lang_vacuum.html optoverview.html queryplanner.html syntaxdiagrams.html vtab.html
  • lang_createtrigger.html - c3ref/c_dbconfig_enable_fkey.html capi3ref.html compile.html faq.html fileformat2.html foreignkeys.html keyword_index.html lang.html lang_conflict.html lang_createtable.html lang_createview.html lang_delete.html lang_droptrigger.html lang_insert.html lang_update.html pragma.html syntaxdiagrams.html
  • lang_createview.html - compile.html fileformat2.html keyword_index.html lang.html lang_createtrigger.html lang_dropview.html syntaxdiagrams.html
  • lang_createvtab.html - fileformat2.html fts3.html keyword_index.html lang.html syntaxdiagrams.html vtab.html
  • lang_datefunc.html - about.html datatype3.html index.html keyword_index.html lang.html lang_corefunc.html lang_expr.html sitemap.html
  • lang_delete.html - c3ref/blob_open.html c3ref/set_authorizer.html c3ref/update_hook.html capi3ref.html compile.html foreignkeys.html fts3.html keyword_index.html lang.html lang_analyze.html lang_createtrigger.html lang_createview.html lang_droptable.html lang_indexedby.html pragma.html rtree.html syntaxdiagrams.html vtab.html
  • lang_detach.html - c3ref/stmt_readonly.html capi3ref.html compile.html different.html keyword_index.html lang.html syntaxdiagrams.html tempfiles.html
  • lang_dropindex.html - keyword_index.html lang.html lang_createindex.html lang_naming.html syntaxdiagrams.html
  • lang_droptable.html - capi3ref.html foreignkeys.html fts3.html keyword_index.html lang.html lang_analyze.html lang_createtable.html lang_createtrigger.html lang_createvtab.html lang_naming.html rtree.html syntaxdiagrams.html vtab.html
  • lang_droptrigger.html - compile.html keyword_index.html lang.html lang_createtrigger.html lang_naming.html syntaxdiagrams.html
  • lang_dropview.html - compile.html keyword_index.html lang.html lang_createview.html lang_naming.html syntaxdiagrams.html
  • lang_explain.html - compile.html different.html eqp.html keyword_index.html lang.html opcode.html optoverview.html syntaxdiagrams.html
  • lang_expr.html - c3ref/bind_blob.html c3ref/c_limit_attached.html c3ref/get_auxdata.html c3ref/prepare.html capi3ref.html cintro.html compile.html datatype3.html keyword_index.html lang.html lang_corefunc.html lang_createtable.html lang_delete.html lang_select.html lang_update.html limits.html optoverview.html pragma.html rtree.html syntaxdiagrams.html vfs.html vtab.html
  • lang_indexedby.html - keyword_index.html lang.html syntaxdiagrams.html
  • lang_insert.html - c3ref/last_insert_rowid.html capi3ref.html faq.html fts3.html keyword_index.html lang.html lang_analyze.html lang_createtable.html lang_createtrigger.html lang_createview.html lang_replace.html pragma.html rtree.html syntaxdiagrams.html vtab.html
  • lang_keywords.html - keyword_index.html lang.html
  • lang_naming.html - keyword_index.html lang_dropview.html
  • lang_reindex.html - compile.html keyword_index.html lang.html lang_naming.html syntaxdiagrams.html
  • lang_replace.html - capi3ref.html different.html keyword_index.html lang.html lang_insert.html
  • lang_savepoint.html - c3ref/stmt_readonly.html capi3ref.html foreignkeys.html keyword_index.html lang.html lang_transaction.html pragma.html syntaxdiagrams.html
  • lang_select.html - c3ref/c_limit_attached.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/set_authorizer.html c3ref/stmt_readonly.html capi3ref.html compile.html datatype3.html eqp.html fts3.html keyword_index.html lang.html lang_analyze.html lang_createtable.html lang_createview.html lang_expr.html lang_indexedby.html lang_transaction.html limits.html pragma.html syntaxdiagrams.html vtab.html
  • lang_transaction.html - asyncvfs.html c3ref/commit_hook.html c3ref/get_autocommit.html c3ref/step.html c3ref/stmt_readonly.html capi3ref.html faq.html foreignkeys.html keyword_index.html lang.html lang_attach.html lang_savepoint.html pragma.html syntaxdiagrams.html wal.html
  • lang_update.html - c3ref/blob_open.html c3ref/column_count.html capi3ref.html compile.html fts3.html keyword_index.html lang.html lang_analyze.html lang_createtable.html lang_createtrigger.html lang_createview.html lang_indexedby.html pragma.html rtree.html syntaxdiagrams.html vtab.html
  • lang_vacuum.html - compile.html faq.html formatchng.html fts3.html howtocorrupt.html keyword_index.html lang.html pragma.html syntaxdiagrams.html tempfiles.html wal.html
  • limits.html - c3ref/c_limit_attached.html c3ref/limit.html capi3ref.html compile.html datatype3.html doclist.html docs.html faq.html features.html foreignkeys.html keyword_index.html lang_createtable.html lang_expr.html pragma.html sitemap.html testing.html
  • lockingv3.html - atomiccommit.html c3ref/backup_finish.html capi3ref.html doclist.html docs.html faq.html keyword_index.html lang_transaction.html sharedcache.html shortnames.html sitemap.html version3.html wal.html
  • malloc.html - c3ref/c_dbconfig_enable_fkey.html c3ref/c_status_malloc_count.html c3ref/mem_methods.html capi3ref.html compile.html doclist.html docs.html keyword_index.html selfcontained.html sitemap.html testing.html
  • mingw.html -
  • mostdeployed.html - doclist.html index.html sitemap.html
  • nulls.html - doclist.html docs.html sitemap.html
  • objlist.html - c3ref/aggregate_context.html c3ref/aggregate_count.html c3ref/auto_extension.html c3ref/backup.html c3ref/backup_finish.html c3ref/bind_blob.html c3ref/bind_parameter_count.html c3ref/bind_parameter_index.html c3ref/bind_parameter_name.html c3ref/blob.html c3ref/blob_bytes.html c3ref/blob_close.html c3ref/blob_open.html c3ref/blob_read.html c3ref/blob_reopen.html c3ref/blob_write.html c3ref/busy_handler.html c3ref/busy_timeout.html c3ref/c_abort.html c3ref/c_access_exists.html c3ref/c_alter_table.html c3ref/c_any.html c3ref/c_blob.html c3ref/c_busy_recovery.html c3ref/c_checkpoint_full.html c3ref/c_config_getmalloc.html c3ref/c_dbconfig_enable_fkey.html c3ref/c_dbstatus_options.html c3ref/c_deny.html c3ref/c_fail.html c3ref/c_fcntl_chunk_size.html c3ref/c_index_constraint_eq.html c3ref/c_iocap_atomic.html c3ref/c_limit_attached.html c3ref/c_lock_exclusive.html c3ref/c_mutex_fast.html c3ref/c_open_autoproxy.html c3ref/c_shm_exclusive.html c3ref/c_shm_nlock.html c3ref/c_source_id.html c3ref/c_static.html c3ref/c_status_malloc_count.html c3ref/c_stmtstatus_counter.html c3ref/c_sync_dataonly.html c3ref/c_testctrl_always.html c3ref/c_vtab_constraint_support.html c3ref/clear_bindings.html c3ref/close.html c3ref/collation_needed.html c3ref/column_blob.html c3ref/column_count.html c3ref/column_database_name.html c3ref/column_decltype.html c3ref/column_name.html c3ref/commit_hook.html c3ref/compileoption_get.html c3ref/complete.html c3ref/config.html c3ref/constlist.html c3ref/context.html c3ref/context_db_handle.html c3ref/create_collation.html c3ref/create_function.html c3ref/create_module.html c3ref/data_count.html c3ref/db_config.html c3ref/db_handle.html c3ref/db_mutex.html c3ref/db_status.html c3ref/declare_vtab.html c3ref/enable_load_extension.html c3ref/enable_shared_cache.html c3ref/errcode.html c3ref/exec.html c3ref/extended_result_codes.html c3ref/file.html c3ref/file_control.html c3ref/finalize.html c3ref/free.html c3ref/free_table.html c3ref/funclist.html c3ref/get_autocommit.html c3ref/get_auxdata.html c3ref/index_info.html c3ref/initialize.html c3ref/int64.html c3ref/interrupt.html c3ref/intro.html c3ref/io_methods.html c3ref/last_insert_rowid.html c3ref/libversion.html c3ref/limit.html c3ref/load_extension.html c3ref/log.html c3ref/mem_methods.html c3ref/memory_highwater.html c3ref/module.html c3ref/mprintf.html c3ref/mutex.html c3ref/mutex_alloc.html c3ref/mutex_held.html c3ref/mutex_methods.html c3ref/next_stmt.html c3ref/open.html c3ref/overload_function.html c3ref/pcache.html c3ref/pcache_methods.html c3ref/prepare.html c3ref/profile.html c3ref/progress_handler.html c3ref/randomness.html c3ref/release_memory.html c3ref/reset.html c3ref/reset_auto_extension.html c3ref/result_blob.html c3ref/set_authorizer.html c3ref/sleep.html c3ref/soft_heap_limit.html c3ref/soft_heap_limit64.html c3ref/sql.html c3ref/sqlite3.html c3ref/status.html c3ref/step.html c3ref/stmt.html c3ref/stmt_readonly.html c3ref/stmt_status.html c3ref/strnicmp.html c3ref/table_column_metadata.html c3ref/temp_directory.html c3ref/test_control.html c3ref/threadsafe.html c3ref/unlock_notify.html c3ref/update_hook.html c3ref/uri_parameter.html c3ref/user_data.html c3ref/value.html c3ref/value_blob.html c3ref/vfs.html c3ref/vfs_find.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_checkpoint_v2.html c3ref/wal_hook.html session/constlist.html session/funclist.html session/intro.html
  • omitted.html - doclist.html docs.html features.html lang.html sitemap.html
  • onefile.html - doclist.html features.html sitemap.html
  • opcode.html - arch.html c3ref/progress_handler.html capi3ref.html different.html doclist.html docs.html keyword_index.html lang_explain.html sitemap.html vdbe.html
  • optoverview.html - compile.html doclist.html docs.html eqp.html fts3.html keyword_index.html lang_createtable.html pragma.html sitemap.html
  • php2004/page-001.html -
  • pragma.html - about.html atomiccommit.html c3ref/c_access_exists.html c3ref/c_fcntl_chunk_size.html c3ref/c_sync_dataonly.html c3ref/compileoption_get.html c3ref/data_count.html c3ref/limit.html c3ref/pcache_methods.html c3ref/set_authorizer.html c3ref/temp_directory.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_hook.html c_interface.html capi3ref.html compile.html doclist.html docs.html faq.html fileformat2.html foreignkeys.html formatchng.html howtocorrupt.html index.html inmemorydb.html keyword_index.html lang.html lang_altertable.html lang_attach.html lang_conflict.html lang_corefunc.html lang_createindex.html lang_createtrigger.html lang_delete.html lang_expr.html lang_transaction.html lang_vacuum.html limits.html lockingv3.html malloc.html optoverview.html sharedcache.html sitemap.html syntaxdiagrams.html tempfiles.html testing.html vdbe.html vtab.html wal.html
  • pressrelease-20071212.html -
  • privatebranch.html - doclist.html docs.html keyword_index.html sitemap.html
  • queryplanner.html - doclist.html eqp.html keyword_index.html sitemap.html
  • quickstart.html - about.html c3ref/intro.html capi3ref.html doclist.html docs.html index.html keyword_index.html sitemap.html
  • releasenotes310.html -
  • requirements.html -
  • rtree.html - amalgamation.html compile.html doclist.html docs.html keyword_index.html sitemap.html vtab.html
  • selfcontained.html - about.html doclist.html features.html index.html sitemap.html
  • serverless.html - about.html doclist.html index.html sitemap.html
  • session.html - doclist.html session/intro.html sitemap.html
  • session/constlist.html -
  • session/funclist.html - keyword_index.html
  • session/intro.html - keyword_index.html session.html
  • session/objlist.html -
  • sharedcache.html - c3ref/backup_finish.html c3ref/c_dbstatus_options.html c3ref/enable_shared_cache.html c3ref/open.html c3ref/unlock_notify.html capi3ref.html doclist.html docs.html keyword_index.html pragma.html sitemap.html uri.html vtab.html
  • shortnames.html - doclist.html howtocorrupt.html keyword_index.html sitemap.html
  • sitemap.html - doclist.html docs.html keyword_index.html
  • speed.html - doclist.html docs.html features.html sitemap.html
  • sqlite.html - c_interface.html compile.html doclist.html features.html howtocompile.html keyword_index.html quickstart.html sitemap.html wal.html
  • src/doc/trunk/doc/lemon.html - arch.html
  • support.html - about.html doclist.html keyword_index.html sitemap.html
  • syntaxdiagrams.html - doclist.html keyword_index.html lang.html lang_altertable.html lang_analyze.html lang_attach.html lang_comment.html lang_conflict.html lang_createindex.html lang_createtable.html lang_createtrigger.html lang_createview.html lang_createvtab.html lang_delete.html lang_detach.html lang_dropindex.html lang_droptable.html lang_droptrigger.html lang_dropview.html lang_explain.html lang_expr.html lang_indexedby.html lang_insert.html lang_reindex.html lang_savepoint.html lang_select.html lang_transaction.html lang_update.html lang_vacuum.html pragma.html sitemap.html
  • sysreq.html - requirements.html
  • tclconf2004/page-001.html -
  • tclsqlite.html - about.html doclist.html docs.html features.html index.html keyword_index.html lang_expr.html sitemap.html
  • tempfiles.html - compile.html doclist.html docs.html keyword_index.html shortnames.html sitemap.html
  • testing.html - about.html doclist.html docs.html faq.html features.html howtocorrupt.html keyword_index.html limits.html malloc.html sitemap.html support.html tclsqlite.html th3.html
  • th3.html - doclist.html keyword_index.html malloc.html sitemap.html support.html testing.html
  • threadsafe.html - c3ref/c_config_getmalloc.html c3ref/db_mutex.html c3ref/errcode.html c3ref/open.html c3ref/threadsafe.html capi3ref.html compile.html doclist.html keyword_index.html sitemap.html
  • transactional.html - about.html doclist.html features.html index.html sitemap.html
  • unlock_notify.html - c3ref/unlock_notify.html capi3ref.html compile.html doclist.html docs.html keyword_index.html sitemap.html
  • uri.html - c3ref/open.html capi3ref.html compile.html doclist.html keyword_index.html lang_attach.html shortnames.html sitemap.html vfs.html
  • vdbe.html - doclist.html docs.html opcode.html pragma.html sitemap.html
  • version3.html - doclist.html docs.html sitemap.html
  • vfs.html - atomiccommit.html c3ref/c_fcntl_chunk_size.html c3ref/open.html c3ref/vfs.html capi3ref.html compile.html doclist.html fileformat2.html keyword_index.html pragma.html selfcontained.html sitemap.html testing.html th3.html uri.html wal.html
  • vtab.html - c3ref/c_fail.html c3ref/c_index_constraint_eq.html c3ref/c_vtab_constraint_support.html c3ref/create_module.html c3ref/declare_vtab.html c3ref/index_info.html c3ref/last_insert_rowid.html c3ref/module.html c3ref/overload_function.html c3ref/stmt_readonly.html c3ref/vtab.html c3ref/vtab_config.html c3ref/vtab_cursor.html c3ref/vtab_on_conflict.html capi3ref.html doclist.html fileformat2.html fts3.html keyword_index.html lang_createvtab.html sitemap.html
  • wal.html - atomiccommit.html c3ref/c_fcntl_chunk_size.html c3ref/wal_autocheckpoint.html c3ref/wal_checkpoint.html c3ref/wal_hook.html capi3ref.html compile.html doclist.html fileformat2.html howtocorrupt.html keyword_index.html lang_attach.html lang_vacuum.html lockingv3.html pragma.html shortnames.html sitemap.html


Target Crossreference

Choose any three.
About Sitemap Documentation Download License News Support
  • 34to35.html - 34to35
  • 35to36.html - 35to36
  • amalgamation.html - amalgamation {the amalgamation}
  • asyncvfs.html - {asynchronous I/O backend} {asynchronous VFS}
  • atomiccommit.html - {Atomic Commit} {atomic commit}
  • atomiccommit.html#sect_9_0 - {Things That Can Go Wrong}
  • autoinc.html - AUTOINCREMENT
  • backup.html - {Using the SQLite Online Backup API} {backup API}
  • books.html - {books about SQLite}
  • btreemodule.html - {btree design}
  • c3ref/aggregate_context.html - sqlite3_aggregate_context
  • c3ref/aggregate_count.html - sqlite3_aggregate_count sqlite3_expired sqlite3_global_recover sqlite3_memory_alarm sqlite3_thread_cleanup sqlite3_transfer_bindings
  • c3ref/auto_extension.html - sqlite3_auto_extension
  • c3ref/backup.html - sqlite3_backup
  • c3ref/backup_finish.html - sqlite3_backup_remaining
  • c3ref/backup_finish.html#sqlite3backupfinish - sqlite3_backup_finish
  • c3ref/backup_finish.html#sqlite3backupinit - sqlite3_backup_init
  • c3ref/backup_finish.html#sqlite3backuppagecount - sqlite3_backup_pagecount
  • c3ref/backup_finish.html#sqlite3backupremaining - sqlite3_backup__remaining
  • c3ref/backup_finish.html#sqlite3backupstep - sqlite3_backup_step
  • c3ref/bind_blob.html - {SQL parameter} {SQL parameters} {host parameter} {host parameter name} {host parameters} {parameter binding} sqlite3_bind_blob sqlite3_bind_double sqlite3_bind_int sqlite3_bind_int64 sqlite3_bind_null sqlite3_bind_text sqlite3_bind_text16 sqlite3_bind_value sqlite3_bind_zeroblob
  • c3ref/bind_parameter_count.html - sqlite3_bind_parameter_count
  • c3ref/bind_parameter_index.html - sqlite3_bind_parameter_index
  • c3ref/bind_parameter_name.html - sqlite3_bind_parameter_name
  • c3ref/blob.html - {BLOB handle} {BLOB handles} sqlite3_blob
  • c3ref/blob_bytes.html - sqlite3_blob_bytes
  • c3ref/blob_close.html - sqlite3_blob_close
  • c3ref/blob_open.html - sqlite3_blob_open
  • c3ref/blob_read.html - sqlite3_blob_read
  • c3ref/blob_reopen.html - sqlite3_blob_reopen
  • c3ref/blob_write.html - sqlite3_blob_write
  • c3ref/busy_handler.html - sqlite3_busy_handler
  • c3ref/busy_timeout.html - sqlite3_busy_timeout
  • c3ref/c_abort.html - SQLITE_ABORT SQLITE_AUTH SQLITE_BUSY SQLITE_CANTOPEN SQLITE_CONSTRAINT SQLITE_CORRUPT SQLITE_DONE SQLITE_EMPTY SQLITE_ERROR SQLITE_FORMAT SQLITE_FULL SQLITE_INTERNAL SQLITE_INTERRUPT SQLITE_IOERR SQLITE_LOCKED SQLITE_MISMATCH SQLITE_MISUSE SQLITE_NOLFS SQLITE_NOMEM SQLITE_NOTADB SQLITE_NOTFOUND SQLITE_OK SQLITE_PERM SQLITE_PROTOCOL SQLITE_RANGE SQLITE_READONLY SQLITE_ROW SQLITE_SCHEMA SQLITE_TOOBIG {error code} {error codes} {result code} {result codes}
  • c3ref/c_access_exists.html - SQLITE_ACCESS_EXISTS SQLITE_ACCESS_READ SQLITE_ACCESS_READWRITE
  • c3ref/c_alter_table.html - SQLITE_ALTER_TABLE SQLITE_ANALYZE SQLITE_ATTACH SQLITE_COPY SQLITE_CREATE_INDEX SQLITE_CREATE_TABLE SQLITE_CREATE_TEMP_INDEX SQLITE_CREATE_TEMP_TABLE SQLITE_CREATE_TEMP_TRIGGER SQLITE_CREATE_TEMP_VIEW SQLITE_CREATE_TRIGGER SQLITE_CREATE_VIEW SQLITE_CREATE_VTABLE SQLITE_DELETE SQLITE_DETACH SQLITE_DROP_INDEX SQLITE_DROP_TABLE SQLITE_DROP_TEMP_INDEX SQLITE_DROP_TEMP_TABLE SQLITE_DROP_TEMP_TRIGGER SQLITE_DROP_TEMP_VIEW SQLITE_DROP_TRIGGER SQLITE_DROP_VIEW SQLITE_DROP_VTABLE SQLITE_FUNCTION SQLITE_INSERT SQLITE_PRAGMA SQLITE_READ SQLITE_REINDEX SQLITE_SAVEPOINT SQLITE_SELECT SQLITE_TRANSACTION SQLITE_UPDATE
  • c3ref/c_any.html - SQLITE_ANY SQLITE_UTF16 SQLITE_UTF16BE SQLITE_UTF16LE SQLITE_UTF16_ALIGNED SQLITE_UTF8
  • c3ref/c_blob.html - SQLITE_BLOB SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_TEXT
  • c3ref/c_busy_recovery.html - SQLITE_BUSY_RECOVERY SQLITE_CANTOPEN_NOTEMPDIR SQLITE_CORRUPT_VTAB SQLITE_IOERR_ACCESS SQLITE_IOERR_BLOCKED SQLITE_IOERR_CHECKRESERVEDLOCK SQLITE_IOERR_CLOSE SQLITE_IOERR_DELETE SQLITE_IOERR_DIR_CLOSE SQLITE_IOERR_DIR_FSYNC SQLITE_IOERR_FSTAT SQLITE_IOERR_FSYNC SQLITE_IOERR_LOCK SQLITE_IOERR_NOMEM SQLITE_IOERR_RDLOCK SQLITE_IOERR_READ SQLITE_IOERR_SEEK SQLITE_IOERR_SHMLOCK SQLITE_IOERR_SHMMAP SQLITE_IOERR_SHMOPEN SQLITE_IOERR_SHMSIZE SQLITE_IOERR_SHORT_READ SQLITE_IOERR_TRUNCATE SQLITE_IOERR_UNLOCK SQLITE_IOERR_WRITE SQLITE_LOCKED_SHAREDCACHE SQLITE_READONLY_CANTLOCK SQLITE_READONLY_RECOVERY {extended error code} {extended error codes} {extended result code} {extended result codes}
  • c3ref/c_checkpoint_full.html - SQLITE_CHECKPOINT_FULL SQLITE_CHECKPOINT_PASSIVE SQLITE_CHECKPOINT_RESTART
  • c3ref/c_config_getmalloc.html - {configuration option}
  • c3ref/c_config_getmalloc.html#sqliteconfiggetmalloc - SQLITE_CONFIG_GETMALLOC
  • c3ref/c_config_getmalloc.html#sqliteconfiggetmutex - SQLITE_CONFIG_GETMUTEX
  • c3ref/c_config_getmalloc.html#sqliteconfiggetpcache - SQLITE_CONFIG_GETPCACHE
  • c3ref/c_config_getmalloc.html#sqliteconfigheap - SQLITE_CONFIG_HEAP
  • c3ref/c_config_getmalloc.html#sqliteconfiglog - SQLITE_CONFIG_LOG
  • c3ref/c_config_getmalloc.html#sqliteconfiglookaside - SQLITE_CONFIG_LOOKASIDE
  • c3ref/c_config_getmalloc.html#sqliteconfigmalloc - SQLITE_CONFIG_MALLOC
  • c3ref/c_config_getmalloc.html#sqliteconfigmemstatus - SQLITE_CONFIG_MEMSTATUS
  • c3ref/c_config_getmalloc.html#sqliteconfigmultithread - SQLITE_CONFIG_MULTITHREAD
  • c3ref/c_config_getmalloc.html#sqliteconfigmutex - SQLITE_CONFIG_MUTEX
  • c3ref/c_config_getmalloc.html#sqliteconfigpagecache - SQLITE_CONFIG_PAGECACHE
  • c3ref/c_config_getmalloc.html#sqliteconfigpcache - SQLITE_CONFIG_PCACHE
  • c3ref/c_config_getmalloc.html#sqliteconfigscratch - SQLITE_CONFIG_SCRATCH
  • c3ref/c_config_getmalloc.html#sqliteconfigserialized - SQLITE_CONFIG_SERIALIZED
  • c3ref/c_config_getmalloc.html#sqliteconfigsinglethread - SQLITE_CONFIG_SINGLETHREAD
  • c3ref/c_config_getmalloc.html#sqliteconfiguri - SQLITE_CONFIG_URI
  • c3ref/c_dbconfig_enable_fkey.html - SQLITE_DBCONFIG_ENABLE_FKEY SQLITE_DBCONFIG_ENABLE_TRIGGER SQLITE_DBCONFIG_LOOKASIDE
  • c3ref/c_dbstatus_options.html - {SQLITE_DBSTATUS options} SQLITE_DBSTATUS_MAX
  • c3ref/c_dbstatus_options.html#sqlitedbstatuscachehit - SQLITE_DBSTATUS_CACHE_HIT
  • c3ref/c_dbstatus_options.html#sqlitedbstatuscachemiss - SQLITE_DBSTATUS_CACHE_MISS
  • c3ref/c_dbstatus_options.html#sqlitedbstatuscacheused - SQLITE_DBSTATUS_CACHE_USED
  • c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidehit - SQLITE_DBSTATUS_LOOKASIDE_HIT
  • c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidemissfull - SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
  • c3ref/c_dbstatus_options.html#sqlitedbstatuslookasidemisssize - SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
  • c3ref/c_dbstatus_options.html#sqlitedbstatuslookasideused - SQLITE_DBSTATUS_LOOKASIDE_USED
  • c3ref/c_dbstatus_options.html#sqlitedbstatusschemaused - SQLITE_DBSTATUS_SCHEMA_USED
  • c3ref/c_dbstatus_options.html#sqlitedbstatusstmtused - SQLITE_DBSTATUS_STMT_USED
  • c3ref/c_deny.html - SQLITE_DENY SQLITE_IGNORE
  • c3ref/c_fail.html - SQLITE_FAIL SQLITE_REPLACE SQLITE_ROLLBACK
  • c3ref/c_fcntl_chunk_size.html - SQLITE_FCNTL_CHUNK_SIZE SQLITE_FCNTL_FILE_POINTER SQLITE_FCNTL_LOCKSTATE SQLITE_FCNTL_OVERWRITE SQLITE_FCNTL_PERSIST_WAL SQLITE_FCNTL_SIZE_HINT SQLITE_FCNTL_SYNC_OMITTED SQLITE_FCNTL_WIN32_AV_RETRY SQLITE_GET_LOCKPROXYFILE SQLITE_LAST_ERRNO SQLITE_SET_LOCKPROXYFILE
  • c3ref/c_index_constraint_eq.html - SQLITE_INDEX_CONSTRAINT_EQ SQLITE_INDEX_CONSTRAINT_GE SQLITE_INDEX_CONSTRAINT_GT SQLITE_INDEX_CONSTRAINT_LE SQLITE_INDEX_CONSTRAINT_LT SQLITE_INDEX_CONSTRAINT_MATCH
  • c3ref/c_iocap_atomic.html - SQLITE_IOCAP_ATOMIC SQLITE_IOCAP_ATOMIC16K SQLITE_IOCAP_ATOMIC1K SQLITE_IOCAP_ATOMIC2K SQLITE_IOCAP_ATOMIC32K SQLITE_IOCAP_ATOMIC4K SQLITE_IOCAP_ATOMIC512 SQLITE_IOCAP_ATOMIC64K SQLITE_IOCAP_ATOMIC8K SQLITE_IOCAP_SAFE_APPEND SQLITE_IOCAP_SEQUENTIAL SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  • c3ref/c_limit_attached.html - {limit categories} {limit category}
  • c3ref/c_limit_attached.html#sqlitelimitattached - SQLITE_LIMIT_ATTACHED
  • c3ref/c_limit_attached.html#sqlitelimitcolumn - SQLITE_LIMIT_COLUMN
  • c3ref/c_limit_attached.html#sqlitelimitcompoundselect - SQLITE_LIMIT_COMPOUND_SELECT
  • c3ref/c_limit_attached.html#sqlitelimitexprdepth - SQLITE_LIMIT_EXPR_DEPTH
  • c3ref/c_limit_attached.html#sqlitelimitfunctionarg - SQLITE_LIMIT_FUNCTION_ARG
  • c3ref/c_limit_attached.html#sqlitelimitlength - SQLITE_LIMIT_LENGTH
  • c3ref/c_limit_attached.html#sqlitelimitlikepatternlength - SQLITE_LIMIT_LIKE_PATTERN_LENGTH
  • c3ref/c_limit_attached.html#sqlitelimitsqllength - SQLITE_LIMIT_SQL_LENGTH
  • c3ref/c_limit_attached.html#sqlitelimittriggerdepth - SQLITE_LIMIT_TRIGGER_DEPTH
  • c3ref/c_limit_attached.html#sqlitelimitvariablenumber - SQLITE_LIMIT_VARIABLE_NUMBER
  • c3ref/c_limit_attached.html#sqlitelimitvdbeop - SQLITE_LIMIT_VDBE_OP
  • c3ref/c_lock_exclusive.html - SQLITE_LOCK_EXCLUSIVE SQLITE_LOCK_NONE SQLITE_LOCK_PENDING SQLITE_LOCK_RESERVED SQLITE_LOCK_SHARED
  • c3ref/c_mutex_fast.html - SQLITE_MUTEX_FAST SQLITE_MUTEX_RECURSIVE SQLITE_MUTEX_STATIC_LRU SQLITE_MUTEX_STATIC_LRU2 SQLITE_MUTEX_STATIC_MASTER SQLITE_MUTEX_STATIC_MEM SQLITE_MUTEX_STATIC_MEM2 SQLITE_MUTEX_STATIC_OPEN SQLITE_MUTEX_STATIC_PMEM SQLITE_MUTEX_STATIC_PRNG
  • c3ref/c_open_autoproxy.html - SQLITE_OPEN_AUTOPROXY SQLITE_OPEN_CREATE SQLITE_OPEN_DELETEONCLOSE SQLITE_OPEN_EXCLUSIVE SQLITE_OPEN_FULLMUTEX SQLITE_OPEN_MAIN_DB SQLITE_OPEN_MAIN_JOURNAL SQLITE_OPEN_MASTER_JOURNAL SQLITE_OPEN_NOMUTEX SQLITE_OPEN_PRIVATECACHE SQLITE_OPEN_READONLY SQLITE_OPEN_READWRITE SQLITE_OPEN_SHAREDCACHE SQLITE_OPEN_SUBJOURNAL SQLITE_OPEN_TEMP_DB SQLITE_OPEN_TEMP_JOURNAL SQLITE_OPEN_TRANSIENT_DB SQLITE_OPEN_URI SQLITE_OPEN_WAL
  • c3ref/c_shm_exclusive.html - SQLITE_SHM_EXCLUSIVE SQLITE_SHM_LOCK SQLITE_SHM_SHARED SQLITE_SHM_UNLOCK
  • c3ref/c_shm_nlock.html - SQLITE_SHM_NLOCK
  • c3ref/c_source_id.html - SQLITE_SOURCE_ID SQLITE_VERSION SQLITE_VERSION_NUMBER
  • c3ref/c_static.html - SQLITE_STATIC SQLITE_TRANSIENT
  • c3ref/c_status_malloc_count.html - {status parameters}
  • c3ref/c_status_malloc_count.html#sqlitestatusmalloccount - SQLITE_STATUS_MALLOC_COUNT
  • c3ref/c_status_malloc_count.html#sqlitestatusmallocsize - SQLITE_STATUS_MALLOC_SIZE
  • c3ref/c_status_malloc_count.html#sqlitestatusmemoryused - SQLITE_STATUS_MEMORY_USED
  • c3ref/c_status_malloc_count.html#sqlitestatuspagecacheoverflow - SQLITE_STATUS_PAGECACHE_OVERFLOW
  • c3ref/c_status_malloc_count.html#sqlitestatuspagecachesize - SQLITE_STATUS_PAGECACHE_SIZE
  • c3ref/c_status_malloc_count.html#sqlitestatuspagecacheused - SQLITE_STATUS_PAGECACHE_USED
  • c3ref/c_status_malloc_count.html#sqlitestatusparserstack - SQLITE_STATUS_PARSER_STACK
  • c3ref/c_status_malloc_count.html#sqlitestatusscratchoverflow - SQLITE_STATUS_SCRATCH_OVERFLOW
  • c3ref/c_status_malloc_count.html#sqlitestatusscratchsize - SQLITE_STATUS_SCRATCH_SIZE
  • c3ref/c_status_malloc_count.html#sqlitestatusscratchused - SQLITE_STATUS_SCRATCH_USED
  • c3ref/c_stmtstatus_counter.html - {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
  • c3ref/c_stmtstatus_counter.html#sqlitestmtstatusautoindex - SQLITE_STMTSTATUS_AUTOINDEX
  • c3ref/c_stmtstatus_counter.html#sqlitestmtstatusfullscanstep - SQLITE_STMTSTATUS_FULLSCAN_STEP
  • c3ref/c_stmtstatus_counter.html#sqlitestmtstatussort - SQLITE_STMTSTATUS_SORT
  • c3ref/c_sync_dataonly.html - SQLITE_SYNC_DATAONLY SQLITE_SYNC_FULL SQLITE_SYNC_NORMAL
  • c3ref/c_testctrl_always.html - SQLITE_TESTCTRL_ALWAYS SQLITE_TESTCTRL_ASSERT SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS SQLITE_TESTCTRL_BITVEC_TEST SQLITE_TESTCTRL_FAULT_INSTALL SQLITE_TESTCTRL_FIRST SQLITE_TESTCTRL_ISKEYWORD SQLITE_TESTCTRL_LAST SQLITE_TESTCTRL_LOCALTIME_FAULT SQLITE_TESTCTRL_OPTIMIZATIONS SQLITE_TESTCTRL_PENDING_BYTE SQLITE_TESTCTRL_PGHDRSZ SQLITE_TESTCTRL_PRNG_RESET SQLITE_TESTCTRL_PRNG_RESTORE SQLITE_TESTCTRL_PRNG_SAVE SQLITE_TESTCTRL_RESERVE SQLITE_TESTCTRL_SCRATCHMALLOC
  • c3ref/c_vtab_constraint_support.html - SQLITE_VTAB_CONSTRAINT_SUPPORT
  • c3ref/changes.html - sqlite3_changes
  • c3ref/clear_bindings.html - sqlite3_clear_bindings
  • c3ref/close.html - sqlite3_close
  • c3ref/collation_needed.html - sqlite3_collation_needed sqlite3_collation_needed16
  • c3ref/column_blob.html - {column access functions} sqlite3_column_blob sqlite3_column_bytes sqlite3_column_bytes16 sqlite3_column_double sqlite3_column_int sqlite3_column_int64 sqlite3_column_text sqlite3_column_text16 sqlite3_column_type sqlite3_column_value
  • c3ref/column_count.html - sqlite3_column_count
  • c3ref/column_database_name.html - sqlite3_column_database_name sqlite3_column_database_name16 sqlite3_column_origin_name sqlite3_column_origin_name16 sqlite3_column_table_name sqlite3_column_table_name16
  • c3ref/column_decltype.html - sqlite3_column_decltype sqlite3_column_decltype16
  • c3ref/column_name.html - sqlite3_column_name sqlite3_column_name16
  • c3ref/commit_hook.html - sqlite3_commit_hook sqlite3_rollback_hook
  • c3ref/compileoption_get.html - sqlite3_compileoption_get sqlite3_compileoption_used
  • c3ref/complete.html - sqlite3_complete sqlite3_complete16
  • c3ref/config.html - sqlite3_config
  • c3ref/context.html - sqlite3_context
  • c3ref/context_db_handle.html - sqlite3_context_db_handle
  • c3ref/create_collation.html - sqlite3_create_collation sqlite3_create_collation16 sqlite3_create_collation_v2
  • c3ref/create_function.html - {application-defined SQL function} {application-defined SQL functions} {function creation routines} sqlite3_create_function sqlite3_create_function16 sqlite3_create_function_v2
  • c3ref/create_module.html - sqlite3_create_module sqlite3_create_module_v2
  • c3ref/data_count.html - sqlite3_data_count
  • c3ref/db_config.html - sqlite3_db_config
  • c3ref/db_handle.html - sqlite3_db_handle
  • c3ref/db_mutex.html - sqlite3_db_mutex
  • c3ref/db_status.html - sqlite3_db_status
  • c3ref/declare_vtab.html - sqlite3_declare_vtab
  • c3ref/enable_load_extension.html - sqlite3_enable_load_extension
  • c3ref/enable_shared_cache.html - {shared cache} sqlite3_enable_shared_cache
  • c3ref/errcode.html - sqlite3_errcode sqlite3_errmsg sqlite3_errmsg16 sqlite3_extended_errcode
  • c3ref/exec.html - sqlite3_exec
  • c3ref/experimental.html - deprecated experimental
  • c3ref/extended_result_codes.html - sqlite3_extended_result_codes
  • c3ref/file.html - sqlite3_file
  • c3ref/file_control.html - sqlite3_file_control
  • c3ref/finalize.html - sqlite3_finalize
  • c3ref/free.html - sqlite3_free sqlite3_malloc sqlite3_realloc
  • c3ref/free_table.html - sqlite3_free_table sqlite3_get_table
  • c3ref/funclist.html - {C-API function list} capi3ref_funclist
  • c3ref/get_autocommit.html - {autocommit mode} sqlite3_get_autocommit
  • c3ref/get_auxdata.html - sqlite3_get_auxdata sqlite3_set_auxdata
  • c3ref/index_info.html - sqlite3_index_info
  • c3ref/initialize.html - sqlite3_initialize sqlite3_os_end sqlite3_os_init sqlite3_shutdown
  • c3ref/int64.html - sqlite3_int64 sqlite3_uint64 sqlite_int64 sqlite_uint64
  • c3ref/interrupt.html - sqlite3_interrupt
  • c3ref/intro.html - {C-language Interface} capi3ref
  • c3ref/io_methods.html - sqlite3_io_methods
  • c3ref/last_insert_rowid.html - sqlite3_last_insert_rowid
  • c3ref/libversion.html - sqlite3_libversion sqlite3_libversion_number sqlite3_sourceid sqlite3_version
  • c3ref/limit.html - sqlite3_limit
  • c3ref/load_extension.html - sqlite3_load_extension
  • c3ref/log.html - sqlite3_log
  • c3ref/mem_methods.html - sqlite3_mem_methods
  • c3ref/memory_highwater.html - sqlite3_memory_highwater sqlite3_memory_used
  • c3ref/module.html - sqlite3_module {virtual table module}
  • c3ref/mprintf.html - sqlite3_mprintf sqlite3_snprintf sqlite3_vmprintf sqlite3_vsnprintf
  • c3ref/mutex.html - sqlite3_mutex
  • c3ref/mutex_alloc.html - sqlite3_mutex_alloc sqlite3_mutex_enter sqlite3_mutex_free sqlite3_mutex_leave sqlite3_mutex_try
  • c3ref/mutex_held.html - sqlite3_mutex_held sqlite3_mutex_notheld
  • c3ref/mutex_methods.html - sqlite3_mutex_methods
  • c3ref/next_stmt.html - sqlite3_next_stmt
  • c3ref/open.html - sqlite3_open sqlite3_open16 sqlite3_open_v2
  • c3ref/open.html#coreuriqueryparameters - {core URI query parameters}
  • c3ref/open.html#urifilenameexamples - {URI filename examples}
  • c3ref/open.html#urifilenamesinsqlite3open - {URI filenames in sqlite3_open}
  • c3ref/overload_function.html - sqlite3_overload_function
  • c3ref/pcache.html - sqlite3_pcache
  • c3ref/pcache_methods.html - {page cache} sqlite3_pcache_methods
  • c3ref/pcache_methods.html#thexcachesizepagecachemethod - {the xCachesize page cache method}
  • c3ref/pcache_methods.html#thexcreatepagecachemethods - {the xCreate page cache methods}
  • c3ref/pcache_methods.html#thexdestroypagecachemethod - {the xDestroy page cache method}
  • c3ref/pcache_methods.html#thexfetchpagecachemethods - {the xFetch page cache methods}
  • c3ref/pcache_methods.html#thexinitpagecachemethod - {the xInit page cache method}
  • c3ref/pcache_methods.html#thexpagecountpagecachemethods - {the xPagecount page cache methods}
  • c3ref/pcache_methods.html#thexrekeypagecachemethods - {the xRekey page cache methods}
  • c3ref/pcache_methods.html#thexshutdownpagecachemethod - {the xShutdown page cache method}
  • c3ref/pcache_methods.html#thexunpinpagecachemethod - {the xUnpin page cache method}
  • c3ref/prepare.html - {SQL statement compiler} sqlite3_prepare sqlite3_prepare16 sqlite3_prepare16_v2 sqlite3_prepare_v2
  • c3ref/profile.html - sqlite3_profile sqlite3_trace
  • c3ref/progress_handler.html - sqlite3_progress_handler
  • c3ref/randomness.html - sqlite3_randomness
  • c3ref/release_memory.html - sqlite3_release_memory
  • c3ref/reset.html - sqlite3_reset
  • c3ref/reset_auto_extension.html - sqlite3_reset_auto_extension
  • c3ref/result_blob.html - sqlite3_result_blob sqlite3_result_double sqlite3_result_error sqlite3_result_error16 sqlite3_result_error_code sqlite3_result_error_nomem sqlite3_result_error_toobig sqlite3_result_int sqlite3_result_int64 sqlite3_result_null sqlite3_result_text sqlite3_result_text16 sqlite3_result_text16be sqlite3_result_text16le sqlite3_result_value sqlite3_result_zeroblob
  • c3ref/set_authorizer.html - sqlite3_set_authorizer
  • c3ref/sleep.html - sqlite3_sleep
  • c3ref/soft_heap_limit.html - sqlite3_soft_heap_limit
  • c3ref/soft_heap_limit64.html - sqlite3_soft_heap_limit64
  • c3ref/sql.html - sqlite3_sql
  • c3ref/sqlite3.html - {database connection} {database connections} sqlite3
  • c3ref/status.html - sqlite3_status
  • c3ref/step.html - sqlite3_step
  • c3ref/stmt.html - {prepared statement} {prepared statements} sqlite3_stmt
  • c3ref/stmt_readonly.html - sqlite3_stmt_readonly
  • c3ref/stmt_status.html - sqlite3_stmt_status
  • c3ref/strnicmp.html - sqlite3_strnicmp
  • c3ref/table_column_metadata.html - sqlite3_table_column_metadata
  • c3ref/temp_directory.html - sqlite3_temp_directory
  • c3ref/test_control.html - sqlite3_test_control
  • c3ref/threadsafe.html - sqlite3_threadsafe
  • c3ref/total_changes.html - sqlite3_total_changes
  • c3ref/unlock_notify.html - sqlite3_unlock_notify
  • c3ref/update_hook.html - sqlite3_update_hook
  • c3ref/uri_parameter.html - sqlite3_uri_parameter
  • c3ref/user_data.html - sqlite3_user_data
  • c3ref/value.html - {protected sqlite3_value} sqlite3_value {unprotected sqlite3_value}
  • c3ref/value_blob.html - sqlite3_value_blob sqlite3_value_bytes sqlite3_value_bytes16 sqlite3_value_double sqlite3_value_int sqlite3_value_int64 sqlite3_value_numeric_type sqlite3_value_text sqlite3_value_text16 sqlite3_value_text16be sqlite3_value_text16le sqlite3_value_type
  • c3ref/vfs.html - sqlite3_vfs
  • c3ref/vfs.html#sqlite3vfsxaccess - sqlite3_vfs.xAccess
  • c3ref/vfs.html#sqlite3vfsxopen - sqlite3_vfs.xOpen
  • c3ref/vfs_find.html - sqlite3_vfs_find sqlite3_vfs_register sqlite3_vfs_unregister
  • c3ref/vtab.html - sqlite3_vtab
  • c3ref/vtab_config.html - sqlite3_vtab_config
  • c3ref/vtab_cursor.html - sqlite3_vtab_cursor {virtual table cursor}
  • c3ref/vtab_on_conflict.html - sqlite3_vtab_on_conflict
  • c3ref/wal_autocheckpoint.html - sqlite3_wal_autocheckpoint
  • c3ref/wal_checkpoint.html - sqlite3_wal_checkpoint
  • c3ref/wal_checkpoint_v2.html - sqlite3_wal_checkpoint_v2
  • c3ref/wal_hook.html - sqlite3_wal_hook
  • cintro.html - cintro
  • compile.html - {compile-time options}
  • compile.html#4_byte_aligned_malloc - SQLITE_4_BYTE_ALIGNED_MALLOC
  • compile.html#case_sensitive_like - SQLITE_CASE_SENSITIVE_LIKE
  • compile.html#debug - SQLITE_DEBUG
  • compile.html#default_autovacuum - SQLITE_DEFAULT_AUTOVACUUM
  • compile.html#default_cache_size - SQLITE_DEFAULT_CACHE_SIZE
  • compile.html#default_file_format - SQLITE_DEFAULT_FILE_FORMAT
  • compile.html#default_file_permissions - SQLITE_DEFAULT_FILE_PERMISSIONS
  • compile.html#default_foreign_keys - SQLITE_DEFAULT_FOREIGN_KEYS
  • compile.html#default_journal_size_limit - SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
  • compile.html#default_locking_mode - SQLITE_DEFAULT_LOCKING_MODE
  • compile.html#default_memstatus - SQLITE_DEFAULT_MEMSTATUS
  • compile.html#default_page_size - SQLITE_DEFAULT_PAGE_SIZE
  • compile.html#default_temp_cache_size - SQLITE_DEFAULT_TEMP_CACHE_SIZE
  • compile.html#default_wal_autocheckpoint - SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
  • compile.html#direct_overflow_read - SQLITE_DIRECT_OVERFLOW_READ
  • compile.html#disable_dirsync - SQLITE_DISABLE_DIRSYNC
  • compile.html#disable_lfs - SQLITE_DISABLE_LFS
  • compile.html#enable_8_3_names - SQLITE_ENABLE_8_3_NAMES
  • compile.html#enable_atomic_write - SQLITE_ENABLE_ATOMIC_WRITE
  • compile.html#enable_column_metadata - SQLITE_ENABLE_COLUMN_METADATA
  • compile.html#enable_fts3 - SQLITE_ENABLE_FTS3
  • compile.html#enable_fts3_parenthesis - SQLITE_ENABLE_FTS3_PARENTHESIS
  • compile.html#enable_fts4 - SQLITE_ENABLE_FTS4
  • compile.html#enable_icu - SQLITE_ENABLE_ICU
  • compile.html#enable_iotrace - SQLITE_ENABLE_IOTRACE
  • compile.html#enable_locking_style - SQLITE_ENABLE_LOCKING_STYLE
  • compile.html#enable_memory_management - SQLITE_ENABLE_MEMORY_MANAGEMENT
  • compile.html#enable_memsys3 - SQLITE_ENABLE_MEMSYS3
  • compile.html#enable_memsys5 - SQLITE_ENABLE_MEMSYS5
  • compile.html#enable_rtree - SQLITE_ENABLE_RTREE
  • compile.html#enable_stat2 - SQLITE_ENABLE_STAT2
  • compile.html#enable_stat3 - SQLITE_ENABLE_STAT3
  • compile.html#enable_unlock_notify - SQLITE_ENABLE_UNLOCK_NOTIFY
  • compile.html#enable_update_delete_limit - SQLITE_ENABLE_UPDATE_DELETE_LIMIT
  • compile.html#have_isnan - SQLITE_HAVE_ISNAN
  • compile.html#max_schema_retry - SQLITE_MAX_SCHEMA_RETRY
  • compile.html#memdebug - SQLITE_MEMDEBUG
  • compile.html#omit_altertable - SQLITE_OMIT_ALTERTABLE
  • compile.html#omit_analyze - SQLITE_OMIT_ANALYZE
  • compile.html#omit_attach - SQLITE_OMIT_ATTACH
  • compile.html#omit_authorization - SQLITE_OMIT_AUTHORIZATION
  • compile.html#omit_autoincrement - SQLITE_OMIT_AUTOINCREMENT
  • compile.html#omit_autoinit - SQLITE_OMIT_AUTOINIT
  • compile.html#omit_automatic_index - SQLITE_OMIT_AUTOMATIC_INDEX
  • compile.html#omit_autoreset - SQLITE_OMIT_AUTORESET
  • compile.html#omit_autovacuum - SQLITE_OMIT_AUTOVACUUM
  • compile.html#omit_between_optimization - SQLITE_OMIT_BETWEEN_OPTIMIZATION
  • compile.html#omit_blob_literal - SQLITE_OMIT_BLOB_LITERAL
  • compile.html#omit_btreecount - SQLITE_OMIT_BTREECOUNT
  • compile.html#omit_builtin_test - SQLITE_OMIT_BUILTIN_TEST
  • compile.html#omit_cast - SQLITE_OMIT_CAST
  • compile.html#omit_check - SQLITE_OMIT_CHECK
  • compile.html#omit_compileoption_diags - SQLITE_OMIT_COMPILEOPTION_DIAGS
  • compile.html#omit_complete - SQLITE_OMIT_COMPLETE
  • compile.html#omit_compound_select - SQLITE_OMIT_COMPOUND_SELECT
  • compile.html#omit_datetime_funcs - SQLITE_OMIT_DATETIME_FUNCS
  • compile.html#omit_decltype - SQLITE_OMIT_DECLTYPE
  • compile.html#omit_deprecated - SQLITE_OMIT_DEPRECATED
  • compile.html#omit_diskio - SQLITE_OMIT_DISKIO
  • compile.html#omit_explain - SQLITE_OMIT_EXPLAIN
  • compile.html#omit_flag_pragmas - SQLITE_OMIT_FLAG_PRAGMAS
  • compile.html#omit_floating_point - SQLITE_OMIT_FLOATING_POINT
  • compile.html#omit_foreign_key - SQLITE_OMIT_FOREIGN_KEY
  • compile.html#omit_get_table - SQLITE_OMIT_GET_TABLE
  • compile.html#omit_incrblob - SQLITE_OMIT_INCRBLOB
  • compile.html#omit_integrity_check - SQLITE_OMIT_INTEGRITY_CHECK
  • compile.html#omit_like_optimization - SQLITE_OMIT_LIKE_OPTIMIZATION
  • compile.html#omit_load_extension - SQLITE_OMIT_LOAD_EXTENSION
  • compile.html#omit_localtime - SQLITE_OMIT_LOCALTIME
  • compile.html#omit_lookaside - SQLITE_OMIT_LOOKASIDE
  • compile.html#omit_memorydb - SQLITE_OMIT_MEMORYDB
  • compile.html#omit_merge_sort - SQLITE_OMIT_MERGE_SORT
  • compile.html#omit_or_optimization - SQLITE_OMIT_OR_OPTIMIZATION
  • compile.html#omit_pager_pragmas - SQLITE_OMIT_PAGER_PRAGMAS
  • compile.html#omit_pragma - SQLITE_OMIT_PRAGMA
  • compile.html#omit_progress_callback - SQLITE_OMIT_PROGRESS_CALLBACK
  • compile.html#omit_quickbalance - SQLITE_OMIT_QUICKBALANCE
  • compile.html#omit_reindex - SQLITE_OMIT_REINDEX
  • compile.html#omit_schema_pragmas - SQLITE_OMIT_SCHEMA_PRAGMAS
  • compile.html#omit_schema_version_pragmas - SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
  • compile.html#omit_shared_cache - SQLITE_OMIT_SHARED_CACHE
  • compile.html#omit_subquery - SQLITE_OMIT_SUBQUERY
  • compile.html#omit_tcl_variable - SQLITE_OMIT_TCL_VARIABLE
  • compile.html#omit_tempdb - SQLITE_OMIT_TEMPDB
  • compile.html#omit_trace - SQLITE_OMIT_TRACE
  • compile.html#omit_trigger - SQLITE_OMIT_TRIGGER
  • compile.html#omit_truncate_optimization - SQLITE_OMIT_TRUNCATE_OPTIMIZATION
  • compile.html#omit_utf16 - SQLITE_OMIT_UTF16
  • compile.html#omit_vacuum - SQLITE_OMIT_VACUUM
  • compile.html#omit_view - SQLITE_OMIT_VIEW
  • compile.html#omit_virtualtable - SQLITE_OMIT_VIRTUALTABLE
  • compile.html#omit_wal - SQLITE_OMIT_WAL
  • compile.html#omit_wsd - SQLITE_OMIT_WSD
  • compile.html#omit_xfer_opt - SQLITE_OMIT_XFER_OPT
  • compile.html#omitfeatures - omitfeatures
  • compile.html#os_other - SQLITE_OS_OTHER
  • compile.html#secure_delete - SQLITE_SECURE_DELETE
  • compile.html#soundex - SQLITE_SOUNDEX
  • compile.html#temp_store - SQLITE_TEMP_STORE
  • compile.html#threadsafe - SQLITE_THREADSAFE
  • compile.html#use_uri - SQLITE_USE_URI
  • compile.html#yystackdepth - YYSTACKDEPTH
  • compile.html#yytrackmaxstackdepth - YYTRACKMAXSTACKDEPTH
  • compile.html#zero_malloc - SQLITE_ZERO_MALLOC
  • consortium.html - {SQLite Consortium}
  • custombuild.html - {custom builds} {porting SQLite}
  • datatype3.html - datatype {dynamic typing}
  • datatype3.html#affinity - affinities affinity {column affinity} {type affinity}
  • datatype3.html#affname - {rules for determining column affinity}
  • datatype3.html#boolean - {boolean datatype}
  • datatype3.html#collation - BINARY {BINARY collating function} NOCASE {NOCASE collating function} RTRIM {RTRIM collating function} {collating function} {collating sequence} collation
  • datatype3.html#compaff - {comparison affinity rules}
  • datatype3.html#comparisons - {comparison expressions}
  • datatype3.html#datetime - {date and time datatype}
  • datatype3.html#expraff - {expression affinity}
  • datatype3.html#storageclasses - {storage class}
  • doclist.html - {alphabetical listing of SQLite documents} doclist
  • docs.html - {categorical listing of SQLite documents}
  • download.html - {TEA tarball} {amalgamation tarball} {download page}
  • download.html#encoding - {build product names}
  • eqp.html - {EXPLAIN QUERY PLAN} {explain query plan}
  • fileformat2.html - {file format} {second edition file format document}
  • fileformat2.html#cell_payload - {cell payload}
  • fileformat2.html#cellformat - {cell format summary}
  • fileformat2.html#chngctr - {change counter}
  • fileformat2.html#database_header - {database header}
  • fileformat2.html#filesize - {in-header database size}
  • fileformat2.html#freelist - {free-page list} freelist
  • fileformat2.html#ovflpgs - {overflow page} {overflow pages}
  • fileformat2.html#record_format - {record format}
  • fileformat2.html#rollbackjournal - {rollback journal format}
  • fileformat2.html#serialtype - {serial type} {serial types}
  • fileformat2.html#usable_size - {usable size}
  • fileformat2.html#validfor - {version-valid-for number}
  • fileformat2.html#varint - {variable-length integer} varint
  • fileformat2.html#walcksm - {WAL checksum algorithm}
  • fileformat2.html#walformat - {WAL format}
  • fileformat2.html#walindexformat - {WAL-index format} wal-index
  • fileformat2.html#walread - {WAL read algorithm}
  • fileio.html - {file I/O}
  • footprint.html - footprint {library size}
  • footprint.html#relfootprint - relfootprint
  • foreignkeys.html - {FOREIGN KEY constraints} {foreign key constraint} {foreign key constraints}
  • foreignkeys.html#fk_actions - {foreign key actions}
  • foreignkeys.html#fk_enable - {foreign key constraints are enabled}
  • foreignkeys.html#parentchild - {child key} {child table} {parent key} {parent table}
  • fts3.html - FTS3 fts3 {full-text search}
  • fts3.html#*fts4compression - {compressed FTS4 content}
  • fts3.html#*matchinfo_fts3 - matchinfo_fts3
  • fts3.html#*shadowtab - {FTS shadow tables}
  • fts3.html#appendix_a - {search application tips}
  • fts3.html#fts4 - FTS4
  • fts3.html#fts4_options - {FTS4 options}
  • fts3.html#fts4aux - fts4aux
  • fts3.html#fts4order - {FTS4 order option}
  • fts3.html#fts4prefix - {FTS4 prefix option}
  • fts3.html#hiddencol - {FTS hidden column}
  • fts3.html#matchinfo - matchinfo
  • fts3.html#offsets - offsets
  • fts3.html#section_1_4 - {simple fts queries}
  • fts3.html#section_2 - {compile fts}
  • fts3.html#section_3 - {FTS MATCH}
  • fts3.html#section_3_1 - {enhanced query syntax}
  • fts3.html#section_6_1 - {fts4 compress option}
  • fts3.html#section_6_2 - {fts4 prefix option}
  • fts3.html#section_8 - {segment btree}
  • fts3.html#snippet - {FTS auxiliary functions} snippet
  • fts3.html#termprefix - {prefix queries} {prefix query}
  • fts3.html#tokenizer - tokenizer
  • howtocompile.html - {how to compile}
  • howtocompile.html#amal - {building the amalgamation}
  • howtocompile.html#cli - {compiling the CLI}
  • howtocompile.html#tcl - {compiling the TCL interface}
  • howtocorrupt.html - {how to corrupt}
  • howtocorrupt.html#delhotjrnl - {deleting a hot journal}
  • inmemorydb.html - {in-memory database} {in-memory databases} memory
  • inmemorydb.html#temp_db - {temporary databases} {temporary tables}
  • keyword_index.html - {keyword index}
  • lang_aggfunc.html - {Aggregate Functions} aggfunc
  • lang_aggfunc.html#avg - avg {avg aggregate function}
  • lang_aggfunc.html#count - count {count aggregate function}
  • lang_aggfunc.html#groupconcat - group_concat {group_concat aggregate function}
  • lang_aggfunc.html#maxggunc - agg_max {max aggregate function} maxAggFunc
  • lang_aggfunc.html#minggunc - agg_min {min aggregate function} minAggFunc
  • lang_aggfunc.html#sumunc - sum {sum aggregate function} sumFunc total {total aggregate function}
  • lang_altertable.html - ALTER {ALTER TABLE}
  • lang_analyze.html - ANALYZE
  • lang_attach.html - ATTACH {ATTACH DATABASE}
  • lang_comment.html - comment comments
  • lang_conflict.html - {ON CONFLICT} {ON CONFLICT clause} {conflict clause}
  • lang_corefunc.html - {Core Functions} corefunc
  • lang_corefunc.html#abs - abs {abs SQL function}
  • lang_corefunc.html#changes - changes {changes SQL function}
  • lang_corefunc.html#coalesce - coalesce {coalesce SQL function}
  • lang_corefunc.html#glob - glob {glob SQL function}
  • lang_corefunc.html#hex - hex {hex SQL function}
  • lang_corefunc.html#ifnull - ifnull {ifnull SQL function}
  • lang_corefunc.html#last_insert_rowid - last_insert_rowid {last_insert_rowid SQL function}
  • lang_corefunc.html#length - length {length SQL function}
  • lang_corefunc.html#like - like {like SQL function}
  • lang_corefunc.html#load_extension - load_extension {load_extension SQL function}
  • lang_corefunc.html#lower - lower {lower SQL function}
  • lang_corefunc.html#ltrim - ltrim {ltrim SQL function}
  • lang_corefunc.html#maxoreunc - max {max SQL function} maxCoreFunc
  • lang_corefunc.html#minoreunc - min {min SQL function} minCoreFunc
  • lang_corefunc.html#nullif - nullif {nullif SQL function}
  • lang_corefunc.html#quote - quote {quote SQL function}
  • lang_corefunc.html#random - random {random SQL function}
  • lang_corefunc.html#randomblob - randomblob {randomblob SQL function}
  • lang_corefunc.html#replace - replace {replace SQL function}
  • lang_corefunc.html#round - round {round SQL function}
  • lang_corefunc.html#rtrim - rtrim {rtrim SQL function}
  • lang_corefunc.html#soundex - soundex {soundex SQL function}
  • lang_corefunc.html#sqlite_compileoption_get - sqlite_compileoption_get {sqlite_compileoption_get SQL function}
  • lang_corefunc.html#sqlite_compileoption_used - sqlite_compileoption_used {sqlite_compileoption_used SQL function}
  • lang_corefunc.html#sqlite_source_id - sqlite_source_id {sqlite_source_id SQL function}
  • lang_corefunc.html#sqlite_version - sqlite_version {sqlite_version SQL function}
  • lang_corefunc.html#substr - substr {substr SQL function}
  • lang_corefunc.html#total_changes - total_changes {total_changes SQL function}
  • lang_corefunc.html#trim - trim {trim SQL function}
  • lang_corefunc.html#typeof - typeof {typeof SQL function}
  • lang_corefunc.html#upper - upper {upper SQL function}
  • lang_corefunc.html#zeroblob - zeroblob {zeroblob SQL function}
  • lang_createindex.html - {CREATE INDEX}
  • lang_createtable.html - {CREATE TABLE}
  • lang_createtable.html#ckconst - CHECK {CHECK constraint} {CHECK constraints}
  • lang_createtable.html#constraints - constraints
  • lang_createtable.html#rowid - {INTEGER PRIMARY KEY} ROWID rowid
  • lang_createtable.html#tablecoldef - {column definition} {column definitions}
  • lang_createtrigger.html - {CREATE TRIGGER}
  • lang_createtrigger.html#instead_of_trigger - {INSTEAD OF} {INSTEAD OF trigger}
  • lang_createtrigger.html#undef_before - {undefined BEFORE trigger behavior}
  • lang_createview.html - {CREATE VIEW} view views
  • lang_createvtab.html - {CREATE VIRTUAL TABLE}
  • lang_datefunc.html - {Date And Time Functions} {date SQL function} datefunc {datetime SQL function} {julianday SQL function} {strftime SQL function} {time SQL function}
  • lang_delete.html - DELETE DELETEs
  • lang_delete.html#truncateopt - {truncate optimization}
  • lang_detach.html - DETACH {DETACH DATABASE}
  • lang_dropindex.html - {DROP INDEX}
  • lang_droptable.html - {DROP TABLE}
  • lang_droptrigger.html - {DROP TRIGGER}
  • lang_dropview.html - {DROP VIEW}
  • lang_explain.html - EXPLAIN
  • lang_expr.html - expression {expression syntax}
  • lang_expr.html#between - BETWEEN
  • lang_expr.html#binaryops - {binary operators}
  • lang_expr.html#booleanexpr - {boolean expression}
  • lang_expr.html#case - {CASE expression}
  • lang_expr.html#castexpr - {CAST expression}
  • lang_expr.html#collateop - {COLLATE operator}
  • lang_expr.html#glob - GLOB
  • lang_expr.html#in_op - {EXISTS operator} {IN operator} {NOT EXISTS operator} {NOT IN operator}
  • lang_expr.html#isisnot - {IS NOT operator} {IS operator}
  • lang_expr.html#like - ESCAPE LIKE
  • lang_expr.html#litvalue - {literal value}
  • lang_expr.html#match - MATCH
  • lang_expr.html#regexp - REGEXP
  • lang_expr.html#varparam - {bound parameter} {bound parameters} parameter parameters
  • lang_indexedby.html - {INDEXED BY} {NOT INDEXED}
  • lang_insert.html - INSERT INSERTs
  • lang_keywords.html - {SQL keyword} {SQL keywords} {SQLite Keywords}
  • lang_naming.html - {Database Object Name Resolution} {object resolution}
  • lang_reindex.html - REINDEX
  • lang_replace.html - REPLACE
  • lang_savepoint.html - RELEASE SAVEPOINT
  • lang_select.html - SELECT query
  • lang_select.html#compound - {compound query} {compound select}
  • lang_select.html#distinct - DISTINCT
  • lang_select.html#fromclause - {FROM clause}
  • lang_select.html#orderby - {order by}
  • lang_select.html#resultset - {GROUP BY} {result-set expressions}
  • lang_select.html#whereclause - {WHERE clause}
  • lang_transaction.html - BEGIN {BEGIN TRANSACTION} COMMIT ROLLBACK
  • lang_update.html - UPDATE UPDATEs
  • lang_vacuum.html - VACUUM
  • limits.html - limits
  • limits.html#max_attached - SQLITE_MAX_ATTACHED
  • limits.html#max_column - SQLITE_MAX_COLUMN
  • limits.html#max_compound_select - SQLITE_MAX_COMPOUND_SELECT
  • limits.html#max_expr_depth - SQLITE_MAX_EXPR_DEPTH
  • limits.html#max_function_arg - SQLITE_MAX_FUNCTION_ARG
  • limits.html#max_length - SQLITE_MAX_LENGTH
  • limits.html#max_like_pattern_length - SQLITE_MAX_LIKE_PATTERN_LENGTH
  • limits.html#max_page_count - SQLITE_MAX_PAGE_COUNT
  • limits.html#max_sql_length - SQLITE_MAX_SQL_LENGTH
  • limits.html#max_trigger_depth - SQLITE_MAX_TRIGGER_DEPTH
  • limits.html#max_variable_number - SQLITE_MAX_VARIABLE_NUMBER
  • lockingv3.html - {file locking and concurrency control}
  • lockingv3.html#excl_lock - EXCLUSIVE {EXCLUSIVE lock} {exclusive lock}
  • lockingv3.html#ext3-barrier-problem - {the ext3 barrier problem}
  • lockingv3.html#hotjrnl - {hot journal}
  • lockingv3.html#how_to_corrupt - {How To Corrupt Your Database Files}
  • lockingv3.html#locking - {file locking states}
  • lockingv3.html#pending_lock - PENDING {PENDING lock} {pending lock}
  • lockingv3.html#reserved_lock - RESERVED {RESERVED lock} {reserved lock}
  • lockingv3.html#rollback - {rollback journal}
  • lockingv3.html#shared_lock - SHARED {SHARED lock} {shared lock}
  • lockingv3.html#writer_starvation - {writer starvation}
  • malloc.html - {memory allocation}
  • malloc.html#altalloc - {built-in memory allocators}
  • malloc.html#defaultalloc - {default memory allocator}
  • malloc.html#lookaside - {lookaside memory allocator}
  • malloc.html#memdebug - {debugging memory allocator} memsys2
  • malloc.html#memstatus - {memory statistics}
  • malloc.html#memsys5 - memsys5 {zero-malloc memory allocator}
  • malloc.html#memsysx - {experimental memory allocators}
  • malloc.html#nofrag - {Robson proof}
  • malloc.html#pagecache - {pagecache memory allocator}
  • malloc.html#scratch - {scratch memory allocator}
  • opcode.html - {virtual machine instructions}
  • optoverview.html - optimizer {query planner}
  • optoverview.html#autoindex - {Automatic indexing} {automatic indexing}
  • optoverview.html#flattening - {flattening optimization}
  • optoverview.html#like_opt - {LIKE optimization}
  • optoverview.html#or_opt - {or optimization}
  • optoverview.html#rangequery - {range query optimization}
  • optoverview.html#table_order - {join order}
  • pragma.html#pragma_auto_vacuum - {PRAGMA auto_vacuum} auto_vacuum {auto_vacuum pragma}
  • pragma.html#pragma_automatic_index - {PRAGMA automatic_index} automatic_index {automatic_index pragma}
  • pragma.html#pragma_cache_size - {PRAGMA cache_size} cache_size {cache_size pragma}
  • pragma.html#pragma_case_sensitive_like - {PRAGMA case_sensitive_like} case_sensitive_like {case_sensitive_like pragma}
  • pragma.html#pragma_checkpoint_fullfsync - {PRAGMA checkpoint_fullfsync} checkpoint_fullfsync {checkpoint_fullfsync pragma}
  • pragma.html#pragma_collation_list - {PRAGMA collation_list} collation_list {collation_list pragma}
  • pragma.html#pragma_compile_options - {PRAGMA compile_options} compile_options {compile_options pragma}
  • pragma.html#pragma_count_changes - {PRAGMA count_changes} count_changes {count_changes pragma}
  • pragma.html#pragma_database_list - {PRAGMA database_list} database_list {database_list pragma}
  • pragma.html#pragma_default_cache_size - {PRAGMA default_cache_size} default_cache_size {default_cache_size pragma}
  • pragma.html#pragma_empty_result_callbacks - {PRAGMA empty_result_callbacks} empty_result_callbacks {empty_result_callbacks pragma}
  • pragma.html#pragma_encoding - {PRAGMA encoding} encoding {encoding pragma}
  • pragma.html#pragma_foreign_key_list - {PRAGMA foreign_key_list} foreign_key_list {foreign_key_list pragma}
  • pragma.html#pragma_foreign_keys - {PRAGMA foreign_keys} foreign_keys {foreign_keys pragma}
  • pragma.html#pragma_freelist_count - {PRAGMA freelist_count} freelist_count {freelist_count pragma}
  • pragma.html#pragma_full_column_names - {PRAGMA full_column_names} full_column_names {full_column_names pragma}
  • pragma.html#pragma_fullfsync - {PRAGMA fullfsync} fullfsync {fullfsync pragma}
  • pragma.html#pragma_ignore_check_constraints - {PRAGMA ignore_check_constraints} ignore_check_constraints {ignore_check_constraints pragma}
  • pragma.html#pragma_incremental_vacuum - {PRAGMA incremental_vacuum} incremental_vacuum {incremental_vacuum pragma}
  • pragma.html#pragma_index_info - {PRAGMA index_info} index_info {index_info pragma}
  • pragma.html#pragma_index_list - {PRAGMA index_list} index_list {index_list pragma}
  • pragma.html#pragma_integrity_check - {PRAGMA integrity_check} integrity_check {integrity_check pragma}
  • pragma.html#pragma_journal_mode - {PRAGMA journal_mode} journal_mode {journal_mode pragma}
  • pragma.html#pragma_journal_size_limit - {PRAGMA journal_size_limit} journal_size_limit {journal_size_limit pragma}
  • pragma.html#pragma_legacy_file_format - {PRAGMA legacy_file_format} legacy_file_format {legacy_file_format pragma}
  • pragma.html#pragma_locking_mode - {PRAGMA locking_mode} locking_mode {locking_mode pragma}
  • pragma.html#pragma_max_page_count - {PRAGMA max_page_count} max_page_count {max_page_count pragma}
  • pragma.html#pragma_page_count - {PRAGMA page_count} page_count {page_count pragma}
  • pragma.html#pragma_page_size - {PRAGMA page_size} page_size {page_size pragma}
  • pragma.html#pragma_parser_trace - {PRAGMA parser_trace} parser_trace {parser_trace pragma}
  • pragma.html#pragma_quick_check - {PRAGMA quick_check} quick_check {quick_check pragma}
  • pragma.html#pragma_read_uncommitted - {PRAGMA read_uncommitted} read_uncommitted {read_uncommitted pragma}
  • pragma.html#pragma_recursive_triggers - {PRAGMA recursive_triggers} recursive_triggers {recursive_triggers pragma}
  • pragma.html#pragma_reverse_unordered_selects - {PRAGMA reverse_unordered_selects} reverse_unordered_selects {reverse_unordered_selects pragma}
  • pragma.html#pragma_schema_version - {PRAGMA schema_version} {PRAGMA user_version} schema_version {schema_version pragma} user_version {user_version pragma}
  • pragma.html#pragma_secure_delete - {PRAGMA secure_delete} secure_delete {secure_delete pragma}
  • pragma.html#pragma_short_column_names - {PRAGMA short_column_names} short_column_names {short_column_names pragma}
  • pragma.html#pragma_synchronous - {PRAGMA synchronous} synchronous {synchronous pragma}
  • pragma.html#pragma_table_info - {PRAGMA table_info} table_info {table_info pragma}
  • pragma.html#pragma_temp_store - {PRAGMA temp_store} temp_store {temp_store pragma}
  • pragma.html#pragma_temp_store_directory - {PRAGMA temp_store_directory} temp_store_directory {temp_store_directory pragma}
  • pragma.html#pragma_vdbe_listing - {PRAGMA vdbe_listing} vdbe_listing {vdbe_listing pragma}
  • pragma.html#pragma_vdbe_trace - {PRAGMA vdbe_trace} vdbe_trace {vdbe_trace pragma}
  • pragma.html#pragma_wal_autocheckpoint - {PRAGMA wal_autocheckpoint} wal_autocheckpoint {wal_autocheckpoint pragma}
  • pragma.html#pragma_wal_checkpoint - {PRAGMA wal_checkpoint} wal_checkpoint {wal_checkpoint pragma}
  • pragma.html#pragma_writable_schema - {PRAGMA writable_schema} writable_schema {writable_schema pragma}
  • pragma.html#syntax - PRAGMA
  • pragma.html#toc - {pragma list}
  • privatebranch.html - {private branches}
  • queryplanner.html - indexing {indexing tutorial}
  • queryplanner.html#covidx - {covering index} {covering indices}
  • queryplanner.html#or_in_where - or-connected-terms
  • queryplanner.html#searching - strategies
  • queryplanner.html#sorting - sorting
  • quickstart.html - {Quick Start Guide} quickstart
  • releaselog/3_0_0.html - {Version 3.0.0} {version 3.0.0}
  • releaselog/3_0_1.html - {Version 3.0.1} {version 3.0.1}
  • releaselog/3_0_2.html - {Version 3.0.2} {version 3.0.2}
  • releaselog/3_0_3.html - {Version 3.0.3} {version 3.0.3}
  • releaselog/3_0_4.html - {Version 3.0.4} {version 3.0.4}
  • releaselog/3_0_5.html - {Version 3.0.5} {version 3.0.5}
  • releaselog/3_0_6.html - {Version 3.0.6} {version 3.0.6}
  • releaselog/3_0_7.html - {Version 3.0.7} {version 3.0.7}
  • releaselog/3_0_8.html - {Version 3.0.8} {version 3.0.8}
  • releaselog/3_1_0.html - {Version 3.1.0} {version 3.1.0}
  • releaselog/3_1_1.html - {Version 3.1.1} {version 3.1.1}
  • releaselog/3_1_2.html - {Version 3.1.2} {version 3.1.2}
  • releaselog/3_1_3.html - {Version 3.1.3} {version 3.1.3}
  • releaselog/3_1_4.html - {Version 3.1.4} {version 3.1.4}
  • releaselog/3_1_5.html - {Version 3.1.5} {version 3.1.5}
  • releaselog/3_1_6.html - {Version 3.1.6} {version 3.1.6}
  • releaselog/3_2_0.html - {Version 3.2.0} {version 3.2.0}
  • releaselog/3_2_1.html - {Version 3.2.1} {version 3.2.1}
  • releaselog/3_2_2.html - {Version 3.2.2} {version 3.2.2}
  • releaselog/3_2_3.html - {Version 3.2.3} {version 3.2.3}
  • releaselog/3_2_4.html - {Version 3.2.4} {version 3.2.4}
  • releaselog/3_2_5.html - {Version 3.2.5} {version 3.2.5}
  • releaselog/3_2_6.html - {Version 3.2.6} {version 3.2.6}
  • releaselog/3_2_7.html - {Version 3.2.7} {version 3.2.7}
  • releaselog/3_2_8.html - {Version 3.2.8} {version 3.2.8}
  • releaselog/3_3_0.html - {Version 3.3.0} {version 3.3.0}
  • releaselog/3_3_1.html - {Version 3.3.1} {version 3.3.1}
  • releaselog/3_3_10.html - {Version 3.3.10} {version 3.3.10}
  • releaselog/3_3_11.html - {Version 3.3.11} {version 3.3.11}
  • releaselog/3_3_12.html - {Version 3.3.12} {version 3.3.12}
  • releaselog/3_3_13.html - {Version 3.3.13} {version 3.3.13}
  • releaselog/3_3_14.html - {Version 3.3.14} {version 3.3.14}
  • releaselog/3_3_15.html - {Version 3.3.15} {version 3.3.15}
  • releaselog/3_3_16.html - {Version 3.3.16} {version 3.3.16}
  • releaselog/3_3_17.html - {Version 3.3.17} {version 3.3.17}
  • releaselog/3_3_2.html - {Version 3.3.2} {version 3.3.2}
  • releaselog/3_3_3.html - {Version 3.3.3} {version 3.3.3}
  • releaselog/3_3_4.html - {Version 3.3.4} {version 3.3.4}
  • releaselog/3_3_5.html - {Version 3.3.5} {version 3.3.5}
  • releaselog/3_3_6.html - {Version 3.3.6} {version 3.3.6}
  • releaselog/3_3_7.html - {Version 3.3.7} {version 3.3.7}
  • releaselog/3_3_8.html - {Version 3.3.8} {version 3.3.8}
  • releaselog/3_3_9.html - {Version 3.3.9} {version 3.3.9}
  • releaselog/3_4_0.html - {Version 3.4.0} {version 3.4.0}
  • releaselog/3_4_1.html - {Version 3.4.1} {version 3.4.1}
  • releaselog/3_4_2.html - {Version 3.4.2} {version 3.4.2}
  • releaselog/3_5_0.html - {Version 3.5.0} {version 3.5.0}
  • releaselog/3_5_1.html - {Version 3.5.1} {version 3.5.1}
  • releaselog/3_5_2.html - {Version 3.5.2} {version 3.5.2}
  • releaselog/3_5_3.html - {Version 3.5.3} {version 3.5.3}
  • releaselog/3_5_4.html - {Version 3.5.4} {version 3.5.4}
  • releaselog/3_5_5.html - {Version 3.5.5} {version 3.5.5}
  • releaselog/3_5_6.html - {Version 3.5.6} {version 3.5.6}
  • releaselog/3_5_7.html - {Version 3.5.7} {version 3.5.7}
  • releaselog/3_5_8.html - {Version 3.5.8} {version 3.5.8}
  • releaselog/3_5_9.html - {Version 3.5.9} {version 3.5.9}
  • releaselog/3_6_0.html - {Version 3.6.0} {version 3.6.0}
  • releaselog/3_6_1.html - {Version 3.6.1} {version 3.6.1}
  • releaselog/3_6_10.html - {Version 3.6.10} {version 3.6.10}
  • releaselog/3_6_11.html - {Version 3.6.11} {version 3.6.11}
  • releaselog/3_6_12.html - {Version 3.6.12} {version 3.6.12}
  • releaselog/3_6_13.html - {Version 3.6.13} {version 3.6.13}
  • releaselog/3_6_14.html - {Version 3.6.14} {version 3.6.14}
  • releaselog/3_6_14_1.html - {Version 3.6.14.1} {version 3.6.14.1}
  • releaselog/3_6_14_2.html - {Version 3.6.14.2} {version 3.6.14.2}
  • releaselog/3_6_15.html - {Version 3.6.15} {version 3.6.15}
  • releaselog/3_6_16.html - {Version 3.6.16} {version 3.6.16}
  • releaselog/3_6_16_1.html - {Version 3.6.16.1} {version 3.6.16.1}
  • releaselog/3_6_17.html - {Version 3.6.17} {version 3.6.17}
  • releaselog/3_6_18.html - {Version 3.6.18} {version 3.6.18}
  • releaselog/3_6_19.html - {Version 3.6.19} {version 3.6.19}
  • releaselog/3_6_2.html - {Version 3.6.2} {version 3.6.2}
  • releaselog/3_6_20.html - {Version 3.6.20} {version 3.6.20}
  • releaselog/3_6_21.html - {Version 3.6.21} {version 3.6.21}
  • releaselog/3_6_22.html - {Version 3.6.22} {version 3.6.22}
  • releaselog/3_6_23.html - {Version 3.6.23} {version 3.6.23}
  • releaselog/3_6_23_1.html - {Version 3.6.23.1} {version 3.6.23.1}
  • releaselog/3_6_3.html - {Version 3.6.3} {version 3.6.3}
  • releaselog/3_6_4.html - {Version 3.6.4} {version 3.6.4}
  • releaselog/3_6_5.html - {Version 3.6.5} {version 3.6.5}
  • releaselog/3_6_6.html - {Version 3.6.6} {version 3.6.6}
  • releaselog/3_6_6_1.html - {Version 3.6.6.1} {version 3.6.6.1}
  • releaselog/3_6_6_2.html - {Version 3.6.6.2} {version 3.6.6.2}
  • releaselog/3_6_7.html - {Version 3.6.7} {version 3.6.7}
  • releaselog/3_6_8.html - {Version 3.6.8} {version 3.6.8}
  • releaselog/3_6_9.html - {Version 3.6.9} {version 3.6.9}
  • releaselog/3_7_0.html - {Version 3.7.0} {version 3.7.0}
  • releaselog/3_7_0_1.html - {Version 3.7.0.1} {version 3.7.0.1}
  • releaselog/3_7_1.html - {Version 3.7.1} {version 3.7.1}
  • releaselog/3_7_2.html - {Version 3.7.2} {version 3.7.2}
  • releaselog/3_7_3.html - {Version 3.7.3} {version 3.7.3}
  • releaselog/3_7_4.html - {Version 3.7.4} {version 3.7.4}
  • releaselog/3_7_5.html - {Version 3.7.5} {version 3.7.5}
  • releaselog/3_7_6.html - {Version 3.7.6} {version 3.7.6}
  • releaselog/3_7_6_1.html - {Version 3.7.6.1} {version 3.7.6.1}
  • releaselog/3_7_6_2.html - {Version 3.7.6.2} {version 3.7.6.2}
  • releaselog/3_7_6_3.html - {Version 3.7.6.3} {version 3.7.6.3}
  • releaselog/3_7_7.html - {Version 3.7.7} {version 3.7.7}
  • releaselog/3_7_7_1.html - {Version 3.7.7.1} {version 3.7.7.1}
  • releaselog/3_7_8.html - {Version 3.7.8} {version 3.7.8}
  • releaselog/3_7_9.html - {Version 3.7.9} {version 3.7.9}
  • requirements.html - requirements
  • rtree.html - {R-Tree extension} R-Trees RTREE rtree
  • rtree.html#customquery - {custom r-tree queries}
  • session/funclist.html - {Session Module C-API function list} session_funclist
  • session/intro.html - {Session Module C-language Interface} session
  • sharedcache.html - {SQLite Shared-Cache Mode} {shared cache mode}
  • shortnames.html - {short filenames}
  • shortnames.html#db83corrupt - {database corruption caused by inconsistent use of 83 filenames}
  • sitemap.html#pindex - {permuted index}
  • sqlite.html - CLI {Command Line Interface} {command-line shell}
  • support.html#mailinglists - {mailing lists}
  • support.html#prosupport - {professional support}
  • syntaxdiagrams.html - {syntax diagrams}
  • syntaxdiagrams.html#alter-table-stmt - alter-table-stmt {alter-table-stmt syntax diagram}
  • syntaxdiagrams.html#analyze-stmt - analyze-stmt {analyze-stmt syntax diagram}
  • syntaxdiagrams.html#attach-stmt - attach-stmt {attach-stmt syntax diagram}
  • syntaxdiagrams.html#begin-stmt - begin-stmt {begin-stmt syntax diagram}
  • syntaxdiagrams.html#column-constraint - column-constraint {column-constraint syntax diagram}
  • syntaxdiagrams.html#column-def - column-def {column-def syntax diagram}
  • syntaxdiagrams.html#comment-syntax - comment-syntax {comment-syntax syntax diagram}
  • syntaxdiagrams.html#commit-stmt - commit-stmt {commit-stmt syntax diagram}
  • syntaxdiagrams.html#compound-operator - compound-operator {compound-operator syntax diagram}
  • syntaxdiagrams.html#conflict-clause - conflict-clause {conflict-clause syntax diagram}
  • syntaxdiagrams.html#create-index-stmt - create-index-stmt {create-index-stmt syntax diagram}
  • syntaxdiagrams.html#create-table-stmt - create-table-stmt {create-table-stmt syntax diagram}
  • syntaxdiagrams.html#create-trigger-stmt - create-trigger-stmt {create-trigger-stmt syntax diagram}
  • syntaxdiagrams.html#create-view-stmt - create-view-stmt {create-view-stmt syntax diagram}
  • syntaxdiagrams.html#create-virtual-table-stmt - create-virtual-table-stmt {create-virtual-table-stmt syntax diagram}
  • syntaxdiagrams.html#delete-stmt - delete-stmt {delete-stmt syntax diagram}
  • syntaxdiagrams.html#delete-stmt-limited - delete-stmt-limited {delete-stmt-limited syntax diagram}
  • syntaxdiagrams.html#detach-stmt - detach-stmt {detach-stmt syntax diagram}
  • syntaxdiagrams.html#drop-index-stmt - drop-index-stmt {drop-index-stmt syntax diagram}
  • syntaxdiagrams.html#drop-table-stmt - drop-table-stmt {drop-table-stmt syntax diagram}
  • syntaxdiagrams.html#drop-trigger-stmt - drop-trigger-stmt {drop-trigger-stmt syntax diagram}
  • syntaxdiagrams.html#drop-view-stmt - drop-view-stmt {drop-view-stmt syntax diagram}
  • syntaxdiagrams.html#expr - expr {expr syntax diagram}
  • syntaxdiagrams.html#foreign-key-clause - foreign-key-clause {foreign-key-clause syntax diagram}
  • syntaxdiagrams.html#indexed-column - indexed-column {indexed-column syntax diagram}
  • syntaxdiagrams.html#insert-stmt - insert-stmt {insert-stmt syntax diagram}
  • syntaxdiagrams.html#join-constraint - join-constraint {join-constraint syntax diagram}
  • syntaxdiagrams.html#join-op - join-op {join-op syntax diagram}
  • syntaxdiagrams.html#join-source - join-source {join-source syntax diagram}
  • syntaxdiagrams.html#literal-value - literal-value {literal-value syntax diagram}
  • syntaxdiagrams.html#numeric-literal - numeric-literal {numeric-literal syntax diagram}
  • syntaxdiagrams.html#ordering-term - ordering-term {ordering-term syntax diagram}
  • syntaxdiagrams.html#pragma-stmt - pragma-stmt {pragma-stmt syntax diagram}
  • syntaxdiagrams.html#pragma-value - pragma-value {pragma-value syntax diagram}
  • syntaxdiagrams.html#qualified-table-name - qualified-table-name {qualified-table-name syntax diagram}
  • syntaxdiagrams.html#raise-function - raise-function {raise-function syntax diagram}
  • syntaxdiagrams.html#reindex-stmt - reindex-stmt {reindex-stmt syntax diagram}
  • syntaxdiagrams.html#release-stmt - release-stmt {release-stmt syntax diagram}
  • syntaxdiagrams.html#result-column - result-column {result-column syntax diagram}
  • syntaxdiagrams.html#rollback-stmt - rollback-stmt {rollback-stmt syntax diagram}
  • syntaxdiagrams.html#savepoint-stmt - savepoint-stmt {savepoint-stmt syntax diagram}
  • syntaxdiagrams.html#select-core - select-core {select-core syntax diagram}
  • syntaxdiagrams.html#select-stmt - select-stmt {select-stmt syntax diagram}
  • syntaxdiagrams.html#signed-number - signed-number {signed-number syntax diagram}
  • syntaxdiagrams.html#single-source - single-source {single-source syntax diagram}
  • syntaxdiagrams.html#sql-stmt - sql-stmt {sql-stmt syntax diagram}
  • syntaxdiagrams.html#sql-stmt-list - sql-stmt-list {sql-stmt-list syntax diagram}
  • syntaxdiagrams.html#table-constraint - table-constraint {table-constraint syntax diagram}
  • syntaxdiagrams.html#type-name - type-name {type-name syntax diagram}
  • syntaxdiagrams.html#update-stmt - update-stmt {update-stmt syntax diagram}
  • syntaxdiagrams.html#update-stmt-limited - update-stmt-limited {update-stmt-limited syntax diagram}
  • syntaxdiagrams.html#vacuum-stmt - vacuum-stmt {vacuum-stmt syntax diagram}
  • tclsqlite.html - {TCL Interface} {Tcl extension}
  • tclsqlite.html#varsubst - {TCL variable substitution}
  • tempfiles.html - {temporary disk files}
  • tempfiles.html#tempstore - tempstore
  • testing.html - {test suite} tested testing
  • testing.html#coverage - {test coverage}
  • testing.html#harnesses - {test harness} {three test harnesses}
  • testing.html#mcdc - MC/DC {MC/DC testing}
  • testing.html#slt - SLT {SQL Logic Tests}
  • testing.html#tcl - {TCL test suite}
  • testing.html#testcase - {testcase macros}
  • th3.html - TH3
  • threadsafe.html - {threading mode}
  • unlock_notify.html - {Using the SQLite Unlock Notification Feature}
  • uri.html - URI {URI filename} {URI filenames} {Uniform Resource Identifier}
  • uri.html#coreqp - {query parameters with special meaning to SQLite}
  • vfs.html - {OS backend} VFS VFSes
  • vtab.html - {virtual table} {virtual tables}
  • vtab.html#hiddencol - {hidden column}
  • vtab.html#sqlite3_module.xDestroy - xDestroy
  • vtab.html#xBegin - sqlite3_module.xBegin xBegin
  • vtab.html#xbestindex - sqlite3_module.xBestIndex xBestIndex
  • vtab.html#xclose - sqlite3_module.xClose
  • vtab.html#xcolumn - sqlite3_module.xColumn xColumn
  • vtab.html#xcommit - sqlite3_module.xCommit xCommit
  • vtab.html#xconnect - sqlite3_module.xConnect xConnect
  • vtab.html#xcreate - sqlite3_module.xCreate xCreate
  • vtab.html#xdisconnect - sqlite3_module.xDisconnect xDisconnect
  • vtab.html#xeof - sqlite3_module.xEof xEof
  • vtab.html#xfilter - sqlite3_module.xFilter xFilter
  • vtab.html#xfindfunction - sqlite3_module.xFindFunction xFindFunction
  • vtab.html#xnext - sqlite3_module.xNext xNext
  • vtab.html#xopen - sqlite3_module.xOpen
  • vtab.html#xrename - sqlite3_module.xRename xRename
  • vtab.html#xrollback - sqlite3_module.xRollback xRollback
  • vtab.html#xrowid - sqlite3_module.xRowid xRowid
  • vtab.html#xsavepoint - sqlite3_module.xSavepoint xRelease xRollbackTo xSavepoint
  • vtab.html#xsync - sqlite3_module.xSync
  • vtab.html#xupdate - sqlite3_module.xUpdate xUpdate
  • wal.html - WAL {WAL mode} {write-ahead log}
  • wal.html#bkwrds - {WAL backwards compatibility}
  • wal.html#ckpt - checkpoint checkpointed checkpointing
  • wal.html#concurrency - {WAL concurrency}
  • wal.html#noshm - {WAL without shared memory}
  • wal.html#readonly - {read-only WAL databases}
  • whentouse.html#appfileformat - {application file-format}


Alphabetical List Of SQLite Documents

See Also:
  • Categorical Document List
  • Books About SQLite
  • Permuted Title Index
  • Website Keyword Index
  1. 8+3 Filenames
  2. About SQLite
  3. Alphabetical List Of SQLite Documents
  4. An Asynchronous I/O Module For SQLite
  5. An Introduction To The SQLite C/C++ Interface
  6. Appropriate Uses For SQLite
  7. Architecture of SQLite
  8. Atomic Commit In SQLite
  9. Books About SQLite
  10. C/C++ Interface For SQLite Version 3
  11. C/C++ Interface For SQLite Version 3 (old)
  12. Command Line Shell For SQLite
  13. Compilation Options For SQLite
  14. Constraint Conflict Resolution in SQLite
  15. Custom Builds Of SQLite
  16. Datatypes In SQLite version 2
  17. Datatypes In SQLite Version 3
  18. Distinctive Features Of SQLite
  19. Dynamic Memory Allocation In SQLite
  20. EXPLAIN QUERY PLAN
  21. Features Of SQLite
  22. File Format Changes in SQLite
  23. File Format For SQLite Databases
  24. File Locking And Concurrency In SQLite Version 3
  25. How SQLite Is Tested
  26. How To Compile SQLite
  27. How To Corrupt An SQLite Database File
  28. Implementation Limits For SQLite
  29. In-Memory Databases
  30. Internal Versus External BLOBs
  31. Most Widely Deployed SQL Database Engine
  32. NULL Handling in SQLite
  33. Pragma statements supported by SQLite
  34. Private Branches Of SQLite
  35. Query Language Understood by SQLite
  36. Query Planning
  37. Recent SQLite News
  38. Release History Of SQLite
  39. SQL Features That SQLite Does Not Implement
  40. SQLite Autoincrement
  41. SQLite Backup API
  42. SQLite Changes From Version 3.4.2 To 3.5.0
  43. SQLite Changes From Version 3.5.9 To 3.6.0
  44. SQLite Consortium
  45. SQLite Copyright
  46. SQLite Database Speed Comparison
  47. SQLite Developer Links
  48. SQLite Developers
  49. SQLite Documentation
  50. SQLite Download Page
  51. SQLite Foreign Key Support
  52. SQLite Frequently Asked Questions
  53. SQLite FTS3 and FTS4 Extensions
  54. SQLite Home Page
  55. SQLite In 5 Minutes Or Less
  56. SQLite Is Self-Contained
  57. SQLite Is Serverless
  58. SQLite Is Transactional
  59. SQLite Library Footprint
  60. SQLite Older News
  61. SQLite Session Module C/C++ Interface
  62. SQLite Shared-Cache Mode
  63. SQLite Site Map
  64. SQLite Support Options
  65. SQLite TH3
  66. SQLite Unlock-Notify API
  67. SQLite Version 3 Overview
  68. SQLite Virtual Machine Opcodes
  69. SQLite: Single File Database
  70. Syntax Diagrams For SQLite
  71. Temporary Files Used By SQLite
  72. The C language interface to SQLite Version 2
  73. The OS Backend (VFS) To SQLite
  74. The SQLite Amalgamation
  75. The SQLite Query Optimizer Overview
  76. The SQLite R*Tree Module
  77. The Tcl interface to the SQLite library
  78. The Virtual Database Engine of SQLite
  79. The Virtual Table Mechanism Of SQLite
  80. Uniform Resource Identifiers
  81. Using SQLite In Multi-Threaded Applications
  82. Website Keyword Index
  83. Well-Known Users Of SQLite
  84. Write-Ahead Logging
  85. Zero-Configuration


SQLite Documentation

Choose any three.
About Sitemap Documentation Download License News Support

Categorical Index Of SQLite Documents

Overview Documents
About SQLite | A high-level overview of what SQLite is and why you might be interested in using it.
Appropriate Uses For SQLite | This document describes situations where SQLite is an appropriate database engine to use versus situations where a client/server database engine might be a better choice.
Distinctive Features | This document enumerates and describes some of the features of SQLite that make it different from other SQL database engines.
How SQLite Is Tested | The reliability and robustness of SQLite is achieved in large part by thorough and careful testing. This document identifies the many tests that occur before every release of SQLite.
Copyright | SQLite is in the public domain. This document describes what that means and the implications for contributors.
Frequently Asked Questions | The title of the document says all...
Books About SQLite | A list of independently written books about SQLite.
Alphabetical Listing Of Documents | A list of all titled pages on this website, sorted by title.
Website Keyword Index | A cross-reference from keywords to various pages within this website.
Permuted Title Index | Also known as a "keyword in context" or "KWIC" index or as a concordance, this document is a listing of all other documents sorted by keyword.
SQLite Programming Interfaces Documentation describing the APIs used to program SQLite, and the SQL dialect that it interprets.
SQLite In 5 Minutes Or Less | A very quick introduction to programming with SQLite.
Introduction to the C/C++ API | This document introduces the C/C++ API. Users should read this document before the C/C++ API Reference Guide linked below.
C/C++ API Reference | This document describes each API function separately.
Tcl API | A description of the TCL interface bindings for SQLite.
SQL Syntax | This document describes the SQL language that is understood by SQLite.
Pragma commands | This document describes SQLite performance tuning options and other special purpose database commands.
Version 3 DataTypes | SQLite version 3 introduces the concept of manifest typing, where the type of a value is associated with the value itself, not the column that it is stored in. This page describes data typing for SQLite version 3 in further detail.
Null Handling | Different SQL database engines handle NULLs in different ways. The SQL standards are ambiguous. This document describes how SQLite handles NULLs in comparison with other SQL database engines.
Unsupported SQL | This page describes features of SQL that SQLite does not support.
SQLite Features and Extensions Pages describing specific features or extension modules of SQLite.
Asynchronous IO Mode | This page describes the asynchronous IO extension developed alongside SQLite. Using asynchronous IO can cause SQLite to appear more responsive by delegating database writes to a background thread.
Foreign Key Support | This document describes the support for foreign key constraints introduced in version 3.6.19.
Shared Cache Mode | Version 3.3.0 and later supports the ability for two or more database connections to share the same page and schema cache. This feature is useful for certain specialized applications.
Unlock Notify | The "unlock notify" feature can be used in conjunction with shared cache mode to more efficiently manage resource conflict (database table locks).
Using The Online Backup Interface | The online-backup interface can be used to copy content from a disk file into an in-memory database or vice versa and it can make a hot backup of a live database. This application note gives examples of how.
R-Trees | A description of the SQLite R-Tree extension. An R-Tree is a specialized data structure that supports fast multi-dimensional range queries often used in geospatial systems.
Full Text Search | A description of the SQLite Full Text Search (FTS3) extension.
Upgrading SQLite, Backwards Compatibility
Moving From SQLite 3.5 to 3.6 | A document describing the differences between SQLite version 3.5.9 and 3.6.0.
Moving From SQLite 3.4 to 3.5 | A document describing the differences between SQLite version 3.4.2 and 3.5.0.
Release History | A chronology of SQLite releases going back to version 1.0.0
Backwards Compatibility | This document details all of the incompatible changes to the SQLite file format that have occurred since version 1.0.0.
Private Branches | This document suggests procedures for maintaining a private branch or fork of SQLite and keeping that branch or fork in sync with the public SQLite source tree.
SQLite Technical/Design Documentation
Temporary Files Used By SQLite | SQLite can potentially use many different temporary files when processing certain SQL statements. This document describes the many kinds of temporary files that SQLite uses and offers suggestions for avoiding them on systems where creating a temporary file is an expensive operation.
In-Memory Databases | SQLite normally stores content in a disk file. However, it can also be used as an in-memory database engine. This document explains how.
How SQLite Implements Atomic Commit | A description of the logic within SQLite that implements transactions with atomic commit, even in the face of power failures.
Dynamic Memory Allocation in SQLite | SQLite has a sophisticated memory allocation subsystem that can be configured and customized to meet memory usage requirements of the application and that is robust against out-of-memory conditions and leak-free. This document provides the details.
Customizing And Porting SQLite | This document explains how to customize the build of SQLite and how to port SQLite to new platforms.
Locking And Concurrency In SQLite Version 3 | A description of how the new locking code in version 3 increases concurrency and decreases the problem of writer starvation.
Overview Of The Optimizer | A quick overview of the various query optimizations that are attempted by the SQLite code generator.
Architecture | An architectural overview of the SQLite library, useful for those who want to hack the code.
VDBE Opcodes | This document is an automatically generated description of the various opcodes that the VDBE understands. Programmers can use this document as a reference to better understand the output of EXPLAIN listings from SQLite.
SQLite File Format | A description of the format used for SQLite database and journal files, and other details required to create software to read and write SQLite databases without using SQLite.
Compilation Options | This document describes the compile time options that may be set to modify the default behavior of the library or omit optional features in order to reduce binary size.
Limits In SQLite | This document describes limitations of SQLite (the maximum length of a string or blob, the maximum size of a database, the maximum number of tables in a database, etc.) and how these limits can be altered at compile-time and run-time.
Old Documents These documents either pertain to SQLite version 2 or were written during the transition period between versions 2 and 3. They are no longer strictly applicable to recent versions of SQLite, but the information found within may still be useful.
Version 2 C/C++ API | A description of the C/C++ interface bindings for SQLite through version 2.8
Version 2 DataTypes | A description of how SQLite version 2 handles SQL datatypes. Short summary: Everything is a string.
VDBE Tutorial | The VDBE is the subsystem within SQLite that does the actual work of executing SQL statements. This page describes the principles of operation for the VDBE in SQLite version 2.7. This is essential reading for anyone who want to modify the SQLite sources.
SQLite Version 3 | A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
Version 3 C/C++ API | A summary of of the API related changes between SQLite version 2.8 and SQLite version 3.0.
Speed Comparison | The speed of version 2.7.6 of SQLite is compared against PostgreSQL and MySQL.


SQLite Download Page

Build Product Names

Beginning with SQLite version 3.7.4, the names of the build products have changed to be more consistent. (Prior to version 3.7.4, the names of build products were seemingly random.) Build products are named using one of the following templates:

  1. sqlite-product-version.zip
  2. sqlite-product-version.tar.gz
  3. sqlite-product-os-cpu-version.zip
  4. sqlite-product-date.zip

Templates (1) and (2) are used for source-code products. Template (1) is used for generic source-code products and templates (2) is used for source-code products that are generally only useful on unix-like platforms. Template (3) is used for precompiled binaries products. Template (4) is used for unofficial pre-release "snapshots" of source code.

The version is encoded so that filenames sort in order of increasing version number when viewed using "ls". For version 3.X.Y the filename encoding is 3XXYY00. For branch version 3.X.Y.Z, the encoding is 3XXYYZZ.

The date in template (4) is of the form: YYYYMMDDHHMM

Canonical Source Code

The canonical SQLite source code is maintained in three self-synchronizing Fossil repositories that are available for anonymous read-only access. Anyone can view the repository contents and download historical versions of individual files or ZIP archives of historical check-ins.

Note that a unix-like development environment, including a recent version of Tcl, is required in order to build from the canonical sources.

http://www.sqlite.org/cgi/src (Dallas)
http://www2.sqlite.org/cgi/src (Newark)
http://www3.sqlite.org/cgi/src (Fremont)

The documentation is maintained in separate Fossil repositories located at:

http://www.sqlite.org/cgi/docsrc (Dallas)
http://www2.sqlite.org/cgi/docsrc (Newark)
http://www3.sqlite.org/cgi/docsrc (Fremont)


EXPLAIN QUERY PLAN

Choose any three.
About Sitemap Documentation Download License News Support
EXPLAIN QUERY PLAN
Table Of Contents
1. The EXPLAIN QUERY PLAN Command
1.1. Table and Index Scans
1.2. Temporary Sorting B-Trees
1.3. Subqueries
1.4. Compound Queries
2. Sample Code

1. The EXPLAIN QUERY PLAN Command

Warning: The data returned by the EXPLAIN QUERY PLAN command is intended for interactive debugging only. It may change dramatically between SQLite releases. Applications should not depend on the results of an EXPLAIN QUERY PLAN command.

The EXPLAIN QUERY PLAN SQL command is used to obtain a high-level description of the strategy or plan that SQLite uses to implement a specific SQL query. Most significantly, it reports on the way in which the query uses database indices. In interpreting and using this information to optimize database schemas and queries, users might find the documents describing how SQLite plans and optimizes queries useful.

An EXPLAIN QUERY PLAN command returns zero or more rows of four columns each. The column names are "selectid", "order", "from", "detail". The first three columns contain an integer value. The final column, "detail", contains a text value which carries most of the useful information.

EXPLAIN QUERY PLAN is most useful on a SELECT statement, but may also be appear with other statements that read data from database tables (e.g. UPDATE, DELETE, INSERT INTO ... SELECT).

1.1. Table and Index Scans

When processing a SELECT (or other) statement, SQLite may retrieve data from database tables in a variety of ways. It may scan through all the records in a table (a full-table scan), scan a contiguous subset of the records in a table based on the rowid index, scan a contiguous subset of the entries in a database index, or use a combination of the above strategies in a single scan. The various ways in which SQLite may retrieve data from a table or index are described in detail here.

For each table read by the query, the output of EXPLAIN QUERY PLAN includes a record for which the value in the "detail" column begins with either "SCAN" or "SEARCH". "SCAN" is used for a full-table scan, including cases where SQLite iterates through all records in a table in an order defined by an index. "SEARCH" indicates that only a subset of the table rows are visited. Each SCAN or SEARCH record includes the following information:

  • The name of the table data is read from.
  • Whether or not an index or automatic index is used.
  • Whether or not the covering index optimization applies.
  • Which terms of the WHERE clause are used for indexing.
  • The estimated number of rows that SQLite will visit.

For example, the following EXPLAIN QUERY PLAN command operates on a SELECT statement that is implemented by performing a full-table scan on table t1:

sqlite> EXPLAIN QUERY PLAN SELECT a, b FROM t1 WHERE a=1;
0|0|0|SCAN TABLE t1 (~100000 rows)

The example above shows SQLite estimating that the full-table scan will visit approximately 1,000,000 records. If the query were able to use an index, then the SCAN/SEARCH record would include the name of the index and, for a SEARCH record, an indication of how the subset of rows visited is identified. For example:

sqlite> CREATE INDEX i1 ON t1(a);
sqlite> EXPLAIN QUERY PLAN SELECT a, b FROM t1 WHERE a=1;
0|0|0|SEARCH TABLE t1 USING INDEX i1 (a=?) (~10 rows)

The previous example, SQLite uses index "i1" to optimize a WHERE clause term of the form (a=?) - in this case "a=1". SQLite estimates that about 10 records will match the "a=1" term. The previous example could not use a covering index, but the following example can, and that fact is reflected in the output:

sqlite> CREATE INDEX i2 ON t1(a, b);
sqlite> EXPLAIN QUERY PLAN SELECT a, b FROM t1 WHERE a=1;
0|0|0|SEARCH TABLE t1 USING COVERING INDEX i2 (a=?) (~10 rows)

All joins in SQLite are implemented using nested scans. When a SELECT query that features a join is analyzed using EXPLAIN QUERY PLAN, one SCAN or SEARCH record is output for each nested loop. For example:

sqlite> EXPLAIN QUERY PLAN SELECT t1.*, t2.* FROM t1, t2 WHERE t1.a=1 AND t1.b>2;
0|0|0|SEARCH TABLE t1 USING COVERING INDEX i2 (a=? AND b>?) (~3 rows)
0|1|1|SCAN TABLE t2 (~1000000 rows)

The second column of output (column "order") indicates the nesting order. In this case, the scan of table t1 using index i2 is the outer loop (order=0) and the full-table scan of table t2 (order=1) is the inner loop. The third column (column "from"), indicates the position in the FROM clause of the SELECT statement that the table associated with each scan occurs in. In the case above, table t1 occupies the first position in the FROM clause, so the value of column "from" is 0 in the first record. Table t2 is in the second position, so the "from" column for the corresponding SCAN record is set to 1. In the following example, the positions of t1 and t2 in the FROM clause of the SELECT are reversed. The query strategy remains the same, but the values in the "from" column of the output are adjusted accordingly.

sqlite> EXPLAIN QUERY PLAN SELECT t1.*, t2.* FROM t2, t1 WHERE t1.a=1 AND t1.b>2;
0|0|1|SEARCH TABLE t1 USING COVERING INDEX i2 (a=? AND b>?) (~3 rows)
0|1|0|SCAN TABLE t2 (~1000000 rows)

In the example above, SQLite estimates that the outer loop scan will visit approximately 3 rows, and that the inner loop will visit approximately 1,000,000. If you observe that SQLite's estimates are wildly inaccurate (and appear to be causing it to generate sub-optimal query plans), your queries may benefit from running the ANALYZE command on the database.

If the WHERE clause of a query contains an OR expression, then SQLite might use the "OR by union" strategy (also described here). In this case there will be two SEARCH records, one for each index, with the same values in both the "order" and "from" columns. For example:

sqlite> CREATE INDEX i3 ON t1(b);
sqlite> EXPLAIN QUERY PLAN SELECT * FROM t1 WHERE a=1 OR b=2;
0|0|0|SEARCH TABLE t1 USING COVERING INDEX i2 (a=?) (~10 rows)
0|0|0|SEARCH TABLE t1 USING INDEX i3 (b=?) (~10 rows)

1.2. Temporary Sorting B-Trees

If a SELECT query contains an ORDER BY, GROUP BY or DISTINCT clause, SQLite may need to use a temporary b-tree structure to sort the output rows. Or, it might use an index. Using an index is almost always much more efficient than performing a sort. If a temporary b-tree is required, a record is added to the EXPLAIN QUERY PLAN output with the "detail" field set to a string value of the form "USE TEMP B-TREE FOR xxx", where xxx is one of "ORDER BY", "GROUP BY" or "DISTINCT". For example:

sqlite> EXPLAIN QUERY PLAN SELECT c, d FROM t2 ORDER BY c;
0|0|0|SCAN TABLE t2 (~1000000 rows)
0|0|0|USE TEMP B-TREE FOR ORDER BY

In this case using the temporary b-tree can be avoided by creating an index on t2(c), as follows:

sqlite> CREATE INDEX i4 ON t2(c);
sqlite> EXPLAIN QUERY PLAN SELECT c, d FROM t2 ORDER BY c;
0|0|0|SCAN TABLE t2 USING INDEX i4 (~1000000 rows)

1.3. Subqueries

In all the examples above, the first column (column "selectid") is always set to 0. If a query contains sub-selects, either as part of the FROM clause or as part of SQL expressions, then the output of EXPLAIN QUERY PLAN also includes a report for each sub-select. Each sub-select is assigned a distinct, non-zero "selectid" value. The top-level SELECT statement is always assigned the selectid value 0. For example:

sqlite> EXPLAIN QUERY PLAN SELECT (SELECT b FROM t1 WHERE a=0), (SELECT a FROM t1 WHERE b=t2.c) FROM t2;
0|0|0|SCAN TABLE t2 (~1000000 rows)
0|0|0|EXECUTE SCALAR SUBQUERY 1
1|0|0|SEARCH TABLE t1 USING COVERING INDEX i2 (a=?) (~10 rows)
0|0|0|EXECUTE CORRELATED SCALAR SUBQUERY 2
2|0|0|SEARCH TABLE t1 USING INDEX i3 (b=?) (~10 rows)

The example above contains a pair of scalar subqueries assigned selectid values 1 and 2. As well as a SCAN record, there are also 2 "EXECUTE" records associated with the top level subquery (selectid 0), indicating that subqueries 1 and 2 are executed by the top level query in a scalar context. The CORRELATED qualifier present in the EXECUTE record associated with scalar subquery 2 indicates that the query must be run separately for each row visited by the top level query. Its absence in the record associated with subquery 1 means that the subquery is only run once and the result cached. In other words, subquery 2 may be more performance critical, as it may be run many times whereas subquery 1 is only ever run once.

Unless the flattening optimization is applied, if a subquery appears in the FROM clause of a SELECT statement, SQLite executes the subquery and stores the results in a temporary table. It then uses the contents of the temporary table in place of the subquery to execute the parent query. This is shown in the output of EXPLAIN QUERY PLAN by substituting a "SCAN SUBQUERY" record for the "SCAN TABLE" record that normally appears for each element in the FROM clause. For example:

sqlite> EXPLAIN QUERY PLAN SELECT count(*) FROM (SELECT max(b) AS x FROM t1 GROUP BY a) GROUP BY x;
1|0|0|SCAN TABLE t1 USING COVERING INDEX i2 (~1000000 rows)
0|0|0|SCAN SUBQUERY 1 (~1000000 rows)
0|0|0|USE TEMP B-TREE FOR GROUP BY

If the flattening optimization is used on a subquery in the FROM clause of a SELECT statement, then the output of EXPLAIN QUERY PLAN reflects this. For example, in the following there is no "SCAN SUBQUERY" record even though there is a subquery in the FROM clause of the top level SELECT. Instead, since the flattening optimization does apply in this case, the EXPLAIN QUERY PLAN report shows that the top level query is implemented using a nested loop join of tables t1 and t2.

sqlite> EXPLAIN QUERY PLAN SELECT * FROM (SELECT * FROM t2 WHERE c=1), t1;
0|0|0|SEARCH TABLE t2 USING INDEX i4 (c=?) (~10 rows)
0|1|1|SCAN TABLE t1 (~1000000 rows)

1.4. Compound Queries

Each component query of a compound query (UNION, UNION ALL, EXCEPT or INTERSECT) is assigned its own selectid and reported on separately. A single record is output for the parent (compound query) identifying the operation, and whether or not a temporary b-tree is used to implement it. For example:

sqlite> EXPLAIN QUERY PLAN SELECT a FROM t1 UNION SELECT c FROM t2;
1|0|0|SCAN TABLE t1 (~1000000 rows)
2|0|0|SCAN TABLE t2 (~1000000 rows)
0|0|0|COMPOUND SUBQUERIES 1 AND 2 USING TEMP B-TREE (UNION)

The "USING TEMP B-TREE" clause in the above output indicates that a temporary b-tree structure is used to implement the UNION of the results of the two sub-selects. If the temporary b-tree were not required, as in the following example, the clause is not present.

sqlite> EXPLAIN QUERY PLAN SELECT a FROM t1 EXCEPT SELECT d FROM t2 ORDER BY 1;
1|0|0|SCAN TABLE t1 USING COVERING INDEX i2 (~1000000 rows)
2|0|0|SCAN TABLE t2 (~1000000 rows)
2|0|0|USE TEMP B-TREE FOR ORDER BY
0|0|0|COMPOUND SUBQUERIES 1 AND 2 (EXCEPT)

2. Sample Code

Sometimes, within a large application, it may be inconvenient to modify code to generate EXPLAIN QUERY PLAN commands for the SELECT queries being investigated. From within an interactive debugging session, it may be almost impossible. In these situations, a function similar to the following may be useful. This particular function is passed an SQLite statement handle as an argument and outputs the corresponding EXPLAIN QUERY PLAN report to standard output. Application specific versions may output the report to an application log or similar.

/*
** Argument pStmt is a prepared SQL statement. This function compiles
** an EXPLAIN QUERY PLAN command to report on the prepared statement,
** and prints the report to stdout using printf().
*/
int printExplainQueryPlan(sqlite3_stmt *pStmt){
  const char *zSql;               /* Input SQL */
  char *zExplain;                 /* SQL with EXPLAIN QUERY PLAN prepended */
  sqlite3_stmt *pExplain;         /* Compiled EXPLAIN QUERY PLAN command */
  int rc;                         /* Return code from sqlite3_prepare_v2() */

  zSql = sqlite3_sql(pStmt);
  if( zSql==0 ) return SQLITE_ERROR;

  zExplain = sqlite3_mprintf("EXPLAIN QUERY PLAN %s", zSql);
  if( zExplain==0 ) return SQLITE_NOMEM;

  rc = sqlite3_prepare_v2(sqlite3_db_handle(pStmt), zExplain, -1, &pExplain, 0);
  sqlite3_free(zExplain);
  if( rc!=SQLITE_OK ) return rc;

  while( SQLITE_ROW==sqlite3_step(pExplain) ){
    int iSelectid = sqlite3_column_int(pExplain, 0);
    int iOrder = sqlite3_column_int(pExplain, 1);
    int iFrom = sqlite3_column_int(pExplain, 2);
    const char *zDetail = (const char *)sqlite3_column_text(pExplain, 3);

    printf("%d %d %d %s\n", iSelectid, iOrder, iFrom, zDetail);
  }

  return sqlite3_finalize(pExplain);
}


Well-Known Users Of SQLite

Choose any three.
About Sitemap Documentation Download License News Support

Well-Known Users of SQLite:

A few of the better-known users of SQLite are shown below in alphabetical order. There is no complete list of projects and companies that use SQLite. SQLite is in the public domain and so many people use it in their projects without ever telling us.

Adobe uses SQLite as the application file format for their Photoshop Lightroom product. SQLite is also a standard part of the Adobe Integrated Runtime (AIR). It is reported that Acrobat Reader also uses SQLite.
Airbus confirms that SQLite is being used in the flight software for the A350 XWB family of aircraft.
Apple uses SQLite for many functions within Mac OS X, including Apple Mail, Safari, and in Aperture. Apple uses SQLite in the iPhone and in the iPod touch and in iTunes software.
The increasingly popular Dropbox file archiving and synchronization service is reported to use SQLite as the primary data store on the client side.
SQLite is the primary meta-data storage format for the Firefox Web Browser and the Thunderbird Email Reader from Mozilla.
We believe that General Electric uses SQLite in some product or another because they twice wrote to the SQLite developers requesting the US Export Control Number for SQLite. So presumably GE is using SQLite in something that they are exporting. But nobody (outside of GE) seems to know what that might be.
It is known that Google uses SQLite in their Desktop for Mac, in Google Gears, in the Android cell-phone operating system, and in the Chrome Web Browser. People are suspicious that Google uses SQLite for lots of other things that we do not know about yet. Engineers at Google have made extensive contributions to the full-text search subsystem within SQLite.
Intuit apparently uses SQLite in QuickBooks and in TurboTax to judge from some error reports from users seen here and here.
McAfee uses SQLite in its antivirus programs. Mentioned here and implied here.
It can inferred from traffic on the SQLite mailing list that at least one group within Microsoft is using SQLite in the development of a game program. No word yet if this game has actually been released or if they are still using SQLite.
The popular PHP programming language comes with both SQLite2 and SQLite3 built in.
SQLite comes bundled with the Python programming language since Python 2.5.
The REALbasic programming environment comes bundled with an enhanced version of SQLite that supports AES encryption.
There are multiple sightings of SQLite in the Skype client for Mac OS X and Windows.
Solaris 10 uses SQLite as the storage format for its Service Management Facility. Thus, Sun has essentially replaced the traditional unix /etc/inittab file with an SQLite database.
SQLite is an integral part of Symbian's operating system commonly found on high-end cellphones.
A representative of Toshiba wrote to the SQLite developers and requested the US Export Control Number for SQLite. We infer from this that Toshiba is exporting something from the US that uses SQLite, but we do not know what that something is.


SQLite Frequently Asked Questions

Choose any three.
About Sitemap Documentation Download License News Support

Frequently Asked Questions

  1. How do I create an AUTOINCREMENT field.
  2. What datatypes does SQLite support?
  3. SQLite lets me insert a string into a database column of type integer!
  4. Why doesn't SQLite allow me to use '0' and '0.0' as the primary key on two different rows of the same table?
  5. Can multiple applications or multiple instances of the same application access a single database file at the same time?
  6. Is SQLite threadsafe?
  7. How do I list all tables/indices contained in an SQLite database
  8. Are there any known size limits to SQLite databases?
  9. What is the maximum size of a VARCHAR in SQLite?
  10. Does SQLite support a BLOB type?
  11. How do I add or delete columns from an existing table in SQLite.
  12. I deleted a lot of data but the database file did not get any smaller. Is this a bug?
  13. Can I use SQLite in my commercial product without paying royalties?
  14. How do I use a string literal that contains an embedded single-quote (') character?
  15. What is an SQLITE_SCHEMA error, and why am I getting one?
  16. Why does ROUND(9.95,1) return 9.9 instead of 10.0? Shouldn't 9.95 round up?
  17. I get hundreds of compiler warnings when I compile SQLite. Isn't this a problem? Doesn't it indicate poor code quality?
  18. Case-insensitive matching of Unicode characters does not work.
  19. INSERT is really slow - I can only do few dozen INSERTs per second
  20. I accidentally deleted some important information from my SQLite database. How can I recover it?
  21. What is an SQLITE_CORRUPT error? What does it mean for the database to be "malformed"? Why am I getting this error?
  22. Does SQLite support foreign keys?
  23. I get a compiler error if I use the SQLITE_OMIT_... compile-time options when building SQLite.
  24. My WHERE clause expression column1="column1" does not work. It causes every row of the table to be returned, not just the rows where column1 has the value "column1".
  25. How are the syntax diagrams (a.k.a. "railroad" diagrams) for SQLite generated?
  26. The SQL standard requires that a UNIQUE constraint be enforced even if one or more of the columns in the constraint are NULL, but SQLite does not do this. Isn't that a bug?
  27. What is the Export Control Classification Number (ECCN) for SQLite?

(1) How do I create an AUTOINCREMENT field.

Short answer: A column declared INTEGER PRIMARY KEY will autoincrement.

Here is the long answer: If you declare a column of a table to be INTEGER PRIMARY KEY, then whenever you insert a NULL into that column of the table, the NULL is automatically converted into an integer which is one greater than the largest value of that column over all other rows in the table, or 1 if the table is empty. (If the largest possible integer key, 9223372036854775807, then an unused key value is chosen at random.) For example, suppose you have a table like this:

CREATE TABLE t1(
  a INTEGER PRIMARY KEY,
  b INTEGER
);

With this table, the statement

INSERT INTO t1 VALUES(NULL,123);

is logically equivalent to saying:

INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);

There is a function named sqlite3_last_insert_rowid() which will return the integer key for the most recent insert operation.

Note that the integer key is one greater than the largest key that was in the table just prior to the insert. The new key will be unique over all keys currently in the table, but it might overlap with keys that have been previously deleted from the table. To create keys that are unique over the lifetime of the table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY declaration. Then the key chosen will be one more than than the largest key that has ever existed in that table. If the largest possible key has previously existed in that table, then the INSERT will fail with an SQLITE_FULL error code.

(2) What datatypes does SQLite support?

SQLite uses dynamic typing. Content can be stored as INTEGER, REAL, TEXT, BLOB, or as NULL.

(3) SQLite lets me insert a string into a database column of type integer!

This is a feature, not a bug. SQLite uses dynamic typing. It does not enforce data type constraints. Any data can be inserted into any column. You can put arbitrary length strings into integer columns, floating point numbers in boolean columns, or dates in character columns. The datatype you assign to a column in the CREATE TABLE command does not restrict what data can be put into that column. Every column is able to hold an arbitrary length string. (There is one exception: Columns of type INTEGER PRIMARY KEY may only hold a 64-bit signed integer. An error will result if you try to put anything other than an integer into an INTEGER PRIMARY KEY column.)

But SQLite does use the declared type of a column as a hint that you prefer values in that format. So, for example, if a column is of type INTEGER and you try to insert a string into that column, SQLite will attempt to convert the string into an integer. If it can, it inserts the integer instead. If not, it inserts the string. This feature is called type affinity.

(4) Why doesn't SQLite allow me to use '0' and '0.0' as the primary key on two different rows of the same table?

This problem occurs when your primary key is a numeric type. Change the datatype of your primary key to TEXT and it should work.

Every row must have a unique primary key. For a column with a numeric type, SQLite thinks that '0' and '0.0' are the same value because they compare equal to one another numerically. (See the previous question.) Hence the values are not unique.

(5) Can multiple applications or multiple instances of the same application access a single database file at the same time?

Multiple processes can have the same database open at the same time. Multiple processes can be doing a SELECT at the same time. But only one process can be making changes to the database at any moment in time, however.

SQLite uses reader/writer locks to control access to the database. (Under Win95/98/ME which lacks support for reader/writer locks, a probabilistic simulation is used instead.) But use caution: this locking mechanism might not work correctly if the database file is kept on an NFS filesystem. This is because fcntl() file locking is broken on many NFS implementations. You should avoid putting SQLite database files on NFS if multiple processes might try to access the file at the same time. On Windows, Microsoft's documentation says that locking may not work under FAT filesystems if you are not running the Share.exe daemon. People who have a lot of experience with Windows tell me that file locking of network files is very buggy and is not dependable. If what they say is true, sharing an SQLite database between two or more Windows machines might cause unexpected problems.

We are aware of no other embedded SQL database engine that supports as much concurrency as SQLite. SQLite allows multiple processes to have the database file open at once, and for multiple processes to read the database at once. When any process wants to write, it must lock the entire database file for the duration of its update. But that normally only takes a few milliseconds. Other processes just wait on the writer to finish then continue about their business. Other embedded SQL database engines typically only allow a single process to connect to the database at once.

However, client/server database engines (such as PostgreSQL, MySQL, or Oracle) usually support a higher level of concurrency and allow multiple processes to be writing to the same database at the same time. This is possible in a client/server database because there is always a single well-controlled server process available to coordinate access. If your application has a need for a lot of concurrency, then you should consider using a client/server database. But experience suggests that most applications need much less concurrency than their designers imagine.

When SQLite tries to access a file that is locked by another process, the default behavior is to return SQLITE_BUSY. You can adjust this behavior from C code using the sqlite3_busy_handler() or sqlite3_busy_timeout() API functions.

(6) Is SQLite threadsafe?

Threads are evil. Avoid them.

SQLite is threadsafe. We make this concession since many users choose to ignore the advice given in the previous paragraph. But in order to be thread-safe, SQLite must be compiled with the SQLITE_THREADSAFE preprocessor macro set to 1. Both the Windows and Linux precompiled binaries in the distribution are compiled this way. If you are unsure if the SQLite library you are linking against is compiled to be threadsafe you can call the sqlite3_threadsafe() interface to find out.

Prior to version 3.3.1, an sqlite3 structure could only be used in the same thread that called sqlite3_open() to create it. You could not open a database in one thread then pass the handle off to another thread for it to use. This was due to limitations (bugs?) in many common threading implementations such as on RedHat9. Specifically, an fcntl() lock created by one thread cannot be removed or modified by a different thread on the troublesome systems. And since SQLite uses fcntl() locks heavily for concurrency control, serious problems arose if you start moving database connections across threads.

The restriction on moving database connections across threads was relaxed somewhat in version 3.3.1. With that and subsequent versions, it is safe to move a connection handle across threads as long as the connection is not holding any fcntl() locks. You can safely assume that no locks are being held if no transaction is pending and all statements have been finalized.

Under Unix, you should not carry an open SQLite database across a fork() system call into the child process. Problems will result if you do.

(7) How do I list all tables/indices contained in an SQLite database

If you are running the sqlite3 command-line access program you can type ".tables" to get a list of all tables. Or you can type ".schema" to see the complete database schema including all tables and indices. Either of these commands can be followed by a LIKE pattern that will restrict the tables that are displayed.

From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python bindings) you can get access to table and index names by doing a SELECT on a special table named "SQLITE_MASTER". Every SQLite database has an SQLITE_MASTER table that defines the schema for the database. The SQLITE_MASTER table looks like this:

CREATE TABLE sqlite_master (
  type TEXT,
  name TEXT,
  tbl_name TEXT,
  rootpage INTEGER,
  sql TEXT
);

For tables, the type field will always be 'table' and the name field will be the name of the table. So to get a list of all tables in the database, use the following SELECT command:

SELECT name FROM sqlite_master
WHERE type='table'
ORDER BY name;

For indices, type is equal to 'index', name is the name of the index and tbl_name is the name of the table to which the index belongs. For both tables and indices, the sql field is the text of the original CREATE TABLE or CREATE INDEX statement that created the table or index. For automatically created indices (used to implement the PRIMARY KEY or UNIQUE constraints) the sql field is NULL.

The SQLITE_MASTER table is read-only. You cannot change this table using UPDATE, INSERT, or DELETE. The table is automatically updated by CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.

Temporary tables do not appear in the SQLITE_MASTER table. Temporary tables and their indices and triggers occur in another special table named SQLITE_TEMP_MASTER. SQLITE_TEMP_MASTER works just like SQLITE_MASTER except that it is only visible to the application that created the temporary tables. To get a list of all tables, both permanent and temporary, one can use a command similar to the following:

SELECT name FROM
   (SELECT * FROM sqlite_master UNION ALL
    SELECT * FROM sqlite_temp_master)
WHERE type='table'
ORDER BY name

(8) Are there any known size limits to SQLite databases?

See limits.html for a full discussion of the limits of SQLite.

(9) What is the maximum size of a VARCHAR in SQLite?

SQLite does not enforce the length of a VARCHAR. You can declare a VARCHAR(10) and SQLite will be happy to let you put 500 characters in it. And it will keep all 500 characters intact - it never truncates.

(10) Does SQLite support a BLOB type?

SQLite versions 3.0 and later allow you to store BLOB data in any column, even columns that are declared to hold some other type.

(11) How do I add or delete columns from an existing table in SQLite.

SQLite has limited ALTER TABLE support that you can use to add a column to the end of a table or to change the name of a table. If you want to make more complex changes in the structure of a table, you will have to recreate the table. You can save existing data to a temporary table, drop the old table, create the new table, then copy the data back in from the temporary table.

For example, suppose you have a table named "t1" with columns names "a", "b", and "c" and that you want to delete column "c" from this table. The following steps illustrate how this could be done:

BEGIN TRANSACTION;
CREATE TEMPORARY TABLE t1_backup(a,b);
INSERT INTO t1_backup SELECT a,b FROM t1;
DROP TABLE t1;
CREATE TABLE t1(a,b);
INSERT INTO t1 SELECT a,b FROM t1_backup;
DROP TABLE t1_backup;
COMMIT;

(12) I deleted a lot of data but the database file did not get any smaller. Is this a bug?

No. When you delete information from an SQLite database, the unused disk space is added to an internal "free-list" and is reused the next time you insert data. The disk space is not lost. But neither is it returned to the operating system.

If you delete a lot of data and want to shrink the database file, run the VACUUM command. VACUUM will reconstruct the database from scratch. This will leave the database with an empty free-list and a file that is minimal in size. Note, however, that the VACUUM can take some time to run (around a half second per megabyte on the Linux box where SQLite is developed) and it can use up to twice as much temporary disk space as the original file while it is running.

As of SQLite version 3.1, an alternative to using the VACUUM command is auto-vacuum mode, enabled using the auto_vacuum pragma.

(13) Can I use SQLite in my commercial product without paying royalties?

Yes. SQLite is in the public domain. No claim of ownership is made to any part of the code. You can do anything you want with it.

(14) How do I use a string literal that contains an embedded single-quote (') character?

The SQL standard specifies that single-quotes in strings are escaped by putting two single quotes in a row. SQL works like the Pascal programming language in the regard. SQLite follows this standard. Example:

    INSERT INTO xyz VALUES('5 O''clock');

(15) What is an SQLITE_SCHEMA error, and why am I getting one?

An SQLITE_SCHEMA error is returned when a prepared SQL statement is no longer valid and cannot be executed. When this occurs, the statement must be recompiled from SQL using the sqlite3_prepare() API. An SQLITE_SCHEMA error can only occur when using the sqlite3_prepare(), and sqlite3_step() interfaces to run SQL. You will never receive an SQLITE_SCHEMA error from sqlite3_exec(). Nor will you receive a the error if you prepare statements using sqlite3_prepare_v2() instead of sqlite3_prepare().

The sqlite3_prepare_v2() interface creates a prepared statement that will automatically recompile itself if the schema changes. The easiest way to deal with SQLITE_SCHEMA errors is to always use sqlite3_prepare_v2() instead of sqlite3_prepare().

(16) Why does ROUND(9.95,1) return 9.9 instead of 10.0? Shouldn't 9.95 round up?

SQLite uses binary arithmetic and in binary, there is no way to write 9.95 in a finite number of bits. The closest to you can get to 9.95 in a 64-bit IEEE float (which is what SQLite uses) is 9.949999999999999289457264239899814128875732421875. So when you type "9.95", SQLite really understands the number to be the much longer value shown above. And that value rounds down.

This kind of problem comes up all the time when dealing with floating point binary numbers. The general rule to remember is that most fractional numbers that have a finite representation in decimal (a.k.a "base-10") do not have a finite representation in binary (a.k.a "base-2"). And so they are approximated using the closest binary number available. That approximation is usually very close, but it will be slightly off and in some cases can cause your results to be a little different from what you might expect.

(17) I get hundreds of compiler warnings when I compile SQLite. Isn't this a problem? Doesn't it indicate poor code quality?

Quality assurance in SQLite is done using full-coverage testing, not by compiler warnings or other static code analysis tools. In other words, we verify that SQLite actually gets the correct answer, not that it merely satisfies stylistic constraints. Most of the SQLite code base is devoted purely to testing. The SQLite test suite runs tens of thousands of separate test cases and many of those test cases are parameterized so that hundreds of millions of tests involving billions of SQL statements are run and evaluated for correctness prior to every release. The developers use code coverage tools to verify that all paths through the code are tested. Whenever a bug is found in SQLite, new test cases are written to exhibit the bug so that the bug cannot recur undetected in the future.

During testing, the SQLite library is compiled with special instrumentation that allows the test scripts to simulate a wide variety of failures in order to verify that SQLite recovers correctly. Memory allocation is carefully tracked and no memory leaks occur, even following memory allocation failures. A custom VFS layer is used to simulate operating system crashes and power failures in order to ensure that transactions are atomic across these events. A mechanism for deliberately injecting I/O errors shows that SQLite is resilient to such malfunctions. (As an experiment, try inducing these kinds of errors on other SQL database engines and see what happens!)

We also run SQLite using Valgrind on Linux and verify that it detects no problems.

Some people say that we should eliminate all warnings because benign warnings mask real warnings that might arise in future changes. This is true enough. But in reply, the developers observe that all warnings have already been fixed in the compilers used for SQLite development (various versions of GCC). Compiler warnings only arise from compilers that the developers do not use on a daily basis (Ex: MSVC).

(18) Case-insensitive matching of Unicode characters does not work.

The default configuration of SQLite only supports case-insensitive comparisons of ASCII characters. The reason for this is that doing full Unicode case-insensitive comparisons and case conversions requires tables and logic that would nearly double the size of the SQLite library. The SQLite developers reason that any application that needs full Unicode case support probably already has the necessary tables and functions and so SQLite should not take up space to duplicate this ability.

Instead of providing full Unicode case support by default, SQLite provides the ability to link against external Unicode comparison and conversion routines. The application can overload the built-in NOCASE collating sequence (using sqlite3_create_collation()) and the built-in like(), upper(), and lower() functions (using sqlite3_create_function()). The SQLite source code includes an "ICU" extension that does these overloads. Or, developers can write their own overloads based on their own Unicode-aware comparison routines already contained within their project.

(19) INSERT is really slow - I can only do few dozen INSERTs per second

Actually, SQLite will easily do 50,000 or more INSERT statements per second on an average desktop computer. But it will only do a few dozen transactions per second. Transaction speed is limited by the rotational speed of your disk drive. A transaction normally requires two complete rotations of the disk platter, which on a 7200RPM disk drive limits you to about 60 transactions per second.

Transaction speed is limited by disk drive speed because (by default) SQLite actually waits until the data really is safely stored on the disk surface before the transaction is complete. That way, if you suddenly lose power or if your OS crashes, your data is still safe. For details, read about atomic commit in SQLite..

By default, each INSERT statement is its own transaction. But if you surround multiple INSERT statements with BEGIN...COMMIT then all the inserts are grouped into a single transaction. The time needed to commit the transaction is amortized over all the enclosed insert statements and so the time per insert statement is greatly reduced.

Another option is to run PRAGMA synchronous=OFF. This command will cause SQLite to not wait on data to reach the disk surface, which will make write operations appear to be much faster. But if you lose power in the middle of a transaction, your database file might go corrupt.

(20) I accidentally deleted some important information from my SQLite database. How can I recover it?

If you have a backup copy of your database file, recover the information from your backup.

If you do not have a backup, recovery is very difficult. You might be able to find partial string data in a binary dump of the raw database file. Recovering numeric data might also be possible given special tools, though to our knowledge no such tools exist. SQLite is sometimes compiled with the SQLITE_SECURE_DELETE option which overwrites all deleted content with zeros. If that is the case then recovery is clearly impossible. Recovery is also impossible if you have run VACUUM since the data was deleted. If SQLITE_SECURE_DELETE is not used and VACUUM has not been run, then some of the deleted content might still be in the database file, in areas marked for reuse. But, again, there exist no procedures or tools that we know of to help you recover that data.

(21) What is an SQLITE_CORRUPT error? What does it mean for the database to be "malformed"? Why am I getting this error?

An SQLITE_CORRUPT error is returned when SQLite detects an error in the structure, format, or other control elements of the database file.

SQLite does not corrupt database files, except in the case of very rare bugs (see DatabaseCorruption) and even then the bugs are normally difficult to reproduce. Even if your application crashes in the middle of an update, your database is safe. The database is safe even if your OS crashes or takes a power loss. The crash-resistance of SQLite has been extensively studied and tested and is attested by years of real-world experience by millions of users."

That said, there are a number of things that external programs or bugs in your hardware or OS can do to corrupt a database file. Details can be found in the discussions on the atomic commit and locking support in SQLite as well as in the mailing list archives.

Your can use PRAGMA integrity_check to do a thorough but time intensive test of the database integrity.

Your can use PRAGMA quick_check to do a faster but less thorough test of the database integrity.

Depending how badly your database is corrupted, you may be able to recover some of the data by using the CLI to dump the schema and contents to a file and then recreate. Unfortunately, once humpty-dumpty falls off the wall, it is generally not possible to put him back together again.

(22) Does SQLite support foreign keys?

As of version 3.6.19, SQLite supports foreign key constraints.

Prior versions of SQLite parsed foreign key constraints, but did not enforce them. The equivalent functionality could be implemented using SQL triggers. Versions 3.6.12 and later of the SQLite shell tool provided the ".genfkey" command to generate such triggers automatically. The readme for the genfkey utility contains more information.

(23) I get a compiler error if I use the SQLITE_OMIT_... compile-time options when building SQLite.

The SQLITE_OMIT_... compile-time options only work when building from canonically source files. They do not work when you build from the SQLite amalgamation or from the pre-processed source files.

It is possible to build a special amalgamation that will work with a predetermined set of SQLITE_OMIT_... options. Instructions for doing so can be found with the SQLITE_OMIT_... documentation.

(24) My WHERE clause expression column1="column1" does not work. It causes every row of the table to be returned, not just the rows where column1 has the value "column1".

Use single-quotes, not double-quotes, around string literals in SQL. This is what the SQL standard requires. Your WHERE clause expression should read: column1='column2'

SQL uses double-quotes around identifiers (column or table names) that contains special characters or which are keywords. So double-quotes are a way of escaping identifier names. Hence, when you say column1="column1" that is equivalent to column1=column1 which is obviously always true.

(25) How are the syntax diagrams (a.k.a. "railroad" diagrams) for SQLite generated?

The process is explained at http://wiki.tcl.tk/21708.

(26) The SQL standard requires that a UNIQUE constraint be enforced even if one or more of the columns in the constraint are NULL, but SQLite does not do this. Isn't that a bug?

Perhaps you are referring to the following statement from SQL92:
A unique constraint is satisfied if and only if no two rows in a table have the same non-null values in the unique columns.
That statement is ambiguous, having at least two possible interpretations:
  1. A unique constraint is satisfied if and only if no two rows in a table have the same values and have non-null values in the unique columns.
  2. A unique constraint is satisfied if and only if no two rows in a table have the same values in the subset of unique columns that are not null.
SQLite follows interpretation (1), as does PostgreSQL, MySQL, Oracle, and Firebird. It is true that Informix and Microsoft SQL Server use interpretation (2), however we the SQLite developers hold that interpretation (1) is the most natural reading of the requirement and we also want to maximize compatibility with other SQL database engines, and most other database engines also go with (1), so that is what SQLite does.

(27) What is the Export Control Classification Number (ECCN) for SQLite?

After careful review of the Commerce Control List (CCL), we are convinced that the core public-domain SQLite source code is not described by any ECCN, hence the ECCN should be reported as EAR99.

The above is true for the core public-domain SQLite. If you extend SQLite by adding new code, or if you statically link SQLite with your application, that might change the ECCN in your particular case.


Features Of SQLite

  • Transactions are atomic, consistent, isolated, and durable (ACID) even after system crashes and power failures.
  • Zero-configuration - no setup or administration needed.
  • Implements most of SQL92. (Features not supported)
  • A complete database is stored in a single cross-platform disk file.
  • Supports terabyte-sized databases and gigabyte-sized strings and blobs. (See limits.html.)
  • Small code footprint: less than 350KiB fully configured or less than 200KiB with optional features omitted.
  • Faster than popular client/server database engines for most common operations.
  • Simple, easy to use API.
  • Written in ANSI-C. TCL bindings included. Bindings for dozens of other languages available separately.
  • Well-commented source code with 100% branch test coverage.
  • Available as a single ANSI-C source-code file that you can easily drop into another project.
  • Self-contained: no external dependencies.
  • Cross-platform: Unix (Linux and Mac OS X), OS/2, and Windows (Win32 and WinCE) are supported out of the box. Easy to port to other systems.
  • Sources are in the public domain. Use for any purpose.
  • Comes with a standalone command-line interface (CLI) client that can be used to administer SQLite databases.

Suggested Uses For SQLite:

  • Application File Format. Rather than using fopen() to write XML or some proprietary format into disk files used by your application, use an SQLite database instead. You'll avoid having to write and troubleshoot a parser, your data will be more easily accessible and cross-platform, and your updates will be transactional.

  • Database For Gadgets. SQLite is popular choice for the database engine in cellphones, PDAs, MP3 players, set-top boxes, and other electronic gadgets. SQLite has a small code footprint, makes efficient use of memory, disk space, and disk bandwidth, is highly reliable, and requires no maintenance from a Database Administrator.

  • Website Database. Because it requires no configuration and stores information in ordinary disk files, SQLite is a popular choice as the database to back small to medium-sized websites.

  • Stand-in For An Enterprise RDBMS. SQLite is often used as a surrogate for an enterprise RDBMS for demonstration purposes or for testing. SQLite is fast and requires no setup, which takes a lot of the hassle out of testing and which makes demos perky and easy to launch.


File Format For SQLite Databases

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

The SQLite Database File Format

This document describes and defines the on-disk database file format used by SQLite.

1.0 The Database File

The complete state of an SQLite database is usually contained a single file on disk called the "main database file".

During a transaction, SQLite stores additional information in a second file called the "rollback journal", or if SQLite is in WAL mode, a write-ahead log file. If the application or host computer crashes before the transaction completes, then the rollback journal or write-ahead log contains critical state information needed to restore the main database file to a consistent state. When a rollback journal or write-ahead log contain information necessary for recovering the state of the database, they are called a "hot journal" or "hot WAL file". Hot journals and WAL files are only a factor during error recovery scenarios and so are uncommon, but they are part of the state of an SQLite database and so cannot be ignored. This document defines the format of a rollback journal and the write-ahead log file, but main focus is on the main database file.

1.1 Pages

The main database file consists of one or more pages. The size of a page is a power of two between 512 and 65536 inclusive. All pages within the same database are the same size. The page size for a database file is determined by the 2-byte integer located at an offset of 16 bytes from the beginning of the database file.

Pages are numbered beginning with 1. The maximum page number is 2147483646 (231 - 2). The minimum size SQLite database is a single 512-byte page. The maximum size database would be 2147483646 pages at 65536 bytes per page or 140,737,488,224,256 bytes (about 140 terabytes). Usually SQLite will hit the maximum file size limit of the underlying filesystem or disk hardware size limit long before it hits its own internal size limit.

In common use, SQLite databases tend to range in size from a few kilobytes to a few gigabytes.

At any point in time, every page in the main database has a single use which is one of the following:

  • The lock-byte page
  • A freelist page
    • A freelist trunk page
    • A freelist leaf page
  • A b-tree page
    • A table b-tree interior page
    • A table b-tree leaf page
    • An index b-tree interior page
    • An index b-tree leaf page
  • A payload overflow page
  • A pointer map page

All reads from and writes to the main database file begin at a page boundary and all writes are an integer number of pages in size. Reads are also usually an integer number of pages in size, with the one exception that when the database is first opened, the first 100 bytes of the database file (the database file header) are read as a sub-page size unit.

Before any information-bearing page of the database is modified, the original unmodified content of that page is written into the rollback journal. If a transaction is interrupted and needs to be rolled back, the rollback journal can then be used to restore the database to its original state. Freelist leaf pages bear no information that would need to be restored on a rollback and so they are not written to the journal prior to modification, in order to reduce disk I/O.

1.2 The Database Header

The first 100 bytes of the database file comprise the database file header. The database file header is divided into fields as shown by the table below. All multibyte fields in the database file header are stored with the must significant byte first (big-endian).

Database Header Format
Offset | Size | Description
0 | 16 | The header string: "SQLite format 3\000"
16 | 2 | The database page size in bytes. Must be a power of two between 512 and 32768 inclusive, or the value 1 representing a page size of 65536.
18 | 1 | File format write version. 1 for legacy; 2 for WAL.
19 | 1 | File format read version. 1 for legacy; 2 for WAL.
20 | 1 | Bytes of unused "reserved" space at the end of each page. Usually 0.
21 | 1 | Maximum embedded payload fraction. Must be 64.
22 | 1 | Minimum embedded payload fraction. Must be 32.
23 | 1 | Leaf payload fraction. Must be 32.
24 | 4 | File change counter.
28 | 4 | Size of the database file in pages. The "in-header database size".
32 | 4 | Page number of the first freelist trunk page.
36 | 4 | Total number of freelist pages.
40 | 4 | The schema cookie.
44 | 4 | The schema format number. Supported schema formats are 1, 2, 3, and 4.
48 | 4 | Default page cache size.
52 | 4 | The page number of the largest root b-tree page when in auto-vacuum or incremental-vacuum modes, or zero otherwise.
56 | 4 | The database text encoding. A value of 1 means UTF-8. A value of 2 means UTF-16le. A value of 3 means UTF-16be.
60 | 4 | The "user version" as read and set by the user_version pragma.
64 | 4 | True (non-zero) for incremental-vacuum mode. False (zero) otherwise.
68 | 24 | Reserved for expansion. Must be zero.
92 | 4 | The version-valid-for number.
96 | 4 | SQLITE_VERSION_NUMBER

1.2.1 Magic Header String

Every valid SQLite database file begins with the following 16 bytes (in hex): 53 51 4c 69 74 65 20 66 6f 72 6d 61 74 20 33 00. This byte sequence corresponds to the UTF-8 string "SQLite format 3" including the nul terminator character at the end.

1.2.2 Page Size

The two-byte value beginning at offset 16 determines the page size of the database. For SQLite versions 3.7.0.1 and earlier, this value is interpreted as a big-endian integer and must be a power of two between 512 and 32768, inclusive. Beginning with SQLite version 3.7.1, a page size of 65536 bytes is supported. The value 65536 will not fit in a two-byte integer, so to specify a 65536-byte page size, the value is at offset 16 is 0x00 0x01. This value can be interpreted as a big-endian 1 and thought of is as a magic number to represent the 65536 page size. Or one can view the two-byte field as a little endian number and say that it represents the page size divided by 256. These two interpretations of the page-size field are equivalent.

1.2.3 File format version numbers

The file format write version and file format read version at offsets 18 and 19 are intended to allow for enhancements of the file format in future versions of SQLite. In current versions of SQLite, both of these values are 1 for rollback journalling modes and 2 for WAL journalling mode. If a version of SQLite coded to the current file format specification encounters a database file where the read version is 1 or 2 but the write version is greater than 2, then the database file must be treated as read-only. If a database file with a read version greater than 2 is encounter, then that database cannot be read or written.

1.2.4 Reserved bytes per page

SQLite has the ability to set aside a small number of extra bytes at the end of every page for use by extensions. These extra bytes are used, for example, by the SQLite Encryption Extension to store a nonce and/or cryptographic checksum associated with each page. The "reserved space" size in the 1-byte integer at offset 20 is the number of bytes of space at the end of each page to reserve for extensions. This value is usually 0. The value can be odd.

The "usable size" of a database page is the page size specify by the 2-byte integer at offset 16 in the header less the "reserved" space size recorded in the 1-byte integer at offset 20 in the header. The usable size of a page might be an odd number. However, the usable size is not allowed to be less than 480. In other words, if the page size is 512, then the reserved space size cannot exceed 32.

1.2.5 Payload fractions

The maximum and minimum embedded payload fractions and the leaf payload fraction values must be 64, 32, and 32. These values were originally intended to as tunable parameters that could be used to modify the storage format of the b-tree algorithm. However, that functionality is not supported and there are no current plans to add support in the future. Hence, these three bytes are fixed at the values specified.

1.2.6 File change counter

The file change counter is a 4-byte big-endian integer which is incremented whenever the database file is unlocked after having been modified. When two or more processes are reading the same database file, each process can detect database changes from other processes by monitoring the change counter. A process will normally want to flush its database page cache when another process modified the database, since the cache has become stale. The file change counter facilitates this.

In WAL mode, changes to the database are detected using the wal-index and so the change counter is not needed. Hence, the change counter might not be incremented on each transaction in WAL mode.

1.2.7 In-header database size

The 4-byte big-endian integer at offset 28 into the header stores the size of the database file in pages. If this in-header datasize size is not valid (see the next paragraph), then the database size is computed by looking at the actual size of the database file. Older versions of SQLite ignored the in-header database size and used the actual file size exclusively. Newer versions of SQLite use the in-header database size if it is available but fall back to the actual file size if the in-header database size is not valid.

The in-header database size is only considered to be valid if it is non-zero and if the 4-byte change counter at offset 24 exactly matches the 4-byte version-valid-for number at offset 92. The in-header database size is always valid when the database is only modified using recent versions of SQLite (versions 3.7.0 and later). If a legacy version of SQLite writes to the database, it will not know to update the in-header database size and so the in-header database size could be incorrect. But legacy versions of SQLite will also leave the version-valid-for number at offset 92 unchanged so it will not match the change-counter. Hence, invalid in-header database sizes can be detected (and ignored) by observing when the change-counter does not match the version-valid-for number.

1.2.8 Free page list

Unused pages in the database file are stored on a freelist. The 4-byte big-endian integer at offset 32 stores the page number of the first page of the freelist, or zero if the freelist is empty. The 4-byte big-endian integer at offset 36 stores stores the total number of pages on the freelist.

1.2.9 Schema cookie

The schema cookie is a 4-byte big-endian integer at offset 40 that is incremented whenever the database schema changes. A prepared statement is compiled against a specific version of the database schema. Whenever the database schema changes, the statement must be reprepared. Whenever a prepared statement runs, it first checks the schema cookie to make sure the value is the same as when the statement was prepared and if the schema cookie has changed, the statement aborts in order to force the statement to be reprepared.

1.2.10 Schema format number

The schema format number is a 4-byte big-endian integer at offset 44. The schema format number is similar to the file format read and write version numbers at offsets 18 and 19 except that the schema format number refers to the high-level SQL formatting rather than the low-level b-tree formatting. Four schema format numbers are currently defined:

  1. Format 1 is understood by all versions of SQLite back to version 3.0.0.
  2. Format 2 adds the ability of rows within the same table to have a varying number of columns, in order to support the ALTER TABLE ... ADD COLUMN functionality. Support for reading and writing format 2 was added in SQLite version 3.1.3 on 2005-02-19.
  3. Format 3 adds the ability of extra columns added by ALTER TABLE ... ADD COLUMN to have non-NULL default values. This capability was added in SQLite version 3.1.4 on 2005-03-11.
  4. Format 4 causes SQLite to respect the DESC keyword on index declarations. (The DESC keyword is ignored in indices for formats 1, 2, and 3.) Format 4 also adds two new boolean record type values (serial types 8 and 9.) Support for format 4 was added in SQLite 3.3.0 on 2006-01-10.

New database files created by SQLite use format 1 by default, so that database files created by newer versions of SQLite can still be read by older versions of SQLite. The legacy_file_format pragma can be used to cause SQLite to create new database files using format 4. Future versions of SQLite may begin to create files using format 4 by default. The format version number can be made to default to 4 instead of 1 by setting SQLITE_DEFAULT_FILE_FORMAT=4 at compile-time.

1.2.11 Suggested cache size

The 4-byte big-endian signed integer at offset 48 is the suggested cache size in pages for the database file. The value is a suggestion only and SQLite is under no obligation to honor it. The absolute value of the integer is used as the suggested size. The suggested cache size can be set using the default_cache_size pragma.

1.2.12 Incremental vacuum settings

The two 4-byte big-endian integers at offsets 52 and 64 are used to manage the auto_vacuum and incremental_vacuum modes. If the integer at offset 52 is zero then pointer-map (ptrmap) pages are omitted from the database file and neither auto_vacuum nor incremental_vacuum are supported. If the integer at offset 52 is non-zero then it is the page number of the largest root page in the database file, the database file contain ptrmap pages, and the mode must be either auto_vacuum or incremental_vacuum. In this latter case, the integer at offset 64 is true for incremental_vacuum and false for auto_vacuum. If the integer at offset 52 is zero then the integer at offset 64 must also be zero.

1.2.13 Text encoding

The 4-byte big-endian integer at offset 56 determines the encoding used for all text strings stored in the database. A value of 1 means UTF-8. A value of 2 means UTF-16le. A value of 3 means UTF-16be. No other values are allowed.

1.2.14 User version number

The 4-byte big-endian integer at offset 60 is the user version which is set and queried by the user_version pragma. The user version is not used by SQLite.

1.2.15 Write library version number and version-valid-for number

The 4-byte big-endian integer at offset 96 stores the SQLITE_VERSION_NUMBER value for the SQLite library that most recently modified the database file. The 4-byte big-ending integer at offset 92 is the value of the change counter when the version number was stored. The integer at offset 92 indicates which transaction the version number is valid for and is sometimes called the "version-valid-for number".

1.2.16 Header space reserved for expansion

All other bytes of the database file header are reserved for future expansion and must be set to zero.

1.3 The Lock-Byte Page

The lock-byte page is the single page of the database file that contains the bytes at offsets between 1073741824 and 1073742335, inclusive. A database file that is less than or equal to 1073741824 bytes in size contains no lock-byte page. A database file larger than 1073741824 contains exactly one lock-byte page.

The lock-byte page is set aside for use by the operating-system specific VFS implementation in implementing the database file locking primitives. SQLite does not use the lock-byte page. The SQLite core will never read or write, though operating-system specific VFS implementations may choose to read or write bytes on the lock-byte page according to the needs and proclivities of the underlying system. The unix and win32 VFS implementations that come built into SQLite do not write to the lock-byte page, but third-party VFS implementations for other operating systems might.

1.4 The Freelist

A database file might contain one or more pages that are not in active use. Unused pages can come about, for example, when information is deleted from the database. Unused pages are stored on the freelist and are reused when additional pages are required.

The freelist is organized as a linked list of freelist trunk pages with each trunk pages containing page numbers for zero or more freelist leaf pages.

A freelist trunk page consists of an array of 4-byte big-endian integers. The size of the array is as many integers as will fit in the usable space of a page. The minimum usable space is 480 bytes so the array will always be at least 120 entries in length. The first integer in the array is the page number of the next freelist trunk page in the list or zero if this is the last freelist trunk page. The second integer in the array is the number of leaf page pointers to follow. Call the second integer L. If L is greater than zero then integers with array indexes between 2 and L+1 inclusive contain page numbers for freelist leaf pages.

Freelist leaf pages contain no information. SQLite avoids reading or writing freelist leaf pages in order to reduce disk I/O.

A bug in SQLite versions prior to 3.6.0 caused the database to be reported as corrupt if any of the last 6 entries in the freelist trunk page array contained non-zero values. Newer versions of SQLite do not have this problem. However, newer versions of SQLite still avoid using the last six entries in the freelist trunk page array in order that database files created by newer versions of SQLite can be read by older versions of SQLite.

The number of freelist pages is stored as a 4-byte big-endian integer in the database header at an offset of 36 from the beginning of the file. The database header also stores the page number of the first freelist trunk page as a 4-byte big-endian integer at an offset of 32 from the beginning of the file.

1.5 B-tree Pages

A b-tree page is either an interior page or a leaf page. A leaf page contains keys and in the case of a table b-tree each key has associated content. An interior page contains K keys without content but with K+1 pointers to child b-tree pages. A "pointer" in an interior b-tree page is just the 31-bit integer page number of the child page.

Define the depth of a leaf b-tree to be 1 and the depth of any interior b-tree to be one more than the maximum depth of any of its children. In a well-formed database, all children of any one interior b-tree have the same depth.

In an interior b-tree page, the pointers and keys logically alternate with a pointer on both ends. (The previous sentence is to be understood conceptually - the actual layout of the keys and pointers within the page is more complicated and will be described in the sequel.) All keys within the same page are unique and are logically organized in ascending order from left to right. (Again, this ordering is logical, not physical. The actual location of keys within the page is arbitrary.) For any key X, pointers to the left of a X refer to b-tree pages on which all keys are less than or equal to X. Pointers to the right of X refer to pages where all keys are greater than X.

Within an interior b-tree page, each key and the pointer to its immediate left are combined into a structure called a "cell". The right-most pointer is held separately. A leaf b-tree page has no pointers, but it still uses the cell structure to hold keys for index b-trees or keys and content for table b-trees.

Every b-tree page has at most one parent b-tree page. A b-tree page without a parent is called a root page. A root b-tree page together with the closure of its children form a complete b-tree. It is possible (and in fact rather common) to have a complete b-tree that consists of a single page that is both a leaf and the root. Because there are pointers from parents to children, every page of a complete b-tree can be located if only the root page is known. Hence, b-trees are identified by their root page number.

A b-tree page is either a table b-tree page or an index b-tree page. All pages within each complete b-tree are of the same type: either table or index. There is a one-to-one mapping from table b-trees in the database file to (non-virtual) tables in the database schema, including system tables such as sqlite_master. There is one-to-one mapping between index b-trees in the database file and indices in the schema, including implied indices created by uniqueness constraints. The b-tree corresponding to the sqlite_master table always has its root page on a page number of 1. The sqlite_master table contains the root page number for every other table and index in the database file.

Each entry in a table b-tree consists of a 64-bit signed integer key and up to 2147483647 bytes of arbitrary data. Interior table b-trees hold only keys and pointers to children. All data is contained in the table b-tree leaves.

Each entry in an index b-tree consists of an arbitrary key of up to 2147483647 bytes in length and no data.

Define the "payload" of a cell to be the arbitrary length section of the cell. For an index b-tree, the key is always arbitrary in length and hence the payload is the key. There are no arbitrary length elements in the cells of interior table b-tree pages and so those cells have no payload. Table b-tree leaf pages contain arbitrary length content and so for cells on those pages the payload is the content.

When the size of payload for a cell exceeds a certain threshold (to be defined later) then only the first few bytes of the payload are stored on the b-tree page and the balance is stored in a linked list of content overflow pages.

A b-tree page is divided into regions in the following order:

  1. The 100-byte database file header (found on page 1 only)
  2. The 8 or 12 byte b-tree page header
  3. The cell pointer array
  4. Unallocated space
  5. The cell content area
  6. The reserved region.

The 100-byte database file header is found only on page 1, which is always a table b-tree page. All other b-tree pages in the database file omit this 100-byte header.

The reserved region is an area of unused space at the end of every page (except the locking page) that extensions can use to hold per-page information. The size of the reserved region is determined by the one-byte unsigned integer found at an offset of 20 into the database file header. The size of the reserved region is usually zero.

The b-tree page header is 8 bytes in size for leaf pages and 12 bytes for interior pages. All multibyte values in the page header are big-endian. The b-tree page header is composed of the following fields:

B-tree Page Header Format
Offset | Size | Description
0 | 1 | A flag indicating the b-tree page type A value of 2 means the page is an interior index b-tree page. A value of 5 means the page is an interior table b-tree page. A value of 10 means the page is a leaf index b-tree page. A value of 13 means the page is a leaf table b-tree page. Any other value for the b-tree page type is an error.
1 | 2 | Byte offset into the page of the first freeblock
3 | 2 | Number of cells on this page
5 | 2 | Offset to the first byte of the cell content area. A zero value is used to represent an offset of 65536, which occurs on an empty root page when using a 65536-byte page size.
7 | 1 | Number of fragmented free bytes within the cell content area
8 | 4 | The right-most pointer (interior b-tree pages only)

The cell pointer array of a b-tree page immediately follows the b-tree page header. Let K be the number of cells on the btree. The cell pointer array consists of K 2-byte integer offsets to the cell contents. The cell pointers are arranged in key order with left-most cell (the cell with the smallest key) first and the right-most cell (the cell with the largest key) last.

Cell content is stored in the cell content region of the b-tree page. SQLite strives to place cells as far toward the end of the b-tree page as it can, in order to leave space for future growth of the cell pointer array. The area in between the last cell pointer array entry and the beginning of the first cell is the unallocated region.

If a page contains no cells (which is only possible for a root page of a table that contains no rows) then the offset to the cell content area will equal the page size minus the bytes of reserved space. If the database uses a 65536-byte page size and the reserved space is zero (the usual value for reserved space) then the cell content offset of an empty page wants to be 65536. However, that integer is too large to be stored in a 2-byte unsigned integer, so a value of 0 is used in its place.

A freeblock is a structure used to identify unallocated space within a b-tree page. Freeblocks are organized as a chain. The first 2 bytes of a freeblock are a big-endian integer which is the offset in the b-tree page of the next freeblock in the chain, or zero if the freeblock is the last on the chain. The third and fourth bytes of each freeblock form a big-endian integer which is the size of the freeblock in bytes, including the 4-byte header. Freeblocks are always connected in order of increasing offset. The second field of the b-tree page header is the offset of the first freeblock, or zero if there are no freeblocks on the page. In a well-formed b-tree page, there will always be at least one cell before the first freeblock.

A freeblock requires at least 4 bytes of space. If there is an isolated group of 1, 2, or 3 unused bytes within the cell content area, those bytes comprise a fragment. The total number of bytes in all fragments is stored in the fifth field of the b-tree page header. In a well-formed b-tree page, the total number of bytes in fragments may not exceed 60.

The total amount of free space on a b-tree page consists of the size of the unallocated region plus the total size of all freeblocks plus the number of fragmented free bytes. SQLite may from time to time reorganize a b-tree page so that there are no freeblocks or fragment bytes, all unused bytes are contained in the unallocated space region, and all cells are packed tightly at the end of the page. This is called "defragmenting" the b-tree page.

A variable-length integer or "varint" is a static Huffman encoding of 64-bit twos-complement integers that uses less space for small positive values. A varint is between 1 and 9 bytes in length. The varint consists of either zero or more byte which have the high-order bit set followed by a single byte with the high-order bit clear, or nine bytes, whichever is shorter. The lower seven bits of each of the first eight bytes and all 8 bits of the ninth byte are used to reconstruct the 64-bit twos-complement integer. Varints are big-endian: bits taken from the earlier byte of the varint are the more significant and bits taken from the later bytes.

The format of a cell depends on which kind of b-tree page the cell appears on. The following table shows the elements of a cell, in order of appearance, for the various b-tree page types.

Table B-Tree Leaf Cell:

  • A varint which is the total number of bytes of payload, including any overflow
  • A varint which is the integer key, a.k.a. "rowid"
  • The initial portion of the payload that does not spill to overflow pages.
  • A 4-byte big-endian integer page number for the first page of the overflow page list - omitted if all payload fits on the b-tree page.

Table B-Tree Interior Cell:

  • A 4-byte big-ending page number which is the left child pointer.
  • A varint which is the integer key

Index B-Tree Leaf Cell:

  • A varint which is the total number of bytes of key payload, including any overflow
  • The initial portion of the payload that does not spill to overflow pages.
  • A 4-byte big-endian integer page number for the first page of the overflow page list - omitted if all payload fits on the b-tree page.

Index B-Tree Interior Cell:

  • A 4-byte big-ending page number which is the left child pointer.
  • A varint which is the total number of bytes of key payload, including any overflow
  • The initial portion of the payload that does not spill to overflow pages.
  • A 4-byte big-endian integer page number for the first page of the overflow page list - omitted if all payload fits on the b-tree page.

The information above can be recast into a table format as follows:

B-tree Cell Format
Datatype | Appears in... |  |  |  | Description
 | Table Leaf | Table Interior | Index Leaf | Index Interior
4-byte integer |  | ✔ |  | ✔ | Page number of left child
varint | ✔ |  | ✔ | ✔ | Number of bytes of payload
varint | ✔ | ✔ |  |  | Rowid
byte array | ✔ |  | ✔ | ✔ | Payload
4-byte integer | ✔ |  | ✔ | ✔ | Page number of first overflow page

The amount of payload that spills onto overflow pages also depends on the page type. For the following computations, let U be the usable size of a database page, the total page size less the reserved space at the end of each page. And let P be the payload size.

Table B-Tree Leaf Cell:

If the payload size P is less than or equal to U-35 then the entire payload is stored on the b-tree leaf page. Let M be ((U-12)*32/255)-23. If P is greater than U-35 then the number of byte stored on the b-tree leaf page is the smaller of M+((P-M)%(U-4)) and U-35. Note that number of bytes stored on the leaf page is never less than M.

Table B-Tree Interior Cell:

Interior pages of table b-trees have no payload and so there is never any payload to spill.

Index B-Tree Leaf Or Interior Cell:

Let X be ((U-12)*64/255)-23). If the payload size P is less than or equal to X then the entire payload is stored on the b-tree page. Let M be ((U-12)*32/255)-23. If P is greater than X then the number of byte stored on the b-tree page is the smaller of M+((P-M)%(U-4)) and X. Note that number of bytes stored on the index page is never less than M.

The overflow thresholds are designed to give a minimum fanout of 4 for index b-trees and to make sure enough of the payload is on the b-tree page that the record header can usually be accessed without consulting an overflow page. In hindsight, the designers of the SQLite b-tree logic realize that these thresholds could have been made much simpler. However, the computations cannot be changed without resulting in an incompatible file format. And the current computations work well, even if they are a little complex.

1.6 Cell Payload Overflow Pages

When the payload of a b-tree cell is too large for the b-tree page, the surplus is spilled onto overflow pages. Overflow pages form a linked list. The first four bytes of each overflow page are a big-endian integer which is the page number of the next page in the chain, or zero for the final page in the chain. The fifth byte through the last usable byte are used to hold overflow content.

1.7 Pointer Map or Ptrmap Pages

Pointer map or ptrmap pages are extra pages inserted into the database to make the operation of auto_vacuum and incremental_vacuum modes more efficient. Other page types in the database typically have pointers from parent to child. For example, an interior b-tree page contains pointers to its child b-tree pages and an overflow chain has a pointer from earlier to later links in the chain. A ptrmap page contains linkage information going in the opposite direction, from child to parent.

Ptrmap pages must exist in any database file which has a non-zero largest root b-tree page value at offset 52 in the database header. If the largest root b-tree page value is zero, then the database must not contain ptrmap pages.

In a database with ptrmap pages, the first ptrmap page is page 2. A ptrmap page consists of an array of 5-byte entries. Let J be the number of 5-byte entries that will fit in the usable space of a page. (In other words, J=U/5.) The first ptrmap page will contain back pointer information for pages 3 through J+2, inclusive. The second pointer map page will be on page J+3 and that ptrmap page will provide back pointer information for pages J+4 through 2*J+3 inclusive. And so forth for the entire database file.

In a database that uses ptrmap pages, all pages at locations identified by the computation in the previous paragraph must be ptrmap page and no other page may be a ptrmap page. Except, if the byte-lock page happens to fall on the same page number as a ptrmap page, then the ptrmap is moved to the following page for that one case.

Each 5-byte entry on a ptrmap page provides back-link information about one of pages that immediately follow the pointer map. If page B is a ptrmap page then back-link information about page B+1 is provided by the first entry on the pointer map. Information about page B+2 is provided by the second entry. And so forth.

Each 5-byte ptrmap entry consists of one byte of "page type" information followed by a 4-byte big-endian page number. Five page types are recognized:

  1. A b-tree root page. The page number should be zero.
  2. A freelist page. The page number should be zero.
  3. The first page of a cell payload overflow chain. The page number is the b-tree page that contains the cell whose content has overflowed.
  4. A page in an overflow chain other than the first page. The page number is the prior page of the overflow chain.
  5. A non-root b-tree page. The page number is the parent b-tree page.

In any database file that contains ptrmap pages, all b-tree root pages must come before any non-root b-tree page, cell payload overflow page, or freelist page. This restriction ensures that a root page will never be moved during an auto-vacuum or incremental-vacuum. The auto-vacuum logic does not know how to update the root_page field of the sqlite_master table and so it is necessary to prevent root pages from being moved during an auto-vacuum in order to preserve the integrity of the sqlite_master table. Root pages are moved to the beginning of the database file by the CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX operations.

2.0 Schema Layer

The foregoing text describes low-level aspects of the SQLite file format. The b-tree mechanism provides a powerful and efficient means of accessing a large data set. This section will describe how the low-level b-tree layer is used to implement higher-level SQL capabilities.

2.1 Record Format

The content of a table b-tree leaf page and the key of any index b-tree page was characterized above as an arbitrary sequence of bytes. The prior discussion mentioned one key being less than another, but did not define what "less than" meant. The current section will address these omissions.

Payload, either table content or index keys, is always in the "record format". The record format defines a sequence of values corresponding to columns in a table or index. The record format specifies the number of columns, the datatype of each column, and the content of each column.

The record format makes extensive use of the variable-length integer or varint representation of 64-bit signed integers defined above.

A record contains a header and a body, in that order. The header begins with a single varint which determines the total number of bytes in the header. The varint value is the size of the header in bytes including the size varint itself. Following the size varint are one or more additional varints, one per column. These additional varints are called "serial type" numbers and determine the datatype of each column, according to the following chart:

Serial Type Codes Of The Record Format
Serial Type | Content Size | Meaning
0 | 0 | NULL
1 | 1 | 8-bit twos-complement integer
2 | 2 | Big-endian 16-bit twos-complement integer
3 | 3 | Big-endian 24-bit twos-complement integer
4 | 4 | Big-endian 32-bit twos-complement integer
5 | 6 | Big-endian 48-bit twos-complement integer
6 | 8 | Big-endian 64-bit twos-complement integer
7 | 8 | Big-endian IEEE 754-2008 64-bit floating point number
8 | 0 | Integer constant 0. Only available for schema format 4 and higher.
9 | 0 | Integer constant 1. Only available for schema format 4 and higher.
10,11 |  | Not used. Reserved for expansion.
N≥12 and even | (N-12)/2 | A BLOB that is (N-12)/2 bytes in length
N≥13 and odd | (N-13)/2 | A string in the database encoding and (N-13)/2 bytes in length. The nul terminator is omitted.

Note that because of the way varints are defined, the header size varint and serial type varints will usually consist of a single byte. The serial type varints for large strings and BLOBs might extend to two or three byte varints, but that is the exception rather than the rule. The varint format is very efficient at coding the record header.

The values for each column in the record immediately follow the header. Note that for serial types 0, 8, 9, 12, and 13, the value is zero bytes in length. If all columns are of these types then the body section of the record is empty.

2.2 Record Sort Order

The order of keys in an index b-tree is determined by the sort order of the records that the keys represent. Record comparison progresses column by column. Columns of a record are examined from left to right. The first pair of columns that are not equal determines the relative order of the two records. The sort order of individual columns is as follows:

  1. NULL values (serial type 0) sort first
  2. Numeric values (serial types 1 through 9) sort next and in numeric order
  3. Text values (even serial types 12 and larger) sort next in the order determined by the columns collating function
  4. BLOB values (odd serial types 13 and larger) sort last in order determined by memcmp().

A collating function for each column is necessary in order to compute the order of text fields. SQLite defines three built-in collating functions:

BINARY | Strings are compared byte by byte using the memcmp() function from the standard C library.
NOCASE | Like BINARY except that uppercase ASCII characters ('A' through 'Z') are folded into their lowercase equivalents prior to running the comparison. Note that only ASCII characters are case-folded. NOCASE does not implement a general purpose unicode caseless comparison.
RTRIM | Like BINARY except that spaces at the end of the string are elided prior to comparison.

Additional application-specific collating functions can be added to SQLite using the sqlite3_create_collation() interface.

The default collating function for all strings is BINARY. Alternative collating functions for table columns can be specified in the CREATE TABLE statement using the COLLATE clause on the column definition. When a column is indexed, the same collating function specified in the CREATE TABLE statement is used for the column in the index, by default, though this can be overridden using a COLLATE clause in the CREATE INDEX statement.

2.3 Representation Of SQL Tables

Each ordinary SQL table in the database schema is represented on disk by a table b-tree. Each entry in the table b-tree corresponds to a row of the SQL table. The rowid of the SQL table is the 64-bit signed integer key for each entry in the table b-tree.

The content of each SQL table row is stored in the database file by first combining the values in the various columns into a byte array in the record format, then storing that byte array as the payload in an entry in the table b-tree. The order of values in the record is the same as the order of columns in the SQL table definition. When an SQL table that includes an INTEGER PRIMARY KEY column (which aliases the rowid) then that column appears in the record as a NULL value. SQLite will always use the table b-tree key rather than the NULL value when referencing the INTEGER PRIMARY KEY column.

If the affinity of a column is REAL and that column contains a value that can be converted to an integer without loss of information (if the value contains no fractional part and is not too large to be represented as an integer) then the column may be stored in the record as an integer. SQLite will convert the value back to floating point when extracting it from the record.

2.4 Representation Of SQL Indices

Each SQL index, whether explicitly declared via a CREATE INDEX statement or implied by a UNIQUE constraint, corresponds to an index b-tree in the database file. There is one entry in index b-tree for each row in the corresponding table. The key to an index b-tree is a record composed of the columns that are being indexed followed by the rowid of the table row. Because every row in a table has a unique rowid and all keys in an index contain the rowid, all keys in an index are unique.

There is a one-to-one mapping between rows in a table and entries in each index associated with that table. Corresponding rows int the index and table b-trees share the same rowid value, and contain the same value for all indexed columns.

2.5 Storage Of The SQL Database Schema

Page 1 of a database file is the root page of a table b-tree that holds a special table named "sqlite_master" (or "sqlite_temp_master" in the case of a TEMP database) which stores the complete database schema. The structure of the sqlite_master table is as if it had been created using the following SQL:

CREATE TABLE sqlite_master(
  type text,
  name text,
  tbl_name text,
  rootpage integer,
  sql text
);

The sqlite_master table contains a row for each table, index, view, and trigger in the database schema, except there is no entry for the sqlite_master table itself.

The sqlite_master.type column will be one of the following text strings: 'table', 'index', 'view', or 'trigger' according to the type of object defined. The 'table' string is used for both ordinary and virtual tables.

The sqlite_master.name column will hold the name of the object. For indices that are automatically created by UNIQUE or PRIMARY KEY constraints, the name is "sqlite_autoindex_TABLE_N" where TABLE is replaced by the name of the table that contains the constraint and N is an integer beginning with 1 and increasing by one with each constraint seen.

The sqlite_master.tbl_name column holds the name of a table or view that the object is associated with. For a table or view, the tbl_name column is a copy of the name column. For an index, the tbl_name is the name of the table that is indexed. For a trigger, the tbl_name column stores the name of the table or view that causes the trigger to fire.

The sqlite_master.rootpage column stores the page number of the root b-tree page for tables and indices. For rows that define views, triggers, and virtual tables, the rootpage column is 0 or NULL.

The sqlite_master.sql column stores SQL text that describes the object. This SQL text is a CREATE TABLE, CREATE VIRTUAL TABLE, CREATE INDEX, CREATE VIEW, or CREATE TRIGGER statement that if evaluated against the database file when it is the main database of a database connection would recreated the object.) The text is usually a copy of the original statement used to create the object but with normalizations applied so that the text conforms to the following rules:

  • The CREATE, TABLE, VIEW, TRIGGER, and INDEX keywords at the beginning of the statement are converted to all upper case letters.
  • The TEMP or TEMPORARY keyword is removed if it occurs after the initial CREATE keyword.
  • Any database name qualifier that occurs prior to the name of the object being created is removed.
  • Leading spaces are removed.
  • All spaces following the first two keywords are converted into a single space.

The text in the sqlite_master.sql column is a copy of the original CREATE statement text that created the object, except normalized as described above and as modified by subsequent ALTER TABLE statements.

For indices that are automatically created by UNIQUE or PRIMARY KEY constraints, the sqlite_master.sql field is NULL.

3.0 The Rollback Journal

The rollback journal is a file associated with each SQLite database file that hold information used to restore the database file to its initial state during the course of a transaction. The rollback journal file is always located in the same directory as the database file and has the same name as the database file but with the string "-journal" appended. There can only be a single rollback journal associated with a give database and hence there can only be one write transaction open against a single database at one time.

If a transaction is aborted due to an application crash, an operating system crash, or a hardware power failure or crash, then the database may be left in an inconsistent state. The next time SQLite attempts to open the database file, the presence of the rollback journal file will be detected and the journal will be automatically played back to restore the database to its state at the start of the incomplete transaction.

A rollback journal is only considered to be valid if it exists and contains a valid header. Hence a transaction can be committed in one of three ways:

  1. The rollback journal file can be deleted,
  2. The rollback journal file can be truncated to zero length, or
  3. The header of the rollback journal can be overwritten with invalid header text (for example, all zeros).
These three ways of committing a transaction correspond to the DELETE, TRUNCATE, and PERSIST settings, respectively, of the journal_mode pragma.

A valid rollback journal begins with a header in the following format:

Rollback Journal Header Format
Offset | Size | Description
0 | 8 | Header string: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7
8 | 4 | The "Page Count" - The number of pages in the next segment of the journal, or -1 to mean all content to the end of the file
12 | 4 | A random nonce for the checksum
16 | 4 | Initial size of the database in pages
20 | 4 | Size of a disk sector assumed by the process that wrote this journal.
24 | 4 | Size of pages in this journal.

A rollback journal header is padded with zeros out to the size of a single sector (as defined by the sector size integer at offset 20). The header is in a sector by itself so that if a power loss occurs while writing the sector, information that follows the header will be (hopefully) undamaged.

After the header and zero padding are zero or more page records. Each page record stores a copy of the content of a page from the database file before it was changed. The same page may not appear more than once within a single rollback journal. To rollback an incomplete transaction, a process has merely to read the rollback journal from beginning to end and write pages found in the journal back into the database file at the appropriate location.

Let the database page size (the value of the integer at offset 24 in the journal header) be N. Then the format of a page record is as follows:

Rollback Journal Page Record Format
Offset | Size | Description
0 | 4 | The page number in the database file
4 | N | Original content of the page prior to the start of the transaction
N+4 | 4 | Checksum

The checksum is an unsigned 32-bit integer computed as follows:

  1. Initialize the checksum to the checksum nonce value found in the journal header at offset 12.
  2. Initialize index X to be N-200 (where N is the size of a database page in bytes.
  3. Interpret the four bytes at offset X into the page as a 4-byte big-endian unsigned integer. Add the value of that integer to the checksum.
  4. Subtrace 200 from X.
  5. If X is greater than or equal to zero, go back to step 3.

The checksum value is used to guard against incomplete writes of a journal page record following a power failure. A different random nonce is used each time a transaction is started in order to minimize the risk that unwritten sectors might by chance contain data from the same page that was a part of prior journals. By changing the nonce for each transaction, stale data on disk will still generate an incorrect checksum and be detected with high probability. The checksum only uses a sparse sample of 32-bit words from the data record for performance reasons - design studies during the planning phases of SQLite 3.0.0 showed a significant performance hit in checksumming the entire page.

Let the page count value at offset 8 in the journal header be M. If M is greater than zero then after M page records the journal file may be zero padded out to the next multiple of the sector size and another journal header may be inserted. All journal headers within the same journal must contain the same database page size and sector size.

If M is -1 in the initial journal header, then the number of page records that follow is computed by computing how many page records will fit in the available space of the remainder of the journal file.

4.0 The Write-Ahead Log

Beginning with version 3.7.0, SQLite supports a new transaction control mechanism called "write-ahead log" or "WAL". When a database is in WAL mode, all connections to that database must use the WAL. A particular database will use either a rollback journal or a WAL, but not both at the same time. The WAL is always located in the same directory as the database file and has the same name as the database file but with the string "-wal" appended.

4.1 WAL File Format

A WAL file consists of a header followed by zero or more "frames". Each frame records the revised content of a single page from the database file. All changes to the database are recorded by writing frames into the WAL. Transactions commit when a frame is written that contains a commit marker. A single WAL can and usually does record multiple transactions. Periodically, the content of the WAL is transferred back into the database file in an operation called a "checkpoint".

A single WAL file can be reused multiple times. In other words, the WAL can fill up with frames and then be checkpointed and then new frames can overwrite the old ones. A WAL always grows from beginning toward the end. Checksums and counters attached to each frame are used to determine which frames within the WAL are valid and which are leftovers from prior checkpoints.

The WAL header is 32 bytes in size and consists of the following eight big-endian 32-bit unsigned integer values:

WAL Header Format
Offset | Size | Description
0 | 4 | Magic number. 0x377f0682 or 0x377f0683
4 | 4 | File format version. Currently 3007000.
8 | 4 | Database page size. Example: 1024
12 | 4 | Checkpoint sequence number
16 | 4 | Salt-1: random integer incremented with each checkpoint
20 | 4 | Salt-2: a different random number for each checkpoint
24 | 4 | Checksum-1: First part of a checksum on the first 24 bytes of header
28 | 4 | Checksum-2: Second part of the checksum on the first 24 bytes of header

Immediately following the wal-header are zero or more frames. Each frame consists of a 24-byte frame-header followed by a page-size bytes of page data. The frame-header is six big-endian 32-bit unsigned integer values, as follows:

WAL Frame Header Format
Offset | Size | Description
0 | 4 | Page number
4 | 4 | For commit records, the size of the database file in pages after the commit. For all other records, zero.
8 | 4 | Salt-1 copied from the WAL header
12 | 4 | Salt-2 copied from the WAL header
16 | 4 | Checksum-1: Cumulative checksum up through and including this page
20 | 4 | Checksum-2: Second half of the cumulative checksum.

A frame is considered valid if and only if the following conditions are true:

  1. The salt-1 and salt-2 values in the frame-header match salt values in the wal-header

  2. The checksum values in the final 8 bytes of the frame-header exactly match the checksum computed consecutively on the WAL header and the first 8 bytes and the content of all frames up to and including the current frame.

4.2 Checksum Algorithm

The checksum is computed by interpreting the input as an even number of unsigned 32-bit integers: x(0) through x(N). The 32-bit integers are big-endian if the magic number in the first 4 bytes of the WAL header is 0x377f0683 and the integers are little-endian the magic number is 0x377f0682. The checksum values are always stored in the frame header in a big-endian format regardless of which byte order is used to compute the checksum.

The checksum algorithm only works for content which is a multiple of 8 bytes in length. In other words, if the inputs are x(0) through x(N) then N must be odd. The checksum algorithm is as follows:

s0 = s1 = 0
for i from 0 to n-1 step 2:
   s0 += x(i) + s1;
   s1 += x(i+1) + s0;
endfor
# result in s0 and s1

The outputs s0 and s1 are both weighted checksums using Fibonacci weights in reverse order. (The largest Fibonacci weight occurs on the first element of the sequence being summed.) The s1 value spans all 32-bit integer terms of the sequence whereas s0 omits the final term.

4.3 Checkpoint Algorithm

On a checkpoint, the WAL is first flushed to persistent storage using the xSync method of the VFS. Then valid content of the WAL is transferred into the database file. Finally, the database is flushed to persistent storage using another xSync method call. The xSync operations serve as write barriers - all writes launched before the xSync must complete before any write that launches after the xSync begins.

After each checkpoint, the WAL header salt-1 value is incremented and the salt-2 value is randomized. This prevents old and new frames in the WAL from being considered valid at the same time and being checkpointing together following a crash.

4.4 Reader Algorithm

To read a page from the database (call it page number P), a reader first checks the WAL to see if it contains page P. If so, then the last valid instance of page P that is followed by a commit frame or is a commit frame itself becomes the value read. If the WAL contains no copies of page P that are valid and which are a commit frame or are followed by a commit frame, then page P is read from the database file.

To start a read transaction, the reader records the index of the last valid frame in the WAL. The reader uses this recorded "mxFrame" value for all subsequent read operations. New transactions can be appended to the WAL, but as long as the reader uses its original mxFrame value and ignores subsequently appended content, the reader will see a consistent snapshot of the database from a single point in time. This technique allows multiple concurrent readers to view different versions of the database content simultaneously.

The reader algorithm in the previous paragraphs works correctly, but because frames for page P can appear anywhere within the WAL, the reader has to scan the entire WAL looking for page P frames. If the WAL is large (multiple megabytes is typical) that scan can be slow, and read performance suffers. To overcome this problem, a separate data structure called the wal-index is maintained to expedite the search for frames of a particular page.

4.5 WAL-Index Format

Conceptually, the wal-index is shared memory, though the current VFS implementations use a mmapped file for the wal-index. The mmapped file is in the same directory as the database and has the same name as the database with a "-shm" suffix appended. Because the wal-index is shared memory, SQLite does not support journal_mode=WAL on a network filesystem when clients are on different machines. All users of the database must be able to share the same memory.

The purpose of the wal-index is to answer this question quickly:

Given a page number P and a maximum WAL frame index M, return the largest WAL frame index for page P that does not exceed M, or return NULL if there are no frames for page P that do not exceed M.

The M value in the previous paragraph is the "mxFrame" value defined in section 4.4 that is read at the start of a transaction and which defines the maximum frame from the WAL that the reader will use.

The wal-index is transient. After a crash, the wal-index is reconstructed from the original WAL file. The VFS is required to either truncate or zero the header of the wal-index when the last connection to it closes. Because the wal-index is transient, it can use an architecture-specific format; it does not have to be cross-platform. Hence, unlike the database and WAL file formats which store all values as big endian, the wal-index stores multi-byte values in the native byte order of the host computer.

This document is concerned with the persistent state of the database file, and since the wal-index is a transient structure, no further information about the format of the wal-index will be provided here. Complete details on the format of the wal-index are contained within comments in SQLite source code.


No Title

Choose any three.
About Sitemap Documentation Download License News Support
SQLite File IO Specification
Table Of Contents
Javascript is required for some features of this document, including table of contents, figure numbering and internal references (section numbers and hyper-links.

Overview

SQLite stores an entire database within a single file, the format of which is described in the SQLite File Database File Format document ff_sqlitert_requirements. Each database file is stored within a file system, presumably provided by the host operating system. Instead of interfacing with the operating system directly, the host application is required to supply an adaptor component that implements the SQLite Virtual File System interface (described in capi_sqlitert_requirements). The adaptor component is responsible for translating the calls made by SQLite to the VFS interface into calls to the file-system interface provided by the operating system. This arrangement is depicted in figure figure_vfs_role.

Figure - Virtual File System (VFS) Adaptor

Although it would be easy to design a system that uses the VFS interface to read and update the content of a database file stored within a file-system, there are several complicated issues that need to be addressed by such a system:

  1. SQLite is required to implement atomic and durable transactions (the 'A' and 'D' from the ACID acronym), even if an application, operating system or power failure occurs midway through or shortly after updating a database file.

    To implement atomic transactions in the face of potential application, operating system or power failures, database writers write a copy of those portions of the database file that they are going to modify into a second file, the journal file, before writing to the database file. If a failure does occur while modifying the database file, SQLite can reconstruct the original database (before the modifications were attempted) based on the contents of the journal file.

  2. SQLite is required to implement isolated transactions (the 'I' from the ACID acronym).

    This is done by using the file locking facilities provided by the VFS adaptor to serialize writers (write transactions) and preventing readers (read transactions) from accessing database files while writers are midway through updating them.

  3. For performance reasons, it is advantageous to minimize the quantity of data read and written to and from the file-system.

    As one might expect, the amount of data read from the database file is minimized by caching portions of the database file in main memory. Additionally, multiple updates to the database file that are part of the same write transaction may be cached in main memory and written to the file together, allowing for more efficient IO patterns and eliminating the redundant write operations that could take place if part of the database file is modified more than once within a single write transaction.

System requirement references for the above points.

This document describes in detail the way that SQLite uses the API provided by the VFS adaptor component to solve the problems and implement the strategies enumerated above. It also specifies the assumptions made about the properties of the system that the VFS adaptor provides access to. For example, specific assumptions about the extent of data corruption that may occur if a power failure occurs while a database file is being updated are presented in section fs_characteristics.

This document does not specify the details of the interface that must be implemented by the VFS adaptor component, that is left to capi_sqlitert_requirements.

Relationship to Other Documents

Related to C-API requirements:

  1. Opening a connection.
  2. Closing a connection.

Related to SQL requirements:

  3. Opening a read-only transaction.
  4. Terminating a read-only transaction.
  5. Opening a read-write transaction.
  6. Committing a read-write transaction.
  7. Rolling back a read-write transaction.
  8. Opening a statement transaction.
  9. Committing a statement transaction.
  10. Rolling back a statement transaction.
  11. Committing a multi-file transaction.

Related to file-format requirements:

  12. Pinning (reading) a database page.
  13. Unpinning a database page.
  14. Modifying the contents of a database page.
  15. Appending a new page to the database file.
  16. Truncating a page from the end of the database file.

Document Structure

Section vfs_assumptions of this document describes the various assumptions made about the system to which the VFS adaptor component provides access. The basic capabilities and functions required from the VFS implementation are presented along with the description of the VFS interface in capi_sqlitert_requirements. Section vfs_assumptions complements this by describing in more detail the assumptions made about VFS implementations on which the algorithms presented in this document depend. Some of these assumptions relate to performance issues, but most concern the expected state of the file-system following a failure that occurs midway through modifying a database file.

Section database_connections introduces the concept of a database connection, a combination of a file-handle and in-memory cache used to access a database file. It also describes the VFS operations required when a new database connection is created (opened), and when one is destroyed (closed).

Section reading_data describes the steps required to open a read transaction and read data from a database file.

Section writing_data describes the steps required to open a write transaction and write data to a database file.

Section rollback describes the way in which aborted write transactions may be rolled back (reverted), either as a result of an explicit user directive or because an application, operating system or power failure occurred while SQLite was midway through updating a database file.

Section page_cache_algorithms describes some of the algorithms used to determine exactly which portions of the database file are cached by a page cache, and the effect that they have on the quantity and nature of the required VFS operations. It may at first seem odd to include the page cache, which is primarily an implementation detail, in this document. However, it is necessary to acknowledge and describe the page cache in order to provide a more complete explanation of the nature and quantity of IO performed by SQLite.

Glossary

After this document is ready, make the vocabulary consistent and then add a glossary here.

VFS Adaptor Related Assumptions

This section documents those assumptions made about the system that the VFS adaptor provides access to. The assumptions noted in section fs_characteristics are particularly important. If these assumptions are not true, then a power or operating system failure may cause SQLite databases to become corrupted.

Performance Related Assumptions

SQLite uses the assumptions in this section to try to speed up reading from and writing to the database file.

It is assumed that writing a series of sequential blocks of data to a file in order is faster than writing the same blocks in an arbitrary order.

System Failure Related Assumptions

In the event of an operating system or power failure, the various combinations of file-system software and storage hardware available provide varying levels of guarantee as to the integrity of the data written to the file system just before or during the failure. The exact combination of IO operations that SQLite is required to perform in order to safely modify a database file depend on the exact characteristics of the target platform.

This section describes the assumptions that SQLite makes about the content of a file-system following a power or system failure. In other words, it describes the extent of file and file-system corruption that such an event may cause.

SQLite queries an implementation for file-system characteristics using the xDeviceCharacteristics() and xSectorSize() methods of the database file file-handle. These two methods are only ever called on file-handles open on database files. They are not called for journal files, master-journal files or temporary database files.

The file-system sector size value determined by calling the xSectorSize() method is a power of 2 value between 512 and 32768, inclusive reference to exactly how this is determined. SQLite assumes that the underlying storage device stores data in blocks of sector-size bytes each, sectors. It is also assumed that each aligned block of sector-size bytes of each file is stored in a single device sector. If the file is not an exact multiple of sector-size bytes in size, then the final device sector is partially empty.

Normally, SQLite assumes that if a power failure occurs while updating any portion of a sector then the contents of the entire device sector is suspect following recovery. After writing to any part of a sector within a file, it is assumed that the modified sector contents are held in a volatile buffer somewhere within the system (main memory, disk cache etc.). SQLite does not assume that the updated data has reached the persistent storage media, until after it has successfully synced the corresponding file by invoking the VFS xSync() method. Syncing a file causes all modifications to the file up until that point to be committed to persistent storage.

Based on the above, SQLite is designed around a model of the file-system whereby any sector of a file written to is considered to be in a transient state until after the file has been successfully synced. Should a power or system failure occur while a sector is in a transient state, it is impossible to predict its contents following recovery. It may be written correctly, not written at all, overwritten with random data, or any combination thereof.

For example, if the sector-size of a given file-system is 2048 bytes, and SQLite opens a file and writes a 1024 byte block of data to offset 3072 of the file, then according to the model the second sector of the file is in the transient state. If a power failure or operating system crash occurs before or during the next call to xSync() on the file handle, then following system recovery SQLite assumes that all file data between byte offsets 2048 and 4095, inclusive, is invalid. It also assumes that since the first sector of the file, containing the data from byte offset 0 to 2047 inclusive, is valid, since it was not in a transient state when the crash occurred.

Assuming that any and all sectors in the transient state may be corrupted following a power or system failure is a very pessimistic approach. Some modern systems provide more sophisticated guarantees than this. SQLite allows the VFS implementation to specify at runtime that the current platform supports zero or more of the following properties:

  • The safe-append property. If a system supports the safe-append property, it means that when a file is extended the new data is written to the persistent media before the size of the file itself is updated. This guarantees that if a failure occurs after a file has been extended, following recovery the write operations that extended the file will appear to have succeeded or not occurred at all. It is not possible for invalid or garbage data to appear in the extended region of the file.

  • The atomic-write property. A system that supports this property also specifies the size or sizes of the blocks that it is capable of writing. Valid sizes are powers of two greater than 512. If a write operation modifies a block of n bytes, where n is one of the block sizes for which atomic-write is supported, then it is impossible for an aligned write of n bytes to cause data corruption. If a failure occurs after such a write operation and before the applicable file handle is synced, then following recovery it will appear as if the write operation succeeded or did not take place at all. It is not possible that only part of the data specified by the write operation was written to persistent media, nor is it possible for any content of the sectors spanned by the write operation to be replaced with garbage data, as it is normally assumed to be.

  • The sequential-write property. A system that supports the sequential-write property guarantees that the various write operations on files within the same file-system are written to the persistent media in the same order that they are performed by the application and that each operation is concluded before the next is begun. If a system supports the sequential-write property, then the model used to determine the possible states of the file-system following a failure is different.

    If a system supports sequential-write it is assumed that syncing any file within the file system flushes all write operations on all files (not just the synced file) to the persistent media. If a failure does occur, it is not known whether or not any of the write operations performed by SQLite since the last time a file was synced. SQLite is able to assume that if the write operations of unknown status are arranged in the order that they occurred:

    1. the first n operations will have been executed successfully,
    2. the next operation puts all device sectors that it modifies into the transient state, so that following recovery each sector may be partially written, completely written, not written at all or populated with garbage data,
    3. the remaining operations will not have had any effect on the contents of the file-system.

Failure Related Assumption Details

This section describes how the assumptions presented in the parent section apply to the individual API functions and operations provided by the VFS to SQLite for the purposes of modifying the contents of the file-system.

SQLite manipulates the contents of the file-system using a combination of the following four types of operation:

  • Create file operations. SQLite may create new files within the file-system by invoking the xOpen() method of the sqlite3_io_methods object.
  • Delete file operations. SQLite may remove files from the file system by calling the xDelete() method of the sqlite3_io_methods object.
  • Truncate file operations. SQLite may truncate existing files by invoking the xTruncate() method of the sqlite3_file object.
  • Write file operations. SQLite may modify the contents and increase the size of a file by files by invoking the xWrite() method of the sqlite3_file object.

Additionally, all VFS implementations are required to provide the sync file operation, accessed via the xSync() method of the sqlite3_file object, used to flush create, write and truncate operations on a file to the persistent storage medium.

The formalized assumptions in this section refer to system failure events. In this context, this should be interpreted as any failure that causes the system to stop operating. For example a power failure or operating system crash.

SQLite does not assume that a create file operation has actually modified the file-system records within persistent storage until after the file has been successfully synced.

If a system failure occurs during or after a "create file" operation, but before the created file has been synced, then SQLite assumes that it is possible that the created file may not exist following system recovery.

Of course, it is also possible that it does exist following system recovery.

If a "create file" operation is executed by SQLite, and then the created file synced, then SQLite assumes that the file-system modifications corresponding to the "create file" operation have been committed to persistent media. It is assumed that if a system failure occurs any time after the file has been successfully synced, then the file is guaranteed to appear in the file-system following system recovery.

A delete file operation (invoked by a call to the VFS xDelete() method) is assumed to be an atomic and durable operation.

If a system failure occurs at any time after a "delete file" operation (call to the VFS xDelete() method) returns successfully, it is assumed that the file-system will not contain the deleted file following system recovery.

If a system failure occurs during a "delete file" operation, it is assumed that following system recovery the file-system will either contain the file being deleted in the state it was in before the operation was attempted, or not contain the file at all. It is assumed that it is not possible for the file to have become corrupted purely as a result of a failure occurring during a "delete file" operation.

The effects of a truncate file operation are not assumed to be made persistent until after the corresponding file has been synced.

If a system failure occurs during or after a "truncate file" operation, but before the truncated file has been synced, then SQLite assumes that the size of the truncated file is either as large or larger than the size that it was to be truncated to.

If a system failure occurs during or after a "truncate file" operation, but before the truncated file has been synced, then it is assumed that the contents of the file up to the size that the file was to be truncated to are not corrupted.

The above two assumptions may be interpreted to mean that if a system failure occurs after file truncation but before the truncated file is synced, the contents of the file following the point at which it was to be truncated may not be trusted. They may contain the original file data, or may contain garbage.

If a "truncate file" operation is executed by SQLite, and then the truncated file synced, then SQLite assumes that the file-system modifications corresponding to the "truncate file" operation have been committed to persistent media. It is assumed that if a system failure occurs any time after the file has been successfully synced, then the effects of the file truncation are guaranteed to appear in the file system following recovery.

A write file operation modifies the contents of an existing file within the file-system. It may also increase the size of the file. The effects of a write file operation are not assumed to be made persistent until after the corresponding file has been synced.

If a system failure occurs during or after a "write file" operation, but before the corresponding file has been synced, then it is assumed that the content of all sectors spanned by the write file operation are untrustworthy following system recovery. This includes regions of the sectors that were not actually modified by the write file operation.

If a system failure occurs on a system that supports the atomic-write property for blocks of size N bytes following an aligned write of N bytes to a file but before the file has been successfully synced, then is assumed following recovery that all sectors spanned by the write operation were correctly updated, or that none of the sectors were modified at all.

If a system failure occurs on a system that supports the safe-append following a write operation that appends data to the end of the file without modifying any of the existing file content but before the file has been successfully synced, then is assumed following recovery that either the data was correctly appended to the file, or that the file size remains unchanged. It is assumed that it is impossible that the file be extended but populated with incorrect data.

Following a system recovery, if a device sector is deemed to be untrustworthy as defined by A21008 and neither A21011 or A21012 apply to the range of bytes written, then no assumption can be made about the content of the sector following recovery. It is assumed that it is possible for such a sector to be written correctly, not written at all, populated with garbage data or any combination thereof.

If a system failure occurs during or after a "write file" operation that causes the file to grow, but before the corresponding file has been synced, then it is assumed that the size of the file following recovery is as large or larger than it was when it was most recently synced.

If a system supports the sequential-write property, then further assumptions may be made with respect to the state of the file-system following recovery from a system failure. Specifically, it is assumed that create, truncate, delete and write file operations are applied to the persistent representation in the same order as they are performed by SQLite. Furthermore, it is assumed that the file-system waits until one operation is safely written to the persistent media before the next is attempted, just as if the relevant file were synced following each operation.

If a system failure occurs on a system that supports the sequential-write property, then it is assumed that all operations completed before the last time any file was synced have been successfully committed to persistent media.

If a system failure occurs on a system that supports the sequential-write property, then it is assumed that the set of possible states that the file-system may be in following recovery is the same as if each of the write operations performed since the most recent time a file was synced was itself followed by a sync file operation, and that the system failure may have occurred during any of the write or sync file operations.

Database Connections

Within this document, the term database connection has a slightly different meaning from that which one might assume. The handles returned by the sqlite3_open() and sqlite3_open16() APIs (reference) are referred to as database handles. A database connection is a connection to a single database file using a single file-handle, which is held open for the lifetime of the connection. Using the SQL ATTACH syntax, multiple database connections may be accessed via a single database handle. Or, using SQLite's shared-cache mode feature, multiple database handles may access a single database connection.

Usually, a new database connection is opened whenever the user opens new database handle on a real database file (not an in-memory database) or when a database file is attached to an existing database connection using the SQL ATTACH syntax. However if the shared-cache mode feature is enabled, then the database file may be accessed through an existing database connection. For more information on shared-cache mode, refer to Reference. The various IO operations required to open a new connection are detailed in section open_new_connection of this document.

Similarly, a database connection is usually closed when the user closes a database handle that is open on a real database file or has had one or more real database files attached to it using the ATTACH mechanism, or when a real database file is detached from a database connection using the DETACH syntax. Again, the exception is if shared-cache mode is enabled. In this case, a database connection is not closed until its number of users reaches zero. The IO related steps required to close a database connection are described in section closing_database_connection.

After sections 4 and 5 are finished, come back here and see if we can add a list of state items associated with each database connection to make things easier to understand. i.e each database connection has a file handle, a set of entries in the page cache, an expected page size etc.

Opening a New Connection

This section describes the VFS operations that take place when a new database connection is created.

Opening a new database connection is a two-step process:

  1. A file-handle is opened on the database file.
  2. If step 1 was successful, an attempt is made to read the database file header from the database file using the new file-handle.

In step 2 of the procedure above, the database file is not locked before it is read from. This is the only exception to the locking rules described in section reading_data.

The reason for attempting to read the database file header is to determine the page-size used by the database file. Because it is not possible to be certain as to the page-size without holding at least a shared lock on the database file (because some other database connection might have changed it since the database file header was read), the value read from the database file header is known as the expected page size.

When a new database connection is required, SQLite shall attempt to open a file-handle on the database file. If the attempt fails, then no new database connection is created and an error returned.

When a new database connection is required, after opening the new file-handle, SQLite shall attempt to read the first 100 bytes of the database file. If the attempt fails for any other reason than that the opened file is less than 100 bytes in size, then the file-handle is closed, no new database connection is created and an error returned instead.

If the database file header is successfully read from a newly opened database file, the connections expected page-size shall be set to the value stored in the page-size field of the database header.

If the database file header cannot be read from a newly opened database file (because the file is less than 100 bytes in size), the connections expected page-size shall be set to the compile time value of the SQLITE_DEFAULT_PAGESIZE option.

Closing a Connection

This section describes the VFS operations that take place when an existing database connection is closed (destroyed).

Closing a database connection is a simple matter. The open VFS file-handle is closed and in-memory page cache related resources are released.

When a database connection is closed, SQLite shall close the associated file handle at the VFS level.

When a database connection is closed, all associated page cache entries shall be discarded.

The Page Cache

The contents of an SQLite database file are formatted as a set of fixed size pages. See ff_sqlitert_requirements for a complete description of the format used. The page size used for a particular database is stored as part of the database file header at a well-known offset within the first 100 bytes of the file. Almost all read and write operations performed by SQLite on database files are done on blocks of data page-size bytes in size.

All SQLite database connections running within a single process share a single page cache. The page cache caches data read from database files in main-memory on a per-page basis. When SQLite requires data from a database file to satisfy a database query, it checks the page cache for usable cached versions of the required database pages before loading it from the database file. If no usable cache entry can be found and the database page data is loaded from the database file, it is cached in the page cache in case the same data is needed again later. Because reading from the database file is assumed to be an order of magnitude faster than reading from main-memory, caching database page content in the page cache to minimize the number of read operations performed on the database file is a significant performance enhancement.

The page cache is also used to buffer database write operations. When SQLite is required to modify one of more of the database pages that make up a database file, it first modifies the cached version of the page in the page cache. At that point the page is considered a "dirty" page. At some point later on, the new content of the "dirty" page is copied from the page cache into the database file via the VFS interface. Buffering writes in the page cache can reduce the number of write operations required on the database file (in cases where the same page is updated twice) and allows optimizations based on the assumptions outlined in section fs_performance.

Database read and write operations, and the way in which they interact with and use the page cache, are described in detail in sections reading_data and writing_data of this document, respectively.

At any one time, the page cache contains zero or more page cache entries, each of which has the following data associated with it:

  • A reference to the associated database connection. Each entry in the page cache is associated with a single database connection; the database connection that created the entry. A page cache entry is only ever used by the database connection that created it. Page cache entries are not shared between database connections.

  • The page number of the cached page. Pages are sequentially numbered within a database file starting from page 1 (page 1 begins at byte offset 0). Refer to ff_sqlitert_requirements for details.

  • The cached data; a blob of data page-size bytes in size.

The first two elements in the list above, the associated database connection and the page number, uniquely identify the page cache entry. At no time may the page cache contain two entries for which both the database connection and page number are identical. Or, put another way, a single database connection never caches more than one copy of a database page within the page cache.

At any one time, each page cache entry may be said to be a clean page, a non-writable dirty page or a writable dirty page, according to the following definitions:

  • A clean page is one for which the cached data currently matches the contents of the corresponding page of the database file. The page has not been modified since it was loaded from the file.

  • A dirty page is a page cache entry for which the cached data has been modified since it was loaded from the database file, and so no longer matches the current contents of the corresponding database file page. A dirty page is one that is currently buffering a modification made to the database file as part of a write transaction.

  • Within this document, the term non-writable dirty page is used specifically to refer to a page cache entry with modified content for which it is not yet safe to update the database file with. It is not safe to update a database file with a buffered write if a power or system failure that occurs during or soon after the update may cause the database to become corrupt following system recovery, according to the assumptions made in section fs_assumption_details.

  • A dirty page for which it would be safe to update the corresponding database file page with the modified contents of without risking database corruption is known as a writable dirty page.

The exact logic used to determine if a page cache entry with modified content is a dirty page or writable page is presented in section page_cache_algorithms.

Because main-memory is a limited resource, the page cache cannot be allowed to grow indefinitely. As a result, unless all database files opened by database connections within the process are quite small, sometimes data must be discarded from the page cache. In practice this means page cache entries must be purged to make room for new ones. If a page cache entry being removed from the page cache to free main-memory is a dirty page, then its contents must be saved into the database file before it can be discarded without data loss. The following two sub-sections describe the algorithms used by the page cache to determine exactly when existing page cache entries are purged (discarded).

Page Cache Configuration

Describe the parameters set to configure the page cache limits.

Page Cache Algorithms

Requirements describing the way in which the configuration parameters are used. About LRU etc.

Reading Data

In order to return data from the database to the user, for example as the results of a SELECT query, SQLite must at some point read data from the database file. Usually, data is read from the database file in aligned blocks of page-size bytes. The exception is when the database file header fields are being inspected, before the page-size used by the database can be known.

With two exceptions, a database connection must have an open transaction (either a read-only transaction or a read/write transaction) on the database before data may be read from the database file.

The two exceptions are:

  • When an attempt is made to read the 100 byte database file header immediately after opening the database connection (see section open_new_connection). When this occurs no lock is held on the database file.
  • Data read while in the process of opening a read-only transaction (see section open_read_only_trans). These read operations occur after a shared lock is held on the database file.

Once a transaction has been opened, reading data from a database connection is a simple operation. Using the xRead() method of the file-handle open on the database file, the required database file pages are read one at a time. SQLite never reads partial pages and always uses a single call to xRead() for each required page.

After reading the data for a database page, SQLite stores the raw page of data in the page cache. Each time a page of data is required by the upper layers, the page cache is queried to see if it contains a copy of the required page stored by the current database connection. If such an entry can be found, then the required data is read from the page cache instead of the database file. Only a connection with an open transaction transaction (either a read-only transaction or a read/write transaction) on the database may read data from the page cache. In this sense reading from the page cache is no different to reading from the database file.

Refer to section page_cache_algorithms for a description of exactly how and for how long page data is stored in the page cache.

Except for the read operation required by H35070 and those reads made as part of opening a read-only transaction, SQLite shall ensure that a database connection has an open read-only or read/write transaction when any data is read from the database file.

Aside from those read operations described by H35070 and H21XXX, SQLite shall read data from the database file in aligned blocks of page-size bytes, where page-size is the database page size used by the database file.

SQLite shall ensure that a database connection has an open read-only or read/write transaction before using data stored in the page cache to satisfy user queries.

Opening a Read-Only Transaction

Before data may be read from a database file or queried from the page cache, a read-only transaction must be successfully opened by the associated database connection (this is true even if the connection will eventually write to the database, as a read/write transaction may only be opened by upgrading from a read-only transaction). This section describes the procedure for opening a read-only transaction.

The key element of a read-only transaction is that the file-handle open on the database file obtains and holds a shared-lock on the database file. Because a connection requires an exclusive-lock before it may actually modify the contents of the database file, and by definition while one connection is holding a shared-lock no other connection may hold an exclusive-lock, holding a shared-lock guarantees that no other process may modify the database file while the read-only transaction remains open. This ensures that read-only transactions are sufficiently isolated from the transactions of other database users (see section overview).

Obtaining the shared lock itself on the database file is quite simple, SQLite just calls the xLock() method of the database file handle. Some of the other processes that take place as part of opening the read-only transaction are quite complex. The steps that SQLite is required to take to open a read-only transaction, in the order in which they must occur, is as follows:

  1. A shared-lock is obtained on the database file.
  2. The connection checks if a hot journal file exists in the file-system. If one does, then it is rolled back before continuing.
  3. The connection checks if the data in the page cache may still be trusted. If not, all page cache data is discarded.
  4. If the file-size is not zero bytes and the page cache does not contain valid data for the first page of the database, then the data for the first page must be read from the database.

Of course, an error may occur while attempting any of the 4 steps enumerated above. If this happens, then the shared-lock is released (if it was obtained) and an error returned to the user. Step 2 of the procedure above is described in more detail in section hot_journal_detection. Section cache_validation describes the process identified by step 3 above. Further detail on step 4 may be found in section read_page_one.

When required to open a read-only transaction using a database connection, SQLite shall first attempt to obtain a shared-lock on the file-handle open on the database file.

If, while opening a read-only transaction, SQLite fails to obtain the shared-lock on the database file, then the process is abandoned, no transaction is opened and an error returned to the user.

The most common reason an attempt to obtain a shared-lock may fail is that some other connection is holding an exclusive or pending lock. However it may also fail because some other error (e.g. an IO or comms related error) occurs within the call to the xLock() method.

While opening a read-only transaction, after successfully obtaining a shared lock on the database file, SQLite shall attempt to detect and roll back a hot journal file associated with the same database file.

If, while opening a read-only transaction, SQLite encounters an error while attempting to detect or roll back a hot journal file, then the shared-lock on the database file is released, no transaction is opened and an error returned to the user.

Section hot_journal_detection contains a description of and requirements governing the detection of a hot-journal file referred to in the above requirements.

Assuming no errors have occurred, then after attempting to detect and roll back a hot journal file, if the page cache contains any entries associated with the current database connection, then SQLite shall validate the contents of the page cache by testing the file change counter. This procedure is known as cache validation.

The cache validation process is described in detail in section cache_validation

If the cache validate procedure prescribed by H35040 is required and does not prove that the page cache entries associated with the current database connection are valid, then SQLite shall discard all entries associated with the current database connection from the page cache.

The numbered list above notes that the data for the first page of the database file, if it exists and is not already loaded into the page cache, must be read from the database file before the read-only transaction may be considered opened. This is handled by requirement H35240.

Hot Journal Detection

This section describes the procedure that SQLite uses to detect a hot journal file. If a hot journal file is detected, this indicates that at some point the process of writing a transaction to the database was interrupted and a recovery operation (hot journal rollback) needs to take place. This section does not describe the process of hot journal rollback (see section hot_journal_rollback) or the processes by which a hot journal file may be created (see section writing_data).

The procedure used to detect a hot-journal file is quite complex. The following steps take place:

  1. Using the VFS xAccess() method, SQLite queries the file-system to see if the journal file associated with the database exists. If it does not, then there is no hot-journal file.
  2. By invoking the xCheckReservedLock() method of the file-handle opened on the database file, SQLite checks if some other connection holds a reserved lock or greater. If some other connection does hold a reserved lock, this indicates that the other connection is midway through a read/write transaction (see section writing_data). In this case the journal file is not a hot-journal and must not be rolled back.
  3. Using the xFileSize() method of the file-handle opened on the database file, SQLite checks if the database file is 0 bytes in size. If it is, the journal file is not considered to be a hot journal file. Instead of rolling back the journal file, in this case it is deleted from the file-system by calling the VFS xDelete() method. Technically, there is a race condition here. This step should be moved to after the exclusive lock is held.
  4. An attempt is made to upgrade to an exclusive lock on the database file. If the attempt fails, then all locks, including the recently obtained shared lock are dropped. The attempt to open a read-only transaction has failed. This occurs when some other connection is also attempting to open a read-only transaction and the attempt to gain the exclusive lock fails because the other connection is also holding a shared lock. It is left to the other connection to roll back the hot journal.
    It is important that the file-handle lock is upgraded directly from shared to exclusive in this case, instead of first upgrading to reserved or pending locks as is required when obtaining an exclusive lock to write to the database file (section writing_data). If SQLite were to first upgrade to a reserved or pending lock in this scenario, then a second process also trying to open a read-transaction on the database file might detect the reserved lock in step 2 of this process, conclude that there was no hot journal, and commence reading data from the database file.
  5. The xAccess() method is invoked again to detect if the journal file is still in the file system. If it is, then it is a hot-journal file and SQLite tries to roll it back (see section rollback).

Master journal file pointers?

The following requirements describe step 1 of the above procedure in more detail.

When required to attempt to detect a hot-journal file, SQLite shall first use the xAccess() method of the VFS layer to check if a journal file exists in the file-system.

If the call to xAccess() required by H35140 fails (due to an IO error or similar), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the shared lock held on the database file and return an error to the user.

When required to attempt to detect a hot-journal file, if the call to xAccess() required by H35140 indicates that a journal file does not exist, then SQLite shall conclude that there is no hot-journal file in the file system and therefore that no hot journal rollback is required.

The following requirements describe step 2 of the above procedure in more detail.

When required to attempt to detect a hot-journal file, if the call to xAccess() required by H35140 indicates that a journal file is present, then the xCheckReservedLock() method of the database file file-handle is invoked to determine whether or not some other process is holding a reserved or greater lock on the database file.

If the call to xCheckReservedLock() required by H35160 fails (due to an IO or other internal VFS error), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the shared lock held on the database file and return an error to the user.

If the call to xCheckReservedLock() required by H35160 indicates that some other database connection is holding a reserved or greater lock on the database file, then SQLite shall conclude that there is no hot journal file. In this case the attempt to detect a hot journal file is concluded.

The following requirements describe step 3 of the above procedure in more detail.

If while attempting to detect a hot-journal file the call to xCheckReservedLock() indicates that no process holds a reserved or greater lock on the database file, then SQLite shall open a file handle on the potentially hot journal file using the VFS xOpen() method.

If the call to xOpen() required by H35440 fails (due to an IO or other internal VFS error), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the shared lock held on the database file and return an error to the user.

After successfully opening a file-handle on a potentially hot journal file, SQLite shall query the file for its size in bytes using the xFileSize() method of the open file handle.

If the call to xFileSize() required by H35450 fails (due to an IO or other internal VFS error), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the shared lock held on the database file, close the file handle opened on the journal file and return an error to the user.

If the size of a potentially hot journal file is revealed to be zero bytes by a query required by H35450, then SQLite shall close the file handle opened on the journal file and delete the journal file using a call to the VFS xDelete() method. In this case SQLite shall conclude that there is no hot journal file.

If the call to xDelete() required by H35450 fails (due to an IO or other internal VFS error), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the shared lock held on the database file and return an error to the user.

The following requirements describe step 4 of the above procedure in more detail.

If the size of a potentially hot journal file is revealed to be greater than zero bytes by a query required by H35450, then SQLite shall attempt to upgrade the shared lock held by the database connection on the database file directly to an exclusive lock.

If an attempt to upgrade to an exclusive lock prescribed by H35470 fails for any reason, then SQLite shall release all locks held by the database connection and close the file handle opened on the journal file. The attempt to open a read-only transaction shall be deemed to have failed and an error returned to the user.

Finally, the following requirements describe step 5 of the above procedure in more detail.

If, as part of the hot journal file detection process, the attempt to upgrade to an exclusive lock mandated by H35470 is successful, then SQLite shall query the file-system using the xAccess() method of the VFS implementation to test whether or not the journal file is still present in the file-system.

If the call to xAccess() required by H35490 fails (due to an IO or other internal VFS error), then SQLite shall abandon the attempt to open a read-only transaction, relinquish the lock held on the database file, close the file handle opened on the journal file and return an error to the user.

If the call to xAccess() required by H35490 reveals that the journal file is no longer present in the file system, then SQLite shall abandon the attempt to open a read-only transaction, relinquish the lock held on the database file, close the file handle opened on the journal file and return an SQLITE_BUSY error to the user.

If the xAccess() query required by H35490 reveals that the journal file is still present in the file system, then SQLite shall conclude that the journal file is a hot journal file that needs to be rolled back. SQLite shall immediately begin hot journal rollback.

Cache Validation

When a database connection opens a read transaction, the page cache may already contain data associated with the database connection. However, if another process has modified the database file since the cached pages were loaded it is possible that the cached data is invalid.

SQLite determines whether or not the page cache entries belonging to the database connection are valid or not using the file change counter, a field in the database file header. The file change counter is a 4-byte big-endian integer field stored starting at byte offset 24 of the database file header. Before the conclusion of a read/write transaction that modifies the contents of the database file in any way (see section writing_data), the value stored in the file change counter is incremented. When a database connection unlocks the database file, it stores the current value of the file change counter. Later, while opening a new read-only transaction, SQLite checks the value of the file change counter stored in the database file. If the value has not changed since the database file was unlocked, then the page cache entries can be trusted. If the value has changed, then the page cache entries cannot be trusted and all entries associated with the current database connection are discarded.

When a file-handle open on a database file is unlocked, if the page cache contains one or more entries belonging to the associated database connection, SQLite shall store the value of the file change counter internally.

When required to perform cache validation as part of opening a read transaction, SQLite shall read a 16 byte block starting at byte offset 24 of the database file using the xRead() method of the database connections file handle.

Why a 16 byte block? Why not 4? (something to do with encrypted databases).

While performing cache validation, after loading the 16 byte block as required by H35190, SQLite shall compare the 32-bit big-endian integer stored in the first 4 bytes of the block to the most recently stored value of the file change counter (see H35180). If the values are not the same, then SQLite shall conclude that the contents of the cache are invalid.

Requirement H35050 (section open_read_only_trans) specifies the action SQLite is required to take upon determining that the cache contents are invalid.

Page 1 and the Expected Page Size

As the last step in opening a read transaction on a database file that is more than 0 bytes in size, SQLite is required to load data for page 1 of the database into the page cache, if it is not already there. This is slightly more complicated than it seems, as the database page-size is no known at this point.

Even though the database page-size cannot be known for sure, SQLite is usually able to guess correctly by assuming it to be equal to the connections expected page size. The expected page size is the value of the page-size field read from the database file header while opening the database connection (see section open_new_connection), or the page-size of the database file when the most read transaction was concluded.

During the conclusion of a read transaction, before unlocking the database file, SQLite shall set the connections expected page size to the current database page-size.

As part of opening a new read transaction, immediately after performing cache validation, if there is no data for database page 1 in the page cache, SQLite shall read N bytes from the start of the database file using the xRead() method of the connections file handle, where N is the connections current expected page size value.

If page 1 data is read as required by H35230, then the value of the page-size field that appears in the database file header that consumes the first 100 bytes of the read block is not the same as the connections current expected page size, then the expected page size is set to this value, the database file is unlocked and the entire procedure to open a read transaction is repeated.

If page 1 data is read as required by H35230, then the value of the page-size field that appears in the database file header that consumes the first 100 bytes of the read block is the same as the connections current expected page size, then the block of data read is stored in the page cache as page 1.

Reading Database Data

Add something about checking the page-cache first etc.

Ending a Read-only Transaction

To end a read-only transaction, SQLite simply relinquishes the shared lock on the file-handle open on the database file. No other action is required.

When required to end a read-only transaction, SQLite shall relinquish the shared lock held on the database file by calling the xUnlock() method of the file-handle.

See also requirements H35180 and H35210 above.

Writing Data

Using DDL or DML SQL statements, SQLite users may modify the contents and size of a database file. Exactly how changes to the logical database are translated to modifications to the database file is described in ff_sqlitert_requirements. From the point of view of the sub-systems described in this document, each DDL or DML statement executed results in the contents of zero or more database file pages being overwritten with new data. A DDL or DML statement may also append or truncate one or more pages to or from the end of the database file. One or more DDL and/or DML statements are grouped together to make up a single write transaction. A write transaction is required to have the special properties described in section overview; a write transaction must be isolated, durable and atomic.

SQLite accomplishes these goals using the following techniques:

  • To ensure that write transactions are isolated, before beginning to modify the contents of the database file to reflect the results of a write transaction, SQLite obtains an exclusive lock on the database file. The lock is not relinquished until the write transaction is concluded. Because reading from the database file requires a shared lock (see section reading_data) and holding an exclusive lock guarantees that no other database connection is holding or can obtain a shared lock, this ensures that no other connection may read data from the database file at a point when a write transaction has been partially applied.

  • Ensuring that write transactions are atomic is the most complex task required of the system. In this case, atomic means that even if a system failure occurs, an attempt to commit a write transaction to the database file either results in all changes that are a part of the transaction being successfully applied to the database file, or none of the changes are successfully applied. There is no chance that a subset of the changes only are applied. Hence from the point of view of an external observer, the write transaction appears to be an atomic event.

    Of course, it is usually not possible to atomically apply all the changes required by a write transaction to a database file within the file-system. For example, if a write transaction requires ten pages of a database file to be modified, and a power outage causes a system failure after sqlite has modified only five pages, then the database file will almost certainly be in an inconsistent state following system recovery.

    SQLite solves this problem by using a journal file. In almost all cases, before the database file is modified in any way, SQLite stores sufficient information in the journal file to allow the original the database file to be reconstructed if a system failure occurs while the database file is being updated to reflect the modifications made by the write transaction. Each time SQLite opens a database file, it checks if such a system failure has occurred and, if so, reconstructs the database file based on the contents of the journal file. The procedure used to detect whether or not this process, coined hot journal rollback, is required is described in section hot_journal_detection. Hot journal rollback itself is described in section hot_journal_rollback.

    The same technique ensures that an SQLite database file cannot be corrupted by a system failure that occurs at an inopportune moment. If a system failure does occur before SQLite has had a chance to execute sufficient sync file operations to ensure that the changes that make up a write transaction have made it safely to persistent storage, then the journal file will be used to restore the database to a known good state following system recovery.

  • So that write transactions are durable in the face of a system failure, SQLite executes a sync file operation on the database file before concluding the write transaction

The page cache is used to buffer modifications to the database file image before they are written to the database file. When the contents of a page is required to be modified as the results of an operation within a write transaction, the modified copy is stored in the page cache. Similarly, if new pages are appended to the end of a database file, they are added to the page cache instead of being immediately written to the database file within the file-system.

Ideally, all changes for an entire write transaction are buffered in the page cache until the end of the transaction. When the user commits the transaction, all changes are applied to the database file in the most efficient way possible, taking into account the assumptions enumerated in section fs_performance. Unfortunately, since main-memory is a limited resource, this is not always possible for large transactions. In this case changes are buffered in the page cache until some internal condition or limit is reached, then written out to the database file in order to free resources as they are required. Section page_cache_algorithms describes the circumstances under which changes are flushed through to the database file mid-transaction to free page cache resources.

Even if an application or system failure does not occur while a write transaction is in progress, a rollback operation to restore the database file and page cache to the state that it was in before the transaction started may be required. This may occur if the user explicitly requests transaction rollback (by issuing a "ROLLBACK" command), or automatically, as a result of encountering an SQL constraint (see sql_sqlitert_requirements). For this reason, the original page content is stored in the journal file before the page is even modified within the page cache.

Introduce the following sub-sections.

Journal File Format

This section describes the format used by an SQLite journal file.

A journal file consists of one or more journal headers, zero or more journal records and optionally a master journal pointer. Each journal file always begins with a journal header, followed by zero or more journal records. Following this may be a second journal header followed by a second set of zero or more journal records and so on. There is no limit to the number of journal headers a journal file may contain. Following the journal headers and their accompanying sets of journal records may be the optional master journal pointer. Or, the file may simply end following the final journal record.

This section only describes the format of the journal file and the various objects that make it up. But because a journal file may be read by an SQLite process following recovery from a system failure (hot journal rollback, see section hot_journal_rollback) it is also important to describe the way the file is created and populated within the file-system using a combination of write file, sync file and truncate file operations. These are described in section write_transactions.

Journal Header Format

A journal header is sector-size bytes in size, where sector-size is the value returned by the xSectorSize method of the file handle opened on the database file. Only the first 28 bytes of the journal header are used, the remainder may contain garbage data. The first 28 bytes of each journal header consists of an eight byte block set to a well-known value, followed by five big-endian 32-bit unsigned integer fields.

Figure - Journal Header Format

Figure figure_journal_header graphically depicts the layout of a journal header. The individual fields are described in the following table. The offsets in the 'byte offset' column of the table are relative to the start of the journal header.

Byte offset | Size in bytes | Description
08The journal magic field always contains a well-known 8-byte string value used to identify SQLite journal files. The well-known sequence of byte values is:
0xd9 0xd5 0x05 0xf9 0x20 0xa1 0x63 0xd7
8 | 4 | This field, the record count, is set to the number of journal records that follow this journal header in the journal file.
12 | 4 | The checksum initializer field is set to a pseudo-random value. It is used as part of the algorithm to calculate the checksum for all journal records that follow this journal header.
16 | 4 | This field, the database page count, is set to the number of pages that the database file contained before any modifications associated with write transaction are applied.
20 | 4 | This field, the sector size, is set to the sector size of the device on which the journal file was created, in bytes. This value is required when reading the journal file to determine the size of each journal header.
24 | 4 | The page size field contains the database page size used by the corresponding database file when the journal file was created, in bytes.

All journal headers are positioned in the file so that they start at a sector size aligned offset. To achieve this, unused space may be left between the start of the second and subsequent journal headers and the end of the journal records associated with the previous header.

Journal Record Format

Each journal record contains the original data for a database page modified by the write transaction. If a rollback is required, then this data may be used to restore the contents of the database page to the state it was in before the write transaction was started.

Figure - Journal Record Format

A journal record, depicted graphically by figure figure_journal_record, contains three fields, as described in the following table. Byte offsets are relative to the start of the journal record.

Byte offset | Size in bytes | Description
0 | 4 | The page number of the database page associated with this journal record, stored as a 4 byte big-endian unsigned integer.
4 | page-size | This field contains the original data for the page, exactly as it appeared in the database file before the write transaction began.
4 + page-size | 4 | This field contains a checksum value, calculated based on the contents of the journaled database page data (the previous field) and the values stored in the checksum initializer field of the preceding journal header.

The set of journal records that follow a journal header in a journal file are packed tightly together. There are no alignment requirements for journal records as there are for journal headers.

Master Journal Pointer

To support atomic transactions that modify more than one database file, SQLite sometimes includes a master journal pointer record in a journal file. Multiple file transactions are described in section multifile_transactions. A master journal pointer contains the name of a master journal-file along with a check-sum and some well known values that allow the master journal pointer to be recognized as such when the journal file is read during a rollback operation (section rollback).

As is the case for a journal header, the start of a master journal pointer is always positioned at a sector size aligned offset. If the journal record or journal header that appears immediately before the master journal pointer does not end at an aligned offset, then unused space is left between the end of the journal record or journal header and the start of the master journal pointer.

Figure - Master Journal Pointer Format

A master journal pointer, depicted graphically by figure figure_master_journal_ptr, contains five fields, as described in the following table. Byte offsets are relative to the start of the master journal pointer.

Byte offset | Size in bytes | Description
0 | 4 | This field, the locking page number, is always set to the page number of the database locking page stored as a 4-byte big-endian integer. The locking page is the page that begins at byte offset 230 of the database file. Even if the database file is large enough to contain the locking page, the locking page is never used to store any data and so the first four bytes of of a valid journal record will never contain this value. For further description of the locking page, refer to ff_sqlitert_requirements.
4 | name-length | The master journal name field contains the name of the master journal file, encoded as a utf-8 string. There is no nul-terminator appended to the string.
4 + name-length | 4 | The name-length field contains the length of the previous field in bytes, formatted as a 4-byte big-endian unsigned integer.
8 + name-length | 4 | The checksum field contains a checksum value stored as a 4-byte big-endian signed integer. The checksum value is calculated as the sum of the bytes that make up the master journal name field, interpreting each byte as an 8-bit signed integer.
12 + name-length8 Finally, the journal magic field always contains a well-known 8-byte string value; the same value stored in the first 8 bytes of a journal header. The well-known sequence of bytes is:
0xd9 0xd5 0x05 0xf9 0x20 0xa1 0x63 0xd7

Write Transactions

This section describes the progression of an SQLite write transaction. From the point of view of the systems described in this document, most write transactions consist of three steps:

  1. The write transaction is opened. This process is described in section opening_a_write_transaction.

  2. The end-user executes DML or DDL SQL statements that require the structure of the database file of the database file to be modified. These modifications may be any combination of operations to

    • modify the content of an existing database page,
    • append a new database page to the database file image, or
    • truncate (discard) a database page from the end of the database file.
    These operations are described in detail in section modifying_appending_truncating. How user DDL or DML SQL statements are mapped to combinations of these three operations is described in ff_sqlitert_requirements.

  3. The write transaction is concluded and the changes made permanently committed to the database. The process required to commit a transaction is described in section committing_a_transaction.

As an alternative to step 3 above, the transaction may be rolled back. Transaction rollback is described in section rollback. Finally, it is also important to remember that a write transaction may be interrupted by a system failure at any point. In this case, the contents of the file-system (the database file and journal file) must be left in such a state so as to enable the database file to be restored to the state it was in before the interrupted write transaction was started. This is known as hot journal rollback, and is described in section hot_journal_rollback. Section fs_assumption_details describes the assumptions made regarding the effects of a system failure on the file-system contents following recovery.

Beginning a Write Transaction

Before any database pages may be modified within the page cache, the database connection must open a write transaction. Opening a write transaction requires that the database connection obtains a reserved lock (or greater) on the database file. Because a obtaining a reserved lock on a database file guarantees that no other database connection may hold or obtain a reserved lock or greater, it follows that no other database connection may have an open write transaction.

A reserved lock on the database file may be thought of as an exclusive lock on the journal file. No database connection may read from or write to a journal file without a reserved or greater lock on the corresponding database file.

Before opening a write transaction, a database connection must have an open read transaction, opened via the procedure described in section open_read_only_trans. This ensures that there is no hot-journal file that needs to be rolled back and that any data stored in the page cache can be trusted.

Once a read transaction has been opened, upgrading to a write transaction is a two step process, as follows:

  1. A reserved lock is obtained on the database file.
  2. The journal file is opened and created if necessary (using the VFS xOpen method), and a journal file header written to the start of it using a single call to the file handles xWrite method.

Requirements describing step 1 of the above procedure in detail:

When required to open a write transaction on the database, SQLite shall first open a read transaction, if the database connection in question has not already opened one.

When required to open a write transaction on the database, after ensuring a read transaction has already been opened, SQLite shall obtain a reserved lock on the database file by calling the xLock method of the file-handle open on the database file.

If an attempt to acquire a reserved lock prescribed by requirement H35360 fails, then SQLite shall deem the attempt to open a write transaction to have failed and return an error to the user.

Requirements describing step 2 of the above procedure in detail:

When required to open a write transaction on the database, after obtaining a reserved lock on the database file, SQLite shall open a read/write file-handle on the corresponding journal file.

When required to open a write transaction on the database, after opening a file-handle on the journal file, SQLite shall append a journal header to the (currently empty) journal file.

Writing a Journal Header

Requirements describing how a journal header is appended to a journal file:

When required to append a journal header to the journal file, SQLite shall do so by writing a block of sector-size bytes using a single call to the xWrite method of the file-handle open on the journal file. The block of data written shall begin at the smallest sector-size aligned offset at or following the current end of the journal file.

The first 8 bytes of the journal header required to be written by H35680 shall contain the following values, in order from byte offset 0 to 7: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63 and 0xd7.

Bytes 8-11 of the journal header required to be written by H35680 shall contain 0x00.

Bytes 12-15 of the journal header required to be written by H35680 shall contain the number of pages that the database file contained when the current write-transaction was started, formatted as a 4-byte big-endian unsigned integer.

Bytes 16-19 of the journal header required to be written by H35680 shall contain pseudo-randomly generated values.

Bytes 20-23 of the journal header required to be written by H35680 shall contain the sector size used by the VFS layer, formatted as a 4-byte big-endian unsigned integer.

Bytes 24-27 of the journal header required to be written by H35680 shall contain the page size used by the database at the start of the write transaction, formatted as a 4-byte big-endian unsigned integer.

Modifying, Adding or Truncating a Database Page

When the end-user executes a DML or DDL SQL statement to modify the database schema or content, SQLite is required to update the database file image to reflect the new database state. This involves modifying the content of, appending or truncating one of more database file pages. Instead of modifying the database file directly using the VFS interface, changes are first buffered within the page cache.

Before modifying a database page within the page cache that may need to be restored by a rollback operation, the page must be journalled. Journalling a page is the process of copying that pages original data into the journal file so that it can be recovered if the write transaction is rolled back. The process of journalling a page is described in section journalling_a_page.

When required to modify the contents of an existing database page that existed and was not a free-list leaf page when the write transaction was opened, SQLite shall journal the page if it has not already been journalled within the current write transaction.

When required to modify the contents of an existing database page, SQLite shall update the cached version of the database page content stored as part of the page cache entry associated with the page.

When a new database page is appended to a database file, there is no requirement to add a record to the journal file. If a rollback is required the database file will simply be truncated back to its original size based on the value stored at byte offset 12 of the journal file.

When required to append a new database page to the database file, SQLite shall create a new page cache entry corresponding to the new page and insert it into the page cache. The dirty flag of the new page cache entry shall be set.

If required to truncate a database page from the end of the database file, the associated page cache entry is discarded. The adjusted size of the database file is stored internally. The database file is not actually truncated until the current write transaction is committed (see section committing_a_transaction).

When required to truncate (remove) a database page that existed and was not a free-list leaf page when the write transaction was opened from the end of a database file, SQLite shall journal the page if it has not already been journalled within the current write transaction.

When required to truncate a database page from the end of the database file, SQLite shall discard the associated page cache entry from the page cache.

Journalling a Database Page

A page is journalled by adding a journal record to the journal file. The format of a journal record is described in section journal_record_format.

When required to journal a database page, SQLite shall first append the page number of the page being journalled to the journal file, formatted as a 4-byte big-endian unsigned integer, using a single call to the xWrite method of the file-handle opened on the journal file.

When required to journal a database page, if the attempt to append the page number to the journal file is successful, then the current page data (page-size bytes) shall be appended to the journal file, using a single call to the xWrite method of the file-handle opened on the journal file.

When required to journal a database page, if the attempt to append the current page data to the journal file is successful, then SQLite shall append a 4-byte big-endian integer checksum value to the to the journal file, using a single call to the xWrite method of the file-handle opened on the journal file.

The checksum value written to the journal file immediately after the page data (requirement H35290), is a function of both the page data and the checksum initializer field stored in the journal header (see section journal_header_format). Specifically, it is the sum of the checksum initializer and the value of every 200th byte of page data interpreted as an 8-bit unsigned integer, starting with the (page-size % 200)'th byte of page data. For example, if the page-size is 1024 bytes, then a checksum is calculated by adding the values of the bytes at offsets 23, 223, 423, 623, 823 and 1023 (the last byte of the page) together with the value of the checksum initializer.

The checksum value written to the journal file by the write required by H35290 shall be equal to the sum of the checksum initializer field stored in the journal header (H35700) and every 200th byte of the page data, beginning with the (page-size % 200)th byte.

The '%' character is used in requirement H35300 to represent the modulo operator, just as it is in programming languages such as C, Java and Javascript.

Syncing the Journal File

Even after the original data of a database page has been written into the journal file using calls to the journal file file-handle xWrite method (section journalling_a_page), it is still not safe to write to the page within the database file. This is because in the event of a system failure the data written to the journal file may still be corrupted (see section fs_characteristics). Before the page can be updated within the database itself, the following procedure takes place:

  1. The xSync method of the file-handle opened on the journal file is called. This operation ensures that all journal records in the journal file have been written to persistent storage, and that they will not become corrupted as a result of a subsequent system failure.
  2. The journal record count field (see section journal_header_format) of the most recently written journal header in the journal file is updated to contain the number of journal records added to the journal file since the header was written.
  3. The xSync method is called again, to ensure that the update to the journal record count has been committed to persistent storage.

If all three of the steps enumerated above are executed successfully, then it is safe to modify the content of the journalled database pages within the database file itself. The combination of the three steps above is referred to as syncing the journal file.

When required to sync the journal file, SQLite shall invoke the xSync method of the file handle open on the journal file.

When required to sync the journal file, after invoking the xSync method as required by H35750, SQLite shall update the record count of the journal header most recently written to the journal file. The 4-byte field shall be updated to contain the number of journal records that have been written to the journal file since the journal header was written, formatted as a 4-byte big-endian unsigned integer.

When required to sync the journal file, after updating the record count field of a journal header as required by H35760, SQLite shall invoke the xSync method of the file handle open on the journal file.

Upgrading to an Exclusive Lock

Before the content of a page modified within the page cache may be written to the database file, an exclusive lock must be held on the database file. The purpose of this lock is to prevent another connection from reading from the database file while the first connection is midway through writing to it. Whether the reason for writing to the database file is because a transaction is being committed, or to free up space within the page cache, upgrading to an exclusive lock always occurs immediately after syncing the journal file.

When required to upgrade to an exclusive lock as part of a write transaction, SQLite shall first attempt to obtain a pending lock on the database file if one is not already held by invoking the xLock method of the file handle opened on the database file.

When required to upgrade to an exclusive lock as part of a write transaction, after successfully obtaining a pending lock SQLite shall attempt to obtain an exclusive lock by invoking the xLock method of the file handle opened on the database file.

What happens if the exclusive lock cannot be obtained? It is not possible for the attempt to upgrade from a reserved to a pending lock to fail.

Committing a Transaction

Committing a write transaction is the final step in updating the database file. Committing a transaction is a seven step process, summarized as follows:

  1. The database file header change counter field is incremented. The change counter, described in ff_sqlitert_requirements, is used by the cache validation procedure described in section cache_validation.

  2. The journal file is synced. The steps required to sync the journal file are described in section syncing_journal_file.

  3. Upgrade to an exclusive lock on the database file, if an exclusive lock is not already held. Upgrading to an exclusive lock is described in section upgrading_to_exclusive_lock.

  4. Copy the contents of all dirty pages stored in the page cache into the database file. The set of dirty pages are written to the database file in page number order in order to improve performance (see the assumptions in section fs_performance for details).

  5. The database file is synced to ensure that all updates are stored safely on the persistent media.

  6. The file-handle open on the journal file is closed and the journal file itself deleted. At this point the write transaction transaction has been irrevocably committed.

  7. The database file is unlocked.

Expand on and explain the above a bit.

The following requirements describe the steps enumerated above in more detail.

When required to commit a write-transaction, SQLite shall modify page 1 to increment the value stored in the change counter field of the database file header.

The change counter is a 4-byte big-endian integer field stored at byte offset 24 of the database file. The modification to page 1 required by H35800 is made using the process described in section modifying_appending_truncating. If page 1 has not already been journalled as a part of the current write-transaction, then incrementing the change counter may require that page 1 be journalled. In all cases the page cache entry corresponding to page 1 becomes a dirty page as part of incrementing the change counter value.

When required to commit a write-transaction, after incrementing the change counter field, SQLite shall sync the journal file.

When required to commit a write-transaction, after syncing the journal file as required by H35810, if an exclusive lock on the database file is not already held, SQLite shall attempt to upgrade to an exclusive lock.

When required to commit a write-transaction, after syncing the journal file as required by H35810 and ensuring that an exclusive lock is held on the database file as required by H35830, SQLite shall copy the contents of all dirty page stored in the page cache into the database file using calls to the xWrite method of the database connection file handle. Each call to xWrite shall write the contents of a single dirty page (page-size bytes of data) to the database file. Dirty pages shall be written in order of page number, from lowest to highest.

When required to commit a write-transaction, after copying the contents of any dirty pages to the database file as required by H35830, SQLite shall sync the database file by invoking the xSync method of the database connection file handle.

When required to commit a write-transaction, after syncing the database file as required by H35840, SQLite shall close the file-handle opened on the journal file and delete the journal file from the file system via a call to the VFS xDelete method.

When required to commit a write-transaction, after deleting the journal file as required by H35850, SQLite shall relinquish all locks held on the database file by invoking the xUnlock method of the database connection file handle.

Is the shared lock held after committing a write transaction?

Purging a Dirty Page

Usually, no data is actually written to the database file until the user commits the active write transaction. The exception is if a single write transaction contains too many modifications to be stored in the page cache. In this case, some of the database file modifications stored in the page cache must be applied to the database file before the transaction is committed so that the associated page cache entries can be purged from the page cache to free memory. Exactly when this condition is reached and dirty pages must be purged is described in section page_cache_algorithms.

Before the contents of the page cache entry can be written into the database file, the page cache entry must meet the criteria for a writable dirty page, as defined in section page_cache_algorithms. If the dirty page selected by the algorithms in section page_cache_algorithms for purging, SQLite is required to sync the journal file. Immediately after the journal file is synced, all dirty pages associated with the database connection are classified as writable dirty pages.

When required to purge a non-writable dirty page from the page cache, SQLite shall sync the journal file before proceeding with the write operation required by H35670.

After syncing the journal file as required by H35640, SQLite shall append a new journal header to the journal file before proceeding with the write operation required by H35670.

Appending a new journal header to the journal file is described in section writing_journal_header.

Once the dirty page being purged is writable, it is simply written into the database file.

When required to purge a page cache entry that is a dirty page SQLite shall write the page data into the database file, using a single call to the xWrite method of the database connection file handle.

Multi-File Transactions

Statement Transactions

Rollback

Hot Journal Rollback

Transaction Rollback

Statement Rollback

References

[1] | C API Requirements Document.
[2] | SQL Requirements Document.
[3] | File Format Requirements Document.


SQLite Library Footprint

Choose any three.
About Sitemap Documentation Download License News Support

Size Of The SQLite Library

The code space used by the SQLite library depends heavily on the target platform, what compiler and optimization options are used to generate object code, and which optional features of SQLite are included or omitted from the build. This page provides examples of what to expect.

SQLite version 3.7.8 is less than 350KiB in size on x86 with -Os and less than 400KiB (409KB) on x64. The -O2 and -O3 builds are larger, presumably due to loop unrolling and function inlining.

Case 1

  • SuSE Linux 10.1
  • GCC 4.1.0
  • SQLite version 3.7.8
  • x86 (32-bit)

Optimization Setting | Size (bytes) | Run-time (Relative to -O0)
-O0 | 529765 | 1.00
-O1 | 397204 | 0.71
-Os | 333059 | 0.73
-O2 | 418161 | 0.68
-O3 | 828602 | 0.66

Case 2

  • Ubuntu
  • GCC 4.5.2
  • SQLite version 3.7.8
  • x86_64 (64-bit)

Optimization Setting | Size (bytes) | Run-time (Relative to -O0)
-O0 | 625841 | 1.00
-O1 | 455072 | 0.62
-Os | 404201 | 0.59
-O2 | 499543 | 0.53
-O3 | 678465 | 0.54

Case 3

  • Mac OS 10.7.1 (Lion)
  • GCC 4.2.1 + LLVM
  • SQLite version 3.7.8
  • x86_64 (64-bit)

Optimization Setting | Size (bytes) | Run-time (Relative to -O0)
-O0 | 806598 | 1.00
-O1 | 508500 | 0.61
-Os | 481816 | 0.57
-O2 | 614346 | 0.55
-O3 | 661622 | 0.55

The Effect Of Compile-Time Options On Library Size

The next study shows the effect that various compile-time options for SQLite have on the size of the resulting library file. The following size figures are computed with an early beta of SQLite version 3.7.9 using GCC version 4.6.1 for X86_64 running on Ubuntu with the -Os option. Actual sizes and size differences may vary by compiler and system.

Compile-Time Option | Library Footprint | Difference From Baseline | Percentage Difference
All OMIT options | 248363 | -155714 | -38.536%
SQLITE_OMIT_TRIGGER | 382038 | -22039 | -5.454%
SQLITE_OMIT_WAL | 388281 | -15796 | -3.909%
SQLITE_OMIT_FLOATING_POINT | 390469 | -13608 | -3.368%
SQLITE_OMIT_VIRTUALTABLE | 391156 | -12921 | -3.198%
SQLITE_OMIT_PRAGMA | 391292 | -12785 | -3.164%
SQLITE_OMIT_FOREIGN_KEY | 393555 | -10522 | -2.604%
SQLITE_OMIT_AUTOVACUUM | 395589 | -8488 | -2.101%
SQLITE_OMIT_SUBQUERY | 396313 | -7764 | -1.921%
SQLITE_OMIT_COMPOUND_SELECT | 396810 | -7267 | -1.798%
SQLITE_OMIT_EXPLAIN | 397011 | -7066 | -1.749%
SQLITE_OMIT_DATETIME_FUNCS | 397179 | -6898 | -1.707%
SQLITE_OMIT_INTEGRITY_CHECK | 397438 | -6639 | -1.643%
SQLITE_OMIT_ATTACH | 397951 | -6126 | -1.516%
SQLITE_OMIT_ALTERTABLE | 398344 | -5733 | -1.419%
SQLITE_OMIT_UTF16 | 399069 | -5008 | -1.239%
SQLITE_OMIT_SHARED_CACHE | 399249 | -4828 | -1.195%
SQLITE_OMIT_INCRBLOB | 399889 | -4188 | -1.036%
SQLITE_OMIT_ANALYZE | 400207 | -3870 | -0.958%
SQLITE_OMIT_AUTHORIZATION | 401002 | -3075 | -0.761%
SQLITE_OMIT_VACUUM | 401026 | -3051 | -0.755%
SQLITE_OMIT_PAGER_PRAGMAS | 401168 | -2909 | -0.720%
SQLITE_OMIT_OR_OPTIMIZATION | 401374 | -2703 | -0.669%
SQLITE_OMIT_VIEW | 401500 | -2577 | -0.638%
SQLITE_OMIT_BUILTIN_TEST | 401711 | -2366 | -0.586%
SQLITE_OMIT_XFER_OPT | 402052 | -2025 | -0.501%
SQLITE_OMIT_AUTOINCREMENT | 402098 | -1979 | -0.490%
SQLITE_OMIT_SCHEMA_PRAGMAS | 402312 | -1765 | -0.437%
SQLITE_OMIT_TRACE | 402369 | -1708 | -0.423%
SQLITE_OMIT_LOAD_EXTENSION | 402611 | -1466 | -0.363%
SQLITE_OMIT_AUTOMATIC_INDEX | 402685 | -1392 | -0.344%
SQLITE_OMIT_LIKE_OPTIMIZATION | 402928 | -1149 | -0.284%
SQLITE_OMIT_REINDEX | 402975 | -1102 | -0.273%
SQLITE_OMIT_GET_TABLE | 402999 | -1078 | -0.267%
SQLITE_OMIT_COMPLETE | 403135 | -942 | -0.233%
SQLITE_OMIT_TEMPDB | 403200 | -877 | -0.217%
SQLITE_OMIT_BTREECOUNT | 403301 | -776 | -0.192%
SQLITE_OMIT_LOCALTIME | 403307 | -770 | -0.191%
SQLITE_OMIT_COMPILEOPTION_DIAGS | 403309 | -768 | -0.190%
SQLITE_OMIT_FLAG_PRAGMAS | 403441 | -636 | -0.157%
SQLITE_OMIT_QUICKBALANCE | 403455 | -622 | -0.154%
SQLITE_OMIT_CAST | 403457 | -620 | -0.153%
SQLITE_OMIT_CHECK | 403501 | -576 | -0.143%
SQLITE_OMIT_MEMORYDB | 403555 | -522 | -0.129%
SQLITE_OMIT_BLOB_LITERAL | 403619 | -458 | -0.113%
SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS | 403748 | -329 | -0.081%
SQLITE_OMIT_LOOKASIDE | 403753 | -324 | -0.080%
SQLITE_OMIT_AUTOINIT | 403759 | -318 | -0.079%
SQLITE_DISABLE_DIRSYNC | 403782 | -295 | -0.073%
SQLITE_OMIT_DECLTYPE | 403794 | -283 | -0.070%
SQLITE_OMIT_DEPRECATED | 403794 | -283 | -0.070%
SQLITE_OMIT_BETWEEN_OPTIMIZATION | 403929 | -148 | -0.037%
SQLITE_OMIT_PROGRESS_CALLBACK | 403957 | -120 | -0.030%
SQLITE_OMIT_TRUNCATE_OPTIMIZATION | 403984 | -93 | -0.023%
SQLITE_OMIT_TCL_VARIABLE | 404003 | -74 | -0.018%
Baseline SQLite Library Size | 404077 | 0 | 0.000%
SQLITE_DISABLE_LFS | 404105 | +28 | +0.007%
SQLITE_ENABLE_IOTRACE | 404108 | +31 | +0.008%
SQLITE_OMIT_AUTORESET | 404143 | +66 | +0.016%
SQLITE_ENABLE_MEMORY_MANAGEMENT | 404348 | +271 | +0.067%
SQLITE_ENABLE_UPDATE_DELETE_LIMIT | 404780 | +703 | +0.174%
SQLITE_ENABLE_COLUMN_METADATA | 405198 | +1121 | +0.277%
SQLITE_ENABLE_UNLOCK_NOTIFY | 405371 | +1294 | +0.320%
SQLITE_ENABLE_ATOMIC_WRITE | 405426 | +1349 | +0.334%
SQLITE_ENABLE_MEMSYS5 | 406290 | +2213 | +0.548%
SQLITE_ENABLE_MEMSYS3 | 406927 | +2850 | +0.705%
SQLITE_OMIT_WSD | 408536 | +4459 | +1.104%
SQLITE_ENABLE_STAT3 | 410352 | +6275 | +1.553%
SQLITE_ENABLE_RTREE | 422554 | +18477 | +4.573%
SQLITE_ENABLE_FTS3 | 467173 | +63096 | +15.615%
SQLITE_ENABLE_FTS4 | 467185 | +63108 | +15.618%


SQLite Foreign Key Support

Choose any three.
About Sitemap Documentation Download License News Support
SQLite Foreign Key Support
Table Of Contents
1. Introduction to Foreign Key Constraints
2. Enabling Foreign Key Support
3. Required and Suggested Database Indexes
4. Advanced Foreign Key Constraint Features
4.1. Composite Foreign Key Constraints
4.2. Deferred Foreign Key Constraints
4.3. ON DELETE and ON UPDATE Actions
5. CREATE, ALTER and DROP TABLE commands
6. Limits and Unsupported Features

Overview

This document describes the support for SQL foreign key constraints introduced in SQLite version 3.6.19.

The first section introduces the concept of an SQL foreign key by example and defines the terminology used for the remainder of the document. Section 2 describes the steps an application must take in order to enable foreign key constraints in SQLite (it is disabled by default). The next section, section 3, describes the indexes that the user must create in order to use foreign key constraints, and those that should be created in order for foreign key constraints to function efficiently. Section 4 describes the advanced foreign key related features supported by SQLite and section 5 describes the way the ALTER and DROP TABLE commands are enhanced to support foreign key constraints. Finally, section 6 enumerates the missing features and limits of the current implementation.

This document does not contain a full description of the syntax used to create foreign key constraints in SQLite. This may be found as part of the documentation for the CREATE TABLE statement.

1. Introduction to Foreign Key Constraints

SQL foreign key constraints are used to enforce "exists" relationships between tables. For example, consider a database schema created using the following SQL commands:

CREATE TABLE artist(
  artistid    INTEGER PRIMARY KEY,
  artistname  TEXT
);
CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER     -- Must map to an artist.artistid!
);

The applications using this database are entitled to assume that for each row in the track table there exists a corresponding row in the artist table. After all, the comment in the declaration says so. Unfortunately, if a user edits the database using an external tool or if there is a bug in an application, rows might be inserted into the track table that do not correspond to any row in the artist table. Or rows might be deleted from the artist table, leaving orphaned rows in the track table that do not correspond to any of the remaining rows in artist. This might cause the application or applications to malfunction later on, or at least make coding the application more difficult.

One solution is to add an SQL foreign key constraint to the database schema to enforce the relationship between the artist and track table. To do so, a foreign key definition may be added by modifying the declaration of the track table to the following:

CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER,
  FOREIGN KEY(trackartist) REFERENCES artist(artistid)
);

This way, the constraint is enforced by SQLite. Attempting to insert a row into the track table that does not correspond to any row in the artist table will fail, as will attempting to delete a row from the artist table when there exist dependent rows in the track table There is one exception: if the foreign key column in the track table is NULL, then no corresponding entry in the artist table is required. Expressed in SQL, this means that for every row in the track table, the following expression evaluates to true:

trackartist IS NULL OR EXISTS(SELECT 1 FROM artist WHERE artistid=trackartist)

Tip: If the application requires a stricter relationship between artist and track, where NULL values are not permitted in the trackartist column, simply add the appropriate "NOT NULL" constraint to the schema.

There are several other ways to add an equivalent foreign key declaration to a CREATE TABLE statement. Refer to the CREATE TABLE documentation for details.

The following SQLite command-line session illustrates the effect of the foreign key constraint added to the track table:

sqlite> SELECT * FROM artist;
artistid  artistname
--------  -----------------
1         Dean Martin
2         Frank Sinatra

sqlite> SELECT * FROM track;
trackid  trackname          trackartist
-------  -----------------  -----------
11       That's Amore       1
12       Christmas Blues    1
13       My Way             2

sqlite> -- This fails because the value inserted into the trackartist column (3)
sqlite> -- does not correspond to row in the artist table.
sqlite> INSERT INTO track VALUES(14, 'Mr. Bojangles', 3);
SQL error: foreign key constraint failed

sqlite> -- This succeeds because a NULL is inserted into trackartist. A
sqlite> -- corresponding row in the artist table is not required in this case.
sqlite> INSERT INTO track VALUES(14, 'Mr. Bojangles', NULL);

sqlite> -- Trying to modify the trackartist field of the record after it has
sqlite> -- been inserted does not work either, since the new value of trackartist (3)
sqlite> -- Still does not correspond to any row in the artist table.
sqlite> UPDATE track SET trackartist = 3 WHERE trackname = 'Mr. Bojangles';
SQL error: foreign key constraint failed

sqlite> -- Insert the required row into the artist table. It is then possible to
sqlite> -- update the inserted row to set trackartist to 3 (since a corresponding
sqlite> -- row in the artist table now exists).
sqlite> INSERT INTO artist VALUES(3, 'Sammy Davis Jr.');
sqlite> UPDATE track SET trackartist = 3 WHERE trackname = 'Mr. Bojangles';

sqlite> -- Now that "Sammy Davis Jr." (artistid = 3) has been added to the database,
sqlite> -- it is possible to INSERT new tracks using this artist without violating
sqlite> -- the foreign key constraint:
sqlite> INSERT INTO track VALUES(15, 'Boogie Woogie', 3);

As you would expect, it is not possible to manipulate the database to a state that violates the foreign key constraint by deleting or updating rows in the artist table either:

sqlite> -- Attempting to delete the artist record for "Frank Sinatra" fails, since
sqlite> -- the track table contains a row that refer to it.
sqlite> DELETE FROM artist WHERE artistname = 'Frank Sinatra';
SQL error: foreign key constraint failed

sqlite> -- Delete all the records from the track table that refer to the artist
sqlite> -- "Frank Sinatra". Only then is it possible to delete the artist.
sqlite> DELETE FROM track WHERE trackname = 'My Way';
sqlite> DELETE FROM artist WHERE artistname = 'Frank Sinatra';

sqlite> -- Try to update the artistid of a row in the artist table while there
sqlite> -- exists records in the track table that refer to it.
sqlite> UPDATE artist SET artistid=4 WHERE artistname = 'Dean Martin';
SQL error: foreign key constraint failed

sqlite> -- Once all the records that refer to a row in the artist table have
sqlite> -- been deleted, it is possible to modify the artistid of the row.
sqlite> DELETE FROM track WHERE trackname IN('That''s Amore', 'Christmas Blues');
sqlite> UPDATE artist SET artistid=4 WHERE artistname = 'Dean Martin';

SQLite uses the following terminology:

  • The parent table is the table that a foreign key constraint refers to. The parent table in the example in this section is the artist table. Some books and articles refer to this as the referenced table, which is arguably more correct, but tends to lead to confusion.

  • The child table is the table that a foreign key constraint is applied to and the table that contains the REFERENCES clause. The example in this section uses the track table as the child table. Other books and articles refer to this as the referencing table.

  • The parent key is the column or set of columns in the parent table that the foreign key constraint refers to. This is normally, but not always, the primary key of the parent table. The parent key must be a named column or columns in the parent table, not the rowid.

  • The child key is the column or set of columns in the child table that are constrained by the foreign key constraint and which hold the REFERENCES clause.

The foreign key constraint is satisfied if for each row in the child table either one or more of the child key columns are NULL, or there exists a row in the parent table for which each parent key column contains a value equal to the value in its associated child key column.

In the above paragraph, the term "equal" means equal when values are compared using the rules specified here. The following clarifications apply:

  • When comparing text values, the collating sequence associated with the parent key column is always used.

  • When comparing values, if the parent key column has an affinity, then that affinity is applied to the child key value before the comparison is performed.

2. Enabling Foreign Key Support

In order to use foreign key constraints in SQLite, the library must be compiled with neither SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER defined. If SQLITE_OMIT_TRIGGER is defined but SQLITE_OMIT_FOREIGN_KEY is not, then SQLite behaves as it did prior to version 3.6.19 - foreign key definitions are parsed and may be queried using PRAGMA foreign_key_list, but foreign key constraints are not enforced. The PRAGMA foreign_keys command is a no-op in this configuration. If OMIT_FOREIGN_KEY is defined, then foreign key definitions cannot even be parsed (attempting to specify a foreign key definition is a syntax error).

Assuming the library is compiled with foreign key constraints enabled, it must still be enabled by the application at runtime, using the PRAGMA foreign_keys command. For example:

sqlite> PRAGMA foreign_keys = ON;

Foreign key constraints are disabled by default (for backwards compatibility), so must be enabled separately for each database connection separately. (Note, however, that future releases of SQLite might change so that foreign key constraints enabled by default. Careful developers will not make any assumptions about whether or not foreign keys are enabled by default but will instead enable or disable them as necessary.) The application can can also use a PRAGMA foreign_keys statement to determine if foreign keys are currently enabled. The following command-line session demonstrates this:

sqlite> PRAGMA foreign_keys;
0
sqlite> PRAGMA foreign_keys = ON;
sqlite> PRAGMA foreign_keys;
1
sqlite> PRAGMA foreign_keys = OFF;
sqlite> PRAGMA foreign_keys;
0

Tip: If the command "PRAGMA foreign_keys" returns no data instead of a single row containing "0" or "1", then the version of SQLite you are using does not support foreign keys (either because it is older than 3.6.19 or because it was compiled with SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER defined).

It is not possible to enable or disable foreign key constraints in the middle of a multi-statement transaction (when SQLite is not in autocommit mode). Attempting to do so does not return an error; it simply has no effect.

3. Required and Suggested Database Indexes

Usually, the parent key of a foreign key constraint is the primary key of the parent table. If they are not the primary key, then the parent key columns must be collectively subject to a UNIQUE constraint or have a UNIQUE index. If the parent key columns have a UNIQUE index, then that index must use the collation sequences that are specified in the CREATE TABLE statement for the parent table. For example,

CREATE TABLE parent(a PRIMARY KEY, b UNIQUE, c, d, e, f);
CREATE UNIQUE INDEX i1 ON parent(c, d);
CREATE INDEX i2 ON parent(e);
CREATE UNIQUE INDEX i3 ON parent(f COLLATE nocase);

CREATE TABLE child1(f, g REFERENCES parent(a));                        -- Ok
CREATE TABLE child2(h, i REFERENCES parent(b));                        -- Ok
CREATE TABLE child3(j, k, FOREIGN KEY(j, k) REFERENCES parent(c, d));  -- Ok
CREATE TABLE child4(l, m REFERENCES parent(e));                        -- Error!
CREATE TABLE child5(n, o REFERENCES parent(f));                        -- Error!
CREATE TABLE child6(p, q, FOREIGN KEY(p, q) REFERENCES parent(b, c));  -- Error!
CREATE TABLE child7(r REFERENCES parent(c));                           -- Error!

The foreign key constraints created as part of tables child1, child2 and child3 are all fine. The foreign key declared as part of table child4 is an error because even though the parent key column is indexed, the index is not UNIQUE. The foreign key for table child5 is an error because even though the parent key column has a unique index, the index uses a different collating sequence. Tables child6 and child7 are incorrect because while both have UNIQUE indices on their parent keys, the keys are not an exact match to the columns of a single UNIQUE index.

If the database schema contains foreign key errors that require looking at more than one table definition to identify, then those errors are not detected when the tables are created. Instead, such errors prevent the application from preparing SQL statements that modify the content of the child or parent tables in ways that use the foreign keys. Errors reported when content is changed are "DML errors" and errors reported when the schema is changed are "DDL errors". So, in other words, misconfigured foreign key constraints that require looking at both the child and parent are DML errors. The English language error message for foreign key DML errors is usually "foreign key mismatch" but can also be "no such table" if the parent table does not exist. Foreign key DML errors are may be reported if:

  • The parent table does not exist, or
  • The parent key columns named in the foreign key constraint do not exist, or
  • The parent key columns named in the foreign key constraint are not the primary key of the parent table and are not subject to a unique constraint using collating sequence specified in the CREATE TABLE, or
  • The child table references the primary key of the parent without specifying the primary key columns and the number of primary key columns in the parent do not match the number of child key columns.

The last bullet above is illustrated by the following:

CREATE TABLE parent2(a, b, PRIMARY KEY(a,b));

CREATE TABLE child8(x, y, FOREIGN KEY(x,y) REFERENCES parent2);        -- Ok
CREATE TABLE child9(x REFERENCES parent2);                             -- Error!
CREATE TABLE child10(x,y,z, FOREIGN KEY(x,y,z) REFERENCES parent2);    -- Error!

By contrast, if foreign key errors can be recognized simply by looking at the definition of the child table and without having to consult the parent table definition, then the CREATE TABLE statement for the child table fails. Because the error occurs during a schema change, this is a DDL error. Foreign key DDL errors are reported regardless of whether or not foreign key constraints are enabled when the table is created.

Indices are not required for child key columns but they are almost always beneficial. Returning to the example in section 1, each time an application deletes a row from the artist table (the parent table), it performs the equivalent of the following SELECT statement to search for referencing rows in the track table (the child table).

SELECT rowid FROM track WHERE trackartist = ?

where ? in the above is replaced with the value of the artistid column of the record being deleted from the artist table (recall that the trackartist column is the child key and the artistid column is the parent key). Or, more generally:

SELECT rowid FROM <child-table> WHERE <child-key> = :parent_key_value

If this SELECT returns any rows at all, then SQLite concludes that deleting the row from the parent table would violate the foreign key constraint and returns an error. Similar queries may be run if the content of the parent key is modified or a new row is inserted into the parent table. If these queries cannot use an index, they are forced to do a linear scan of the entire child table. In a non-trivial database, this may be prohibitively expensive.

So, in most real systems, an index should be created on the child key columns of each foreign key constraint. The child key index does not have to be (and usually will not be) a UNIQUE index. Returning again to the example in section 1, the complete database schema for efficient implementation of the foreign key constraint might be:

CREATE TABLE artist(
  artistid    INTEGER PRIMARY KEY,
  artistname  TEXT
);
CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER REFERENCES artist
);
CREATE INDEX trackindex ON track(trackartist);

The block above uses a shorthand form to create the foreign key constraint. Attaching a "REFERENCES <parent-table>" clause to a column definition creates a foreign key constraint that maps the column to the primary key of <parent-table>. Refer to the CREATE TABLE documentation for further details.

4. Advanced Foreign Key Constraint Features

4.1. Composite Foreign Key Constraints

A composite foreign key constraint is one where the child and parent keys are both composite keys. For example, consider the following database schema:

CREATE TABLE album(
  albumartist TEXT,
  albumname TEXT,
  albumcover BINARY,
  PRIMARY KEY(albumartist, albumname)
);

CREATE TABLE song(
  songid     INTEGER,
  songartist TEXT,
  songalbum TEXT,
  songname   TEXT,
  FOREIGN KEY(songartist, songalbum) REFERENCES album(albumartist, albumname)
);

In this system, each entry in the song table is required to map to an entry in the album table with the same combination of artist and album.

Parent and child keys must have the same cardinality. In SQLite, if any of the child key columns (in this case songartist and songalbum) are NULL, then there is no requirement for a corresponding row in the parent table.

4.2. Deferred Foreign Key Constraints

Each foreign key constraint in SQLite is classified as either immediate or deferred. Foreign key constraints are immediate by default. All the foreign key examples presented so far have been of immediate foreign key constraints.

If a statement modifies the contents of the database so that an immediate foreign key constraint is in violation at the conclusion the statement, an exception is thrown and the effects of the statement are reverted. By contrast, if a statement modifies the contents of the database such that a deferred foreign key constraint is violated, the violation is not reported immediately. Deferred foreign key constraints are not checked until the transaction tries to COMMIT. For as long as the user has an open transaction, the database is allowed to exist in a state that violates any number of deferred foreign key constraints. However, COMMIT will fail as long as foreign key constraints remain in violation.

If the current statement is not inside an explicit transaction (a BEGIN/COMMIT/ROLLBACK block), then an implicit transaction is committed as soon as the statement has finished executing. In this case deferred constraints behave the same as immediate constraints.

To mark a foreign key constraint as deferred, its declaration must include the following clause:

DEFERRABLE INITIALLY DEFERRED                -- A deferred foreign key constraint

The full syntax for specifying foreign key constraints is available as part of the CREATE TABLE documentation. Replacing the phrase above with any of the following creates an immediate foreign key constraint.

NOT DEFERRABLE INITIALLY DEFERRED            -- An immediate foreign key constraint
NOT DEFERRABLE INITIALLY IMMEDIATE           -- An immediate foreign key constraint
NOT DEFERRABLE                               -- An immediate foreign key constraint
DEFERRABLE INITIALLY IMMEDIATE               -- An immediate foreign key constraint
DEFERRABLE                                   -- An immediate foreign key constraint

The following example illustrates the effect of using a deferred foreign key constraint.

-- Database schema. Both tables are initially empty.
CREATE TABLE artist(
  artistid    INTEGER PRIMARY KEY,
  artistname  TEXT
);
CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER REFERENCES artist(artistid) DEFERRABLE INITIALLY DEFERRED
);

sqlite3> -- If the foreign key constraint were immediate, this INSERT would
sqlite3> -- cause an error (since as there is no row in table artist with
sqlite3> -- artistid=5). But as the constraint is deferred and there is an
sqlite3> -- open transaction, no error occurs.
sqlite3> BEGIN;
sqlite3>   INSERT INTO track VALUES(1, 'White Christmas', 5);

sqlite3> -- The following COMMIT fails, as the database is in a state that
sqlite3> -- does not satisfy the deferred foreign key constraint. The
sqlite3> -- transaction remains open.
sqlite3> COMMIT;
SQL error: foreign key constraint failed

sqlite3> -- After inserting a row into the artist table with artistid=5, the
sqlite3> -- deferred foreign key constraint is satisfied. It is then possible
sqlite3> -- to commit the transaction without error.
sqlite3>   INSERT INTO artist VALUES(5, 'Bing Crosby');
sqlite3> COMMIT;

A nested savepoint transaction may be RELEASEd while the database is in a state that does not satisfy a deferred foreign key constraint. A transaction savepoint (a non-nested savepoint that was opened while there was not currently an open transaction), on the other hand, is subject to the same restrictions as a COMMIT - attempting to RELEASE it while the database is in such a state will fail.

If a COMMIT statement (or the RELEASE of a transaction SAVEPOINT) fails because the database is currently in a state that violates a deferred foreign key constraint and there are currently nested savepoints, the nested savepoints remain open.

4.3. ON DELETE and ON UPDATE Actions

Foreign key ON DELETE and ON UPDATE clauses are used to configure actions that take place when deleting rows from the parent table (ON DELETE), or modifying the parent key values of existing rows (ON UPDATE). A single foreign key constraint may have different actions configured for ON DELETE and ON UPDATE. Foreign key actions are similar to triggers in many ways.

The ON DELETE and ON UPDATE action associated with each foreign key in an SQLite database is one of "NO ACTION", "RESTRICT", "SET NULL", "SET DEFAULT" or "CASCADE". If an action is not explicitly specified, it defaults to "NO ACTION".

  • NO ACTION: Configuring "NO ACTION" means just that: when a parent key is modified or deleted from the database, no special action is taken.

  • RESTRICT: The "RESTRICT" action means that the application is prohibited from deleting (for ON DELETE RESTRICT) or modifying (for ON UPDATE RESTRICT) a parent key when there exists one or more child keys mapped to it. The difference between the effect of a RESTRICT action and normal foreign key constraint enforcement is that the RESTRICT action processing happens as soon as the field is updated - not at the end of the current statement as it would with an immediate constraint, or at the end of the current transaction as it would with a deferred constraint. Even if the foreign key constraint it is attached to is deferred, configuring a RESTRICT action causes SQLite to return an error immediately if a parent key with dependent child keys is deleted or modified.

  • SET NULL: If the configured action is "SET NULL", then when a parent key is deleted (for ON DELETE SET NULL) or modified (for ON UPDATE SET NULL), the child key columns of all rows in the child table that mapped to the parent key are set to contain SQL NULL values.

  • SET DEFAULT: The "SET DEFAULT" actions are similar to "SET NULL", except that each of the child key columns is set to contain the columns default value instead of NULL. Refer to the CREATE TABLE documentation for details on how default values are assigned to table columns.

  • CASCADE: A "CASCADE" action propagates the delete or update operation on the parent key to each dependent child key. For an "ON DELETE CASCADE" action, this means that each row in the child table that was associated with the deleted parent row is also deleted. For an "ON UPDATE CASCADE" action, it means that the values stored in each dependent child key are modified to match the new parent key values.

For example, adding an "ON UPDATE CASCADE" clause to the foreign key as shown below enhances the example schema from section 1 to allow the user to update the artistid (the parent key of the foreign key constraint) column without breaking referential integrity:

-- Database schema
CREATE TABLE artist(
  artistid    INTEGER PRIMARY KEY,
  artistname  TEXT
);
CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER REFERENCES artist(artistid) ON UPDATE CASCADE
);

sqlite> SELECT * FROM artist;
artistid  artistname
--------  -----------------
1         Dean Martin
2         Frank Sinatra

sqlite> SELECT * FROM track;
trackid  trackname          trackartist
-------  -----------------  -----------
11       That's Amore       1
12       Christmas Blues    1
13       My Way             2

sqlite> -- Update the artistid column of the artist record for "Dean Martin".
sqlite> -- Normally, this would raise a constraint, as it would orphan the two
sqlite> -- dependent records in the track table. However, the ON UPDATE CASCADE clause
sqlite> -- attached to the foreign key definition causes the update to "cascade"
sqlite> -- to the child table, preventing the foreign key constraint violation.
sqlite> UPDATE artist SET artistid = 100 WHERE artistname = 'Dean Martin';

sqlite> SELECT * FROM artist;
artistid  artistname
--------  -----------------
2         Frank Sinatra
100       Dean Martin

sqlite> SELECT * FROM track;
trackid  trackname          trackartist
-------  -----------------  -----------
11       That's Amore       100
12       Christmas Blues    100
13       My Way             2

Configuring an ON UPDATE or ON DELETE action does not mean that the foreign key constraint does not need to be satisfied. For example, if an "ON DELETE SET DEFAULT" action is configured, but there is no row in the parent table that corresponds to the default values of the child key columns, deleting a parent key while dependent child keys exist still causes a foreign key violation. For example:

-- Database schema
CREATE TABLE artist(
  artistid    INTEGER PRIMARY KEY,
  artistname  TEXT
);
CREATE TABLE track(
  trackid     INTEGER,
  trackname   TEXT,
  trackartist INTEGER DEFAULT 0 REFERENCES artist(artistid) ON DELETE SET DEFAULT
);

sqlite> SELECT * FROM artist;
artistid  artistname
--------  -----------------
3         Sammy Davis Jr.

sqlite> SELECT * FROM track;
trackid  trackname          trackartist
-------  -----------------  -----------
14       Mr. Bojangles      3

sqlite> -- Deleting the row from the parent table causes the child key
sqlite> -- value of the dependent row to be set to integer value 0. However, this
sqlite> -- value does not correspond to any row in the parent table. Therefore
sqlite> -- the foreign key constraint is violated and an is exception thrown.
sqlite> DELETE FROM artist WHERE artistname = 'Sammy Davis Jr.';
SQL error: foreign key constraint failed

sqlite> -- This time, the value 0 does correspond to a parent table row. And
sqlite> -- so the DELETE statement does not violate the foreign key constraint
sqlite> -- and no exception is thrown.
sqlite> INSERT INTO artist VALUES(0, 'Unknown Artist');
sqlite> DELETE FROM artist WHERE artistname = 'Sammy Davis Jr.';

sqlite> SELECT * FROM artist;
artistid  artistname
--------  -----------------
0         Unknown Artist

sqlite> SELECT * FROM track;
trackid  trackname          trackartist
-------  -----------------  -----------
14       Mr. Bojangles      0

Those familiar with SQLite triggers will have noticed that the "ON DELETE SET DEFAULT" action demonstrated in the example above is similar in effect to the following AFTER DELETE trigger:

CREATE TRIGGER on_delete_set_default AFTER DELETE ON artist BEGIN
  UPDATE child SET trackartist = 0 WHERE trackartist = old.artistid;
END;

Whenever a row in the parent table of a foreign key constraint is deleted, or when the values stored in the parent key column or columns are modified, the logical sequence of events is:

  1. Execute applicable BEFORE trigger programs,
  2. Check local (non foreign key) constraints,
  3. Update or delete the row in the parent table,
  4. Perform any required foreign key actions,
  5. Execute applicable AFTER trigger programs.

There is one important difference between ON UPDATE foreign key actions and SQL triggers. An ON UPDATE action is only taken if the values of the parent key are modified so that the new parent key values are not equal to the old. For example:

-- Database schema
CREATE TABLE parent(x PRIMARY KEY);
CREATE TABLE child(y REFERENCES parent ON UPDATE SET NULL);

sqlite> SELECT * FROM parent;
x
----
key

sqlite> SELECT * FROM child;
y
----
key

sqlite> -- Since the following UPDATE statement does not actually modify
sqlite> -- the parent key value, the ON UPDATE action is not performed and
sqlite> -- the child key value is not set to NULL.
sqlite> UPDATE parent SET x = 'key';
sqlite> SELECT IFNULL(y, 'null') FROM child;
y
----
key

sqlite> -- This time, since the UPDATE statement does modify the parent key
sqlite> -- value, the ON UPDATE action is performed and the child key is set
sqlite> -- to NULL.
sqlite> UPDATE parent SET x = 'key2';
sqlite> SELECT IFNULL(y, 'null') FROM child;
y
----
null

5. CREATE, ALTER and DROP TABLE commands

This section describes the way the CREATE TABLE, ALTER TABLE, and DROP TABLE commands interact with SQLite's foreign keys.

A CREATE TABLE command operates the same whether or not foreign key constraints are enabled. The parent key definitions of foreign key constraints are not checked when a table is created. There is nothing stopping the user from creating a foreign key definition that refers to a parent table that does not exist, or to parent key columns that do not exist or are not collectively bound by a PRIMARY KEY or UNIQUE constraint.

The ALTER TABLE command works differently in two respects when foreign key constraints are enabled:

  • It is not possible to use the "ALTER TABLE ... ADD COLUMN" syntax to add a column that includes a REFERENCES clause, unless the default value of the new column is NULL. Attempting to do so returns an error.

  • If an "ALTER TABLE ... RENAME TO" command is used to rename a table that is the parent table of one or more foreign key constraints, the definitions of the foreign key constraints are modified to refer to the parent table by its new name. The text of the child CREATE TABLE statement or statements stored in the sqlite_master table are modified to reflect the new parent table name.

If foreign key constraints are enabled when it is prepared, the DROP TABLE command performs an implicit DELETE to remove all rows from the table before dropping it. The implicit DELETE does not cause any SQL triggers to fire, but may invoke foreign key actions or constraint violations. If an immediate foreign key constraint is violated, the DROP TABLE statement fails and the table is not dropped. If a deferred foreign key constraint is violated, then an error is reported when the user attempts to commit the transaction if the foreign key constraint violations still exist at that point. Any "foreign key mismatch" errors encountered as part of an implicit DELETE are ignored.

The intent of these enhancements to the ALTER TABLE and DROP TABLE commands is to ensure that they cannot be used to create a database that contains foreign key violations, at least while foreign key constraints are enabled. There is one exception to this rule though. If a parent key is not subject to a PRIMARY KEY or UNIQUE constraint created as part of the parent table definition, but is subject to a UNIQUE constraint by virtue of an index created using the CREATE INDEX command, then the child table may be populated without causing a "foreign key mismatch" error. If the UNIQUE index is dropped from the database schema, then the parent table itself is dropped, no error will be reported. However the database may be left in a state where the child table of the foreign key constraint contains rows that do not refer to any parent table row. This case can be avoided if all parent keys in the database schema are constrained by PRIMARY KEY or UNIQUE constraints added as part of the parent table definition, not by external UNIQUE indexes.

The properties of the DROP TABLE and ALTER TABLE commands described above only apply if foreign keys are enabled. If the user considers them undesirable, then the workaround is to use PRAGMA foreign_keys to disable foreign key constraints before executing the DROP or ALTER TABLE command. Of course, while foreign key constraints are disabled, there is nothing to stop the user from violating foreign key constraints and thus creating an internally inconsistent database.

6. Limits and Unsupported Features

This section lists a few limitations and omitted features that are not mentioned elsewhere.

  1. No support for the MATCH clause. According to SQL92, a MATCH clause may be attached to a composite foreign key definition to modify the way NULL values that occur in child keys are handled. If "MATCH SIMPLE" is specified, then a child key is not required to correspond to any row of the parent table if one or more of the child key values are NULL. If "MATCH FULL" is specified, then if any of the child key values is NULL, no corresponding row in the parent table is required, but all child key values must be NULL. Finally, if the foreign key constraint is declared as "MATCH PARTIAL" and one of the child key values is NULL, there must exist at least one row in the parent table for which the non-NULL child key values match the parent key values.

    SQLite parses MATCH clauses (i.e. does not report a syntax error if you specify one), but does not enforce them. All foreign key constraints in SQLite are handled as if MATCH SIMPLE were specified.

  2. No support for switching constraints between deferred and immediate mode. Many systems allow the user to toggle individual foreign key constraints between deferred and immediate mode at runtime (for example using the Oracle "SET CONSTRAINT" command). SQLite does not support this. In SQLite, a foreign key constraint is permanently marked as deferred or immediate when it is created.

  3. Recursion limit on foreign key actions. The SQLITE_MAX_TRIGGER_DEPTH and SQLITE_LIMIT_TRIGGER_DEPTH settings determine the maximum allowable depth of trigger program recursion. For the purposes of these limits, foreign key actions are considered trigger programs. The PRAGMA recursive_triggers setting does not not affect the operation of foreign key actions. It is not possible to disable recursive foreign key actions.


File Format Changes in SQLite

Every effort is made to keep SQLite fully backwards compatible from one release to the next. Rarely, however, some enhancements or bug fixes may require a change to the underlying file format. When this happens and you must convert the contents of your databases into a portable ASCII representation using the old version of the library then reload the data using the new version of the library.

You can tell if you should reload your databases by comparing the version numbers of the old and new libraries. If the first digit of the version number is different, then a reload of the database will be required. If the second digit changes, newer versions of SQLite will be able to read and write older database files, but older versions of the library may have difficulty reading or writing newer database files. For example, upgrading from version 2.8.14 to 3.0.0 requires a reload. Going from version 3.0.8 to 3.1.0 is backwards compatible but not necessarily forwards compatible.

The following table summarizes the SQLite file format changes that have occurred since version 1.0.0:

Version Change | Approx. Date | Description Of File Format Change
1.0.32 to 2.0.0 | 2001-Sep-20 | Version 1.0.X of SQLite used the GDBM library as its backend interface to the disk. Beginning in version 2.0.0, GDBM was replaced by a custom B-Tree library written especially for SQLite. The new B-Tree backend is twice as fast as GDBM, supports atomic commits and rollback, and stores an entire database in a single disk file instead using a separate file for each table as GDBM does. The two file formats are not even remotely similar.
2.0.8 to 2.1.0 2001-Nov-12 The same basic B-Tree format is used but the details of the index keys were changed in order to provide better query optimization opportunities. Some of the headers were also changed in order to increase the maximum size of a row from 64KB to 24MB.

This change is an exception to the version number rule described above in that it is neither forwards or backwards compatible. A complete reload of the database is required. This is the only exception.

2.1.7 to 2.2.0 2001-Dec-21 Beginning with version 2.2.0, SQLite no longer builds an index for an INTEGER PRIMARY KEY column. Instead, it uses that column as the actual B-Tree key for the main table.

Version 2.2.0 and later of the library will automatically detect when it is reading a 2.1.x database and will disable the new INTEGER PRIMARY KEY feature. In other words, version 2.2.x is backwards compatible to version 2.1.x. But version 2.1.x is not forward compatible with version 2.2.x. If you try to open a 2.2.x database with an older 2.1.x library and that database contains an INTEGER PRIMARY KEY, you will likely get a coredump. If the database schema does not contain any INTEGER PRIMARY KEYs, then the version 2.1.x and version 2.2.x database files will be identical and completely interchangeable.

2.2.5 to 2.3.0 | 2002-Jan-30 | Beginning with version 2.3.0, SQLite supports some additional syntax (the "ON CONFLICT" clause) in the CREATE TABLE and CREATE INDEX statements that are stored in the SQLITE_MASTER table. If you create a database that contains this new syntax, then try to read that database using version 2.2.5 or earlier, the parser will not understand the new syntax and you will get an error. Otherwise, databases for 2.2.x and 2.3.x are interchangeable.
2.3.3 to 2.4.0 | 2002-Mar-10 | Beginning with version 2.4.0, SQLite added support for views. Information about views is stored in the SQLITE_MASTER table. If an older version of SQLite attempts to read a database that contains VIEW information in the SQLITE_MASTER table, the parser will not understand the new syntax and initialization will fail. Also, the way SQLite keeps track of unused disk blocks in the database file changed slightly. If an older version of SQLite attempts to write a database that was previously written by version 2.4.0 or later, then it may leak disk blocks.
2.4.12 to 2.5.0 | 2002-Jun-17 | Beginning with version 2.5.0, SQLite added support for triggers. Information about triggers is stored in the SQLITE_MASTER table. If an older version of SQLite attempts to read a database that contains a CREATE TRIGGER in the SQLITE_MASTER table, the parser will not understand the new syntax and initialization will fail.
2.5.6 to 2.6.0 2002-July-17 A design flaw in the layout of indices required a file format change to correct. This change appeared in version 2.6.0.

If you use version 2.6.0 or later of the library to open a database file that was originally created by version 2.5.6 or earlier, an attempt to rebuild the database into the new format will occur automatically. This can take some time for a large database. (Allow 1 or 2 seconds per megabyte of database under Unix - longer under Windows.) This format conversion is irreversible. It is strongly suggested that you make a backup copy of older database files prior to opening them with version 2.6.0 or later of the library, in case there are errors in the format conversion logic.

Version 2.6.0 or later of the library cannot open read-only database files from version 2.5.6 or earlier, since read-only files cannot be upgraded to the new format.
2.6.3 to 2.7.0 2002-Aug-13

Beginning with version 2.7.0, SQLite understands two different datatypes: text and numeric. Text data sorts in memcmp() order. Numeric data sorts in numerical order if it looks like a number, or in memcmp() order if it does not.

When SQLite version 2.7.0 or later opens a 2.6.3 or earlier database, it assumes all columns of all tables have type "numeric". For 2.7.0 and later databases, columns have type "text" if their datatype string contains the substrings "char" or "clob" or "blob" or "text". Otherwise they are of type "numeric".

Because "text" columns have a different sort order from numeric, indices on "text" columns occur in a different order for version 2.7.0 and later database. Hence version 2.6.3 and earlier of SQLite will be unable to read a 2.7.0 or later database. But version 2.7.0 and later of SQLite will read earlier databases.
2.7.6 to 2.8.0 2003-Feb-14

Version 2.8.0 introduces a change to the format of the rollback journal file. The main database file format is unchanged. Versions 2.7.6 and earlier can read and write 2.8.0 databases and vice versa. Version 2.8.0 can rollback a transaction that was started by version 2.7.6 and earlier. But version 2.7.6 and earlier cannot rollback a transaction started by version 2.8.0 or later.

The only time this would ever be an issue is when you have a program using version 2.8.0 or later that crashes with an incomplete transaction, then you try to examine the database using version 2.7.6 or earlier. The 2.7.6 code will not be able to read the journal file and thus will not be able to rollback the incomplete transaction to restore the database.
2.8.14 to 3.0.0 2004-Jun-18

Version 3.0.0 is a major upgrade for SQLite that incorporates support for UTF-16, BLOBs, and a more compact encoding that results in database files that are typically 25% to 50% smaller. The new file format is very different and is completely incompatible with the version 2 file format.
3.0.8 to 3.1.0 2005-Jan-21

Version 3.1.0 adds support for autovacuum mode. Prior versions of SQLite will be able to read an autovacuumed database but will not be able to write it. If autovaccum is disabled (which is the default condition) then databases are fully forwards and backwards compatible.
3.1.6 to 3.2.0 2005-Mar-19

Version 3.2.0 adds support for the ALTER TABLE ADD COLUMN command. A database that has been modified by this command can not be read by a version of SQLite prior to 3.1.4. Running VACUUM after the ALTER TABLE restores the database to a format such that it can be read by earlier SQLite versions.
3.2.8 to 3.3.0 2006-Jan-10

Version 3.3.0 adds support for descending indices and uses a new encoding for boolean values that requires less disk space. Version 3.3.0 can read and write database files created by prior versions of SQLite. But prior versions of SQLite will not be able to read or write databases created by Version 3.3.0

If you need backwards and forwards compatibility, you can compile with -DSQLITE_DEFAULT_FILE_FORMAT=1. Or at runtime you can say "PRAGMA legacy_file_format=ON" prior to creating a new database file

Once a database file is created, its format is fixed. So a database file created by SQLite 3.2.8 and merely modified by version 3.3.0 or later will retain the old format. Except, the VACUUM command recreates the database so running VACUUM on 3.3.0 or later will change the file format to the latest edition.
3.3.6 to 3.3.7 2006-Aug-12

The previous file format change has caused so much grief that the default behavior has been changed back to the original file format. This means that DESC option on indices is ignored by default that the more efficient encoding of boolean values is not used. In that way, older versions of SQLite can read and write databases created by newer versions. If the new features are desired, they can be enabled using pragma: "PRAGMA legacy_file_format=OFF".

To be clear: both old and new file formats continue to be understood and continue to work. But the old file format is used by default instead of the new. This might change again in some future release - we may go back to generating the new file format by default - but probably not until all users have upgraded to a version of SQLite that will understand the new file format. That might take several years.
3.4.2 to 3.5.0 2007-Sep-3

The design of the OS interface layer was changed for release 3.5.0. Applications that implemented a custom OS interface will need to be modified in order to upgrade. There are also some subtly different semantics a few obscure APIs. An article is available which describing the changes in detail.

The on-disk file format is unchanged.
3.5.9 to 3.6.0 2008-July-16

There are minor tweaks to the new OS interface layer that was added in version 3.5.0. Applications that implemented a custom OS interface will need to be adjusted. An article is available which describing the changes in detail.

The on-disk file format is unchanged.

To perform a database reload, have ready versions of the sqlite command-line utility for both the old and new version of SQLite. Call these two executables "sqlite-old" and "sqlite-new". Suppose the name of your old database is "old.db" and you want to create a new database with the same information named "new.db". The command to do this is as follows:

sqlite-old old.db .dump | sqlite-new new.db


SQLite FTS3 and FTS4 Extensions

Choose any three.
About Sitemap Documentation Download License News Support
SQLite FTS3 and FTS4 Extensions
Table Of Contents
1. Introduction to FTS3 and FTS4
1.1. Differences between FTS3 and FTS4
1.2. Creating and Destroying FTS Tables
1.3. Populating FTS Tables
1.4. Simple FTS Queries
1.5. Summary
2. Compiling and Enabling FTS3 and FTS4
3. Full-text Index Queries
3.1. Set Operations Using The Enhanced Query Syntax
3.2. Set Operations Using The Standard Query Syntax
4. Auxiliary Functions - Snippet, Offsets and Matchinfo
4.1. The Offsets Function
4.2. The Snippet Function
4.3. The Matchinfo Function
5. Fts4aux - Direct Access to the Full-Text Index
6. FTS4 Options
6.1. Compress/Uncompress
6.2. Prefix
7. Tokenizers
7.1. Custom (User Implemented) Tokenizers
8. Data Structures
8.1. Variable Length Integer (varint) Format
8.2. Segment B-Tree Format
8.2.1. Segment B-Tree Leaf Nodes
8.2.2. Segment B-Tree Interior Nodes
8.3. Doclist Format
Appendix A: Search Application Tips

Overview

FTS3 and FTS4 are an SQLite virtual table modules that allows users to perform full-text searches on a set of documents. The most common (and effective) way to describe full-text searches is "what Google, Yahoo and Altavista do with documents placed on the World Wide Web". Users input a term, or series of terms, perhaps connected by a binary operator or grouped together into a phrase, and the full-text query system finds the set of documents that best matches those terms considering the operators and groupings the user has specified. This article describes the deployment and usage of FTS3 and FTS4.

FTS1 and FTS2 are obsolete full-text search modules for SQLite. There are known issues with these older modules and their use should be avoided. Portions of the original FTS3 code were contributed to the SQLite project by Scott Hess of Google. It is now developed and maintained as part of SQLite.

1. Introduction to FTS3 and FTS4

The FTS3 and FTS4 extension modules allows users to create special tables with a built-in full-text index (hereafter "FTS tables"). The full-text index allows the user to efficiently query the database for all rows that contain one or more words (hereafter "tokens"), even if the table contains many large documents.

For example, if each of the 517430 documents in the "Enron E-Mail Dataset" is inserted into both an FTS table and an ordinary SQLite table created using the following SQL script:

CREATE VIRTUAL TABLE enrondata1 USING fts3(content TEXT);     /* FTS3 table */
CREATE TABLE enrondata2(content TEXT);                        /* Ordinary table */

Then either of the two queries below may be executed to find the number of documents in the database that contain the word "linux" (351). Using one desktop PC hardware configuration, the query on the FTS3 table returns in approximately 0.03 seconds, versus 22.5 for querying the ordinary table.

SELECT count(*) FROM enrondata1 WHERE content MATCH 'linux';  /* 0.03 seconds */
SELECT count(*) FROM enrondata2 WHERE content LIKE '%linux%'; /* 22.5 seconds */

Of course, the two queries above are not entirely equivalent. For example the LIKE query matches rows that contain terms such as "linuxophobe" or "EnterpriseLinux" (as it happens, the Enron E-Mail Dataset does not actually contain any such terms), whereas the MATCH query on the FTS3 table selects only those rows that contain "linux" as a discrete token. Both searches are case-insensitive. The FTS3 table consumes around 2006 MB on disk compared to just 1453 MB for the ordinary table. Using the same hardware configuration used to perform the SELECT queries above, the FTS3 table took just under 31 minutes to populate, versus 25 for the ordinary table.

1.1. Differences between FTS3 and FTS4

FTS3 and FTS4 are nearly identical. They share most of their code in common, and their interfaces are the same. The differences are:

  • FTS4 contains query performance optimizations that may significantly improve the performance of full-text queries that contain terms that are very common (present in a large percentage of table rows).

  • FTS4 supports some additional options that may used with the matchinfo() function.

  • Because it stores extra information on disk in two new shadow tables in order to support the performance optimizations and extra matchinfo() options, FTS4 tables may consume more disk space than the equivalent table created using FTS3. Usually the overhead is 1-2% or less, but may be as high as 10% if the documents stored in the FTS table are very small. The overhead may be reduced by specifying the directive "matchinfo=fts3" as part of the FTS4 table declaration, but this comes at the expense of sacrificing some of the extra supported matchinfo() options.

  • FTS4 provides hooks (the compress and uncompress options) allowing data to be stored in a compressed form, reducing disk usage and IO.

FTS4 is an enhancement to FTS3. FTS3 has been available since SQLite version 3.5.0 in 2007-09-04. The enhancements for FTS4 were added with SQLite version 3.7.4 on 2010-12-08.

Which module, FTS3 or FTS4, should you use in your application? FTS4 is sometimes significantly faster than FTS3, even orders of magnitude faster depending on the query, though in the common case the performance of the two modules is similar. FTS4 also offers the enhanced matchinfo() outputs which can be useful in ranking the results of a MATCH operation. On the other hand, in the absence of a matchinfo=fts3 directive FTS4 requires a little more disk space than FTS3, though only a percent of two in most cases.

For newer applications, FTS4 is recommended; though if compatibility with older versions of SQLite is important, then FTS3 will usually serve just as well.

1.2. Creating and Destroying FTS Tables

Like other virtual table types, new FTS tables are created using a CREATE VIRTUAL TABLE statement. The module name, which follows the USING keyword, is either "fts3" or "fts4". The virtual table module arguments may be left empty, in which case an FTS table with a single user-defined column named "content" is created. Alternatively, the module arguments may be passed a list of comma separated column names.

If column names are explicitly provided for the FTS table as part of the CREATE VIRTUAL TABLE statement, then a datatype name may be optionally specified for each column. This is pure syntactic sugar, the supplied typenames are not used by FTS or the SQLite core for any purpose. The same applies to any constraints specified along with an FTS column name - they are parsed but not used or recorded by the system in any way.

-- Create an FTS table named "data" with one column - "content":
CREATE VIRTUAL TABLE data USING fts3();

-- Create an FTS table named "pages" with three columns:
CREATE VIRTUAL TABLE pages USING fts4(title, keywords, body);

-- Create an FTS table named "mail" with two columns. Datatypes
-- and column constraints are specified along with each column. These
-- are completely ignored by FTS and SQLite.
CREATE VIRTUAL TABLE mail USING fts3(
  subject VARCHAR(256) NOT NULL,
  body TEXT CHECK(length(body)<10240)
);

As well as a list of columns, the module arguments passed to a CREATE VIRTUAL TABLE statement used to create an FTS table may be used to specify a tokenizer. This is done by specifying a string of the form "tokenize=<tokenizer name> <tokenizer args>" in place of a column name, where <tokenizer name> is the name of the tokenizer to use and <tokenizer args> is an optional list of whitespace separated qualifiers to pass to the tokenizer implementation. A tokenizer specification may be placed anywhere in the column list, but at most one tokenizer declaration is allowed for each CREATE VIRTUAL TABLE statement. See below for a detailed description of using (and, if necessary, implementing) a tokenizer.

-- Create an FTS table named "papers" with two columns that uses
-- the tokenizer "porter".
CREATE VIRTUAL TABLE papers USING fts3(author, document, tokenize=porter);

-- Create an FTS table with a single column - "content" - that uses
-- the "simple" tokenizer.
CREATE VIRTUAL TABLE data USING fts4(tokenize=simple);

-- Create an FTS table with two columns that uses the "icu" tokenizer.
-- The qualifier "en_AU" is passed to the tokenizer implementation
CREATE VIRTUAL TABLE names USING fts3(a, b, tokenize=icu en_AU);

FTS tables may be dropped from the database using an ordinary DROP TABLE statement. For example:

-- Create, then immediately drop, an FTS4 table.
CREATE VIRTUAL TABLE data USING fts4();
DROP TABLE data;

1.3. Populating FTS Tables

FTS tables are populated using INSERT, UPDATE and DELETE statements in the same way as ordinary SQLite tables are.

As well as the columns named by the user (or the "content" column if no module arguments were specified as part of the CREATE VIRTUAL TABLE statement), each FTS table has a "rowid" column. The rowid of an FTS table behaves in the same way as the rowid column of an ordinary SQLite table, except that the values stored in the rowid column of an FTS table remain unchanged if the database is rebuilt using the VACUUM command. For FTS tables, "docid" is allowed as an alias along with the usual "rowid", "oid" and "_oid_" identifiers. Attempting to insert or update a row with a docid value that already exists in the table is an error, just as it would be with an ordinary SQLite table.

There is one other subtle difference between "docid" and the normal SQLite aliases for the rowid column. Normally, if an INSERT or UPDATE statement assigns discrete values to two or more aliases of the rowid column, SQLite writes the rightmost of such values specified in the INSERT or UPDATE statement to the database. However, assigning a non-NULL value to both the "docid" and one or more of the SQLite rowid aliases when inserting or updating an FTS table is considered an error. See below for an example.

-- Create an FTS table
CREATE VIRTUAL TABLE pages USING fts4(title, body);

-- Insert a row with a specific docid value.
INSERT INTO pages(docid, title, body) VALUES(53, 'Home Page', 'SQLite is a software...');

-- Insert a row and allow FTS to assign a docid value using the same algorithm as
-- SQLite uses for ordinary tables. In this case the new docid will be 54,
-- one greater than the largest docid currently present in the table.
INSERT INTO pages(title, body) VALUES('Download', 'All SQLite source code...');

-- Change the title of the row just inserted.
UPDATE pages SET title = 'Download SQLite' WHERE rowid = 54;

-- Delete the entire table contents.
DELETE FROM pages;

-- The following is an error. It is not possible to assign non-NULL values to both
-- the rowid and docid columns of an FTS table.
INSERT INTO pages(rowid, docid, title, body) VALUES(1, 2, 'A title', 'A document body');

To support full-text queries, FTS maintains an inverted index that maps from each unique term or word that appears in the dataset to the locations in which it appears within the table contents. For the curious, a complete description of the data structure used to store this index within the database file appears below. A feature of this data structure is that at any time the database may contain not one index b-tree, but several different b-trees that are incrementally merged as rows are inserted, updated and deleted. This technique improves performance when writing to an FTS table, but causes some overhead for full-text queries that use the index. Executing an SQL statement of the form "INSERT INTO <fts-table>(<fts-table>) VALUES('optimize')" causes FTS to merge all existing index b-trees into a single large b-tree containing the entire index. This can be an expensive operation, but may speed up future queries.

For example, to optimize the full-text index for an FTS table named "docs":

-- Optimize the internal structure of FTS table "docs".
INSERT INTO docs(docs) VALUES('optimize');

The statement above may appear syntactically incorrect to some. Refer to the section describing the simple fts queries for an explanation.

There is another, deprecated, method for invoking the optimize operation using a SELECT statement. New code should use statements similar to the INSERT above to optimize FTS structures.

1.4. Simple FTS Queries

As for all other SQLite tables, virtual or otherwise, data is retrieved from FTS tables using a SELECT statement.

FTS tables can be queried efficiently using SELECT statements of two different forms:

  • Query by rowid. If the WHERE clause of the SELECT statement contains a sub-clause of the form "rowid = ?", where ? is an SQL expression, FTS is able to retrieve the requested row directly using the equivalent of an SQLite INTEGER PRIMARY KEY index.

  • Full-text query. If the WHERE clause of the SELECT statement contains a sub-clause of the form "<column> MATCH ?", FTS is able to use the built-in full-text index to restrict the search to those documents that match the full-text query string specified as the right-hand operand of the MATCH clause.

If neither of these two query strategies can be used, all queries on FTS tables are implemented using a linear scan of the entire table. If the table contains large amounts of data, this may be an impractical approach (the first example on this page shows that a linear scan of 1.5 GB of data takes around 30 seconds using a modern PC).

-- The examples in this block assume the following FTS table:
CREATE VIRTUAL TABLE mail USING fts3(subject, body);

SELECT * FROM mail WHERE rowid = 15;                -- Fast. Rowid lookup.
SELECT * FROM mail WHERE body MATCH 'sqlite';       -- Fast. Full-text query.
SELECT * FROM mail WHERE mail MATCH 'search';       -- Fast. Full-text query.
SELECT * FROM mail WHERE rowid BETWEEN 15 AND 20;   -- Slow. Linear scan.
SELECT * FROM mail WHERE subject = 'database';      -- Slow. Linear scan.
SELECT * FROM mail WHERE subject MATCH 'database';  -- Fast. Full-text query.

In all of the full-text queries above, the right-hand operand of the MATCH operator is a string consisting of a single term. In this case, the MATCH expression evaluates to true for all documents that contain one or more instances of the specified word ("sqlite", "search" or "database", depending on which example you look at). Specifying a single term as the right-hand operand of the MATCH operator results in the simplest and most common type of full-text query possible. However more complicated queries are possible, including phrase searches, term-prefix searches and searches for documents containing combinations of terms occurring within a defined proximity of each other. The various ways in which the full-text index may be queried are described below.

Normally, full-text queries are case-insensitive. However, this is dependent on the specific tokenizer used by the FTS table being queried. Refer to the section on tokenizers for details.

The paragraph above notes that a MATCH operator with a simple term as the right-hand operand evaluates to true for all documents that contain the specified term. In this context, the "document" may refer to either the data stored in a single column of a row of an FTS table, or to the contents of all columns in a single row, depending on the identifier used as the left-hand operand to the MATCH operator. If the identifier specified as the left-hand operand of the MATCH operator is an FTS table column name, then the document that the search term must be contained in is the value stored in the specified column. However, if the identifier is the name of the FTS table itself, then the MATCH operator evaluates to true for each row of the FTS table for which any column contains the search term. The following example demonstrates this:

-- Example schema
CREATE VIRTUAL TABLE mail USING fts3(subject, body);

-- Example table population
INSERT INTO mail(docid, subject, body) VALUES(1, 'software feedback', 'found it too slow');
INSERT INTO mail(docid, subject, body) VALUES(2, 'software feedback', 'no feedback');
INSERT INTO mail(docid, subject, body) VALUES(3, 'slow lunch order',  'was a software problem');

-- Example queries
SELECT * FROM mail WHERE subject MATCH 'software';    -- Selects rows 1 and 2
SELECT * FROM mail WHERE body    MATCH 'feedback';    -- Selects row 2
SELECT * FROM mail WHERE mail    MATCH 'software';    -- Selects rows 1, 2 and 3
SELECT * FROM mail WHERE mail    MATCH 'slow';        -- Selects rows 1 and 3

At first glance, the final two full-text queries in the example above seem to be syntactically incorrect, as there is a table name ("mail") used as an SQL expression. The reason this is acceptable is that each FTS table actually has a HIDDEN column with the same name as the table itself (in this case, "mail"). The value stored in this column is not meaningful to the application, but can be used as the left-hand operand to a MATCH operator. This special column may also be passed as an argument to the FTS auxiliary functions.

The following example illustrates the above. The expressions "docs", "docs.docs" and "main.docs.docs" all refer to column "docs". However, the expression "main.docs" does not refer to any column. It could be used to refer to a table, but a table name is not allowed in the context in which it is used below.

-- Example schema
CREATE VIRTUAL TABLE docs USING fts4(content);

-- Example queries
SELECT * FROM docs WHERE docs MATCH 'sqlite';              -- OK.
SELECT * FROM docs WHERE docs.docs MATCH 'sqlite';         -- OK.
SELECT * FROM docs WHERE main.docs.docs MATCH 'sqlite';    -- OK.
SELECT * FROM docs WHERE main.docs MATCH 'sqlite';         -- Error.

1.5. Summary

From the users point of view, FTS tables are similar to ordinary SQLite tables in many ways. Data may be added to, modified within and removed from FTS tables using the INSERT, UPDATE and DELETE commands just as it may be with ordinary tables. Similarly, the SELECT command may be used to query data. The following list summarizes the differences between FTS and ordinary tables:

  1. As with all virtual table types, it is not possible to create indices or triggers attached to FTS tables. Nor is it possible to use the ALTER TABLE command to add extra columns to FTS tables (although it is possible to use ALTER TABLE to rename an FTS table).

  2. Data-types specified as part of the "CREATE VIRTUAL TABLE" statement used to create an FTS table are ignored completely. Instead of the normal rules for applying type affinity to inserted values, all values inserted into FTS table columns (except the special rowid column) are converted to type TEXT before being stored.

  3. FTS tables permit the special alias "docid" to be used to refer to the rowid column supported by all virtual tables.

  4. The FTS MATCH operator is supported for queries based on the built-in full-text index.

  5. The FTS auxiliary functions, snippet(), offsets(), and matchinfo() are available to support full-text queries.

  6. Every FTS table has a hidden column with the same name as the table itself. The value contained in each row for the hidden column is a blob that is only useful as the left operand of a MATCH operator, or as the left-most argument to one of the FTS auxiliary functions.

2. Compiling and Enabling FTS3 and FTS4

Although FTS3 and FTS4 are included with the SQLite core source code, they are not enabled by default. To build SQLite with FTS functionality enabled, define the preprocessor macro SQLITE_ENABLE_FTS3 when compiling. New applications should also define the SQLITE_ENABLE_FTS3_PARENTHESIS macro to enable the enhanced query syntax (see below). Usually, this is done by adding the following two switches to the compiler command line:

-DSQLITE_ENABLE_FTS3
-DSQLITE_ENABLE_FTS3_PARENTHESIS

Note that enabling FTS3 also makes FTS4 available. There is not a separate SQLITE_ENABLE_FTS4 compile-time option. A build of SQLite either supports both FTS3 and FTS4 or it supports neither.

If using the amalgamation autoconf based build system, setting the CPPFLAGS environment variable while running the 'configure' script is an easy way to set these macros. For example, the following command:

CPPFLAGS="-DSQLITE_ENABLE_FTS3 -DSQLITE_ENABLE_FTS3_PARENTHESIS" ./configure <configure options>

where <configure options> are those options normally passed to the configure script, if any.

Because FTS3 and FTS4 are virtual tables, The SQLITE_ENABLE_FTS3 compile-time option is incompatible with the SQLITE_OMIT_VIRTUALTABLE option.

If a build of SQLite does not include the FTS modules, then any attempt to prepare an SQL statement to create an FTS3 or FTS4 table or to drop or access an existing FTS table in any way will fail. The error message returned will be similar to "no such module: ftsN" (where N is either 3 or 4).

If the C version of the ICU library is available, then FTS may also be compiled with the SQLITE_ENABLE_ICU pre-processor macro defined. Compiling with this macro enables an FTS tokenizer that uses the ICU library to split a document into terms (words) using the conventions for a specified language and locale.

-DSQLITE_ENABLE_ICU

3. Full-text Index Queries

The most useful thing about FTS tables is the queries that may be performed using the built-in full-text index. Full-text queries are performed by specifying a clause of the form "<column> MATCH <full-text query expression>" as part of the WHERE clause of a SELECT statement that reads data from an FTS table. Simple FTS queries that return all documents that contain a given term are described above. In that discussion the right-hand operand of the MATCH operator was assumed to be a string consisting of a single term. This section describes the more complex query types supported by FTS tables, and how they may be utilized by specifying a more complex query expression as the right-hand operand of a MATCH operator.

FTS tables support three basic query types:

  • Token or token prefix queries. An FTS table may be queried for all documents that contain a specified term (the simple case described above), or for all documents that contain a term with a specified prefix. As we have seen, the query expression for a specific term is simply the term itself. The query expression used to search for a term prefix is the prefix itself with a '*' character appended to it. For example:

-- Virtual table declaration
CREATE VIRTUAL TABLE docs USING fts3(title, body);

-- Query for all documents containing the term "linux":
SELECT * FROM docs WHERE docs MATCH 'linux';

-- Query for all documents containing a term with the prefix "lin". This will match
-- all documents that contain "linux", but also those that contain terms "linear",
--"linker", "linguistic" and so on.
SELECT * FROM docs WHERE docs MATCH 'lin*';

  • Normally, a token or token prefix query is matched against the FTS table column specified as the right-hand side of the MATCH operator. Or, if the special column with the same name as the FTS table itself is specified, against all columns. This may be overridden by specifying a column-name followed by a ":" character before a basic term query. There may be space between the ":" and the term to query for, but not between the column-name and the ":" character. For example:

-- Query the database for documents for which the term "linux" appears in
-- the document title, and the term "problems" appears in either the title
-- or body of the document.
SELECT * FROM docs WHERE docs MATCH 'title:linux problems';

-- Query the database for documents for which the term "linux" appears in
-- the document title, and the term "driver" appears in the body of the document
-- ("driver" may also appear in the title, but this alone will not satisfy the.
-- query criteria).
SELECT * FROM docs WHERE body MATCH 'title:linux driver';

  • Phrase queries. A phrase query is a query that retrieves all documents that contain a nominated set of terms or term prefixes in a specified order with no intervening tokens. Phrase queries are specified by enclosing a space separated sequence of terms or term prefixes in double quotes ("). For example:

-- Query for all documents that contain the phrase "linux applications".
SELECT * FROM docs WHERE docs MATCH '"linux applications"';

-- Query for all documents that contain a phrase that matches "lin* app*". As well as
-- "linux applications", this will match common phrases such as "linoleum appliances"
-- or "link apprentice".
SELECT * FROM docs WHERE docs MATCH '"lin* app*"';

  • NEAR queries. A NEAR query is a query that returns documents that contain a two or more nominated terms or phrases within a specified proximity of each other (by default with 10 or less intervening terms). A NEAR query is specified by putting the keyword "NEAR" between two phrase, term or prefix queries. To specify a proximity other than the default, an operator of the form "NEAR/<N>" may be used, where <N> is the maximum number of intervening terms allowed. For example:

-- Virtual table declaration.
CREATE VIRTUAL TABLE docs USING fts4();

-- Virtual table data.
INSERT INTO docs VALUES('SQLite is an ACID compliant embedded relational database management system');

-- Search for a document that contains the terms "sqlite" and "database" with
-- not more than 10 intervening terms. This matches the only document in
-- table docs (since there are only six terms between "SQLite" and "database"
-- in the document).
SELECT * FROM docs WHERE docs MATCH 'sqlite NEAR database';

-- Search for a document that contains the terms "sqlite" and "database" with
-- not more than 6 intervening terms. This also matches the only document in
-- table docs. Note that the order in which the terms appear in the document
-- does not have to be the same as the order in which they appear in the query.
SELECT * FROM docs WHERE docs MATCH 'database NEAR/6 sqlite';

-- Search for a document that contains the terms "sqlite" and "database" with
-- not more than 5 intervening terms. This query matches no documents.
SELECT * FROM docs WHERE docs MATCH 'database NEAR/5 sqlite';

-- Search for a document that contains the phrase "ACID compliant" and the term
-- "database" with not more than 2 terms separating the two. This matches the
-- document stored in table docs.
SELECT * FROM docs WHERE docs MATCH 'database NEAR/2 "ACID compliant"';

-- Search for a document that contains the phrase "ACID compliant" and the term
-- "sqlite" with not more than 2 terms separating the two. This also matches
-- the only document stored in table docs.
SELECT * FROM docs WHERE docs MATCH '"ACID compliant" NEAR/2 sqlite';

  • More than one NEAR operator may appear in a single query. In this case each pair of terms or phrases separated by a NEAR operator must appear within the specified proximity of each other in the document. Using the same table and data as in the block of examples above:

-- The following query selects documents that contains an instance of the term
 -- "sqlite" separated by two or fewer terms from an instance of the term "acid",
 -- which is in turn separated by two or fewer terms from an instance of the term
 -- "relational". As it happens, the only document in table docs satisfies this criteria.
 SELECT * FROM docs WHERE docs MATCH 'sqlite NEAR/2 acid NEAR/2 relational';

 -- This query matches no documents. There is an instance of the term "sqlite" with
 -- sufficient proximity to an instance of "acid" but it is not sufficiently close
 -- to an instance of the term "relational".
 SELECT * FROM docs WHERE docs MATCH 'acid NEAR/2 sqlite NEAR/2 relational';

Phrase and NEAR queries may not span multiple columns within a row.

The three basic query types described above may be used to query the full-text index for the set of documents that match the specified criteria. Using the FTS query expression language it is possible to perform various set operations on the results of basic queries. There are currently three supported operations:

  • The AND operator determines the intersection of two sets of documents.
  • The OR operator calculates the union of two sets of documents.
  • The NOT operator (or, if using the standard syntax, a unary "-" operator) may be used to compute the relative complement of one set of documents with respect to another.

The FTS modules may be compiled to use one of two slightly different versions of the full-text query syntax, the "standard" query syntax and the "enhanced" query syntax. The basic term, term-prefix, phrase and NEAR queries described above are the same in both versions of the syntax. The way in which set operations are specified is slightly different. The following two sub-sections describe the part of the two query syntaxes that pertains to set operations. Refer to the description of how to compile fts for compilation notes.

3.1. Set Operations Using The Enhanced Query Syntax

The enhanced query syntax supports the AND, OR and NOT binary set operators. Each of the two operands to an operator may be a basic FTS query, or the result of another AND, OR or NOT set operation. Operators must be entered using capital letters. Otherwise, they are interpreted as basic term queries instead of set operators.

The AND operator may be implicitly specified. If two basic queries appear with no operator separating them in an FTS query string, the results are the same as if the two basic queries were separated by an AND operator. For example, the query expression "implicit operator" is a more succinct version of "implicit AND operator".

-- Virtual table declaration
CREATE VIRTUAL TABLE docs USING fts3();

-- Virtual table data
INSERT INTO docs(docid, content) VALUES(1, 'a database is a software system');
INSERT INTO docs(docid, content) VALUES(2, 'sqlite is a software system');
INSERT INTO docs(docid, content) VALUES(3, 'sqlite is a database');

-- Return the set of documents that contain the term "sqlite", and the
-- term "database". This query will return the document with docid 3 only.
SELECT * FROM docs WHERE docs MATCH 'sqlite AND database';

-- Again, return the set of documents that contain both "sqlite" and
-- "database". This time, use an implicit AND operator. Again, document
-- 3 is the only document matched by this query.
SELECT * FROM docs WHERE docs MATCH 'database sqlite';

-- Query for the set of documents that contains either "sqlite" or "database".
-- All three documents in the database are matched by this query.
SELECT * FROM docs WHERE docs MATCH 'sqlite OR database';

-- Query for all documents that contain the term "database", but do not contain
-- the term "sqlite". Document 1 is the only document that matches this criteria.
SELECT * FROM docs WHERE docs MATCH 'database NOT sqlite';

-- The following query matches no documents. Because "and" is in lowercase letters,
-- it is interpreted as a basic term query instead of an operator. Operators must
-- be specified using capital letters. In practice, this query will match any documents
-- that contain each of the three terms "database", "and" and "sqlite" at least once.
-- No documents in the example data above match this criteria.
SELECT * FROM docs WHERE docs MATCH 'database and sqlite';

The examples above all use basic full-text term queries as both operands of the set operations demonstrated. Phrase and NEAR queries may also be used, as may the results of other set operations. When more than one set operation is present in an FTS query, the precedence of operators is as follows:

Operator | Enhanced Query Syntax Precedence
NOT | Highest precedence (tightest grouping).
AND |
OR | Lowest precedence (loosest grouping).

When using the enhanced query syntax, parenthesis may be used to override the default precedence of the various operators. For example:

-- Return the docid values associated with all documents that contain the
-- two terms "sqlite" and "database", and/or contain the term "library".
SELECT docid FROM docs WHERE docs MATCH 'sqlite AND database OR library';

-- This query is equivalent to the above.
SELECT docid FROM docs WHERE docs MATCH 'sqlite AND database'
  UNION
SELECT docid FROM docs WHERE docs MATCH 'library';

-- Query for the set of documents that contains the term "linux", and at least
-- one of the phrases "sqlite database" and "sqlite library".
SELECT docid FROM docs WHERE docs MATCH '("sqlite database" OR "sqlite library") AND linux';

-- This query is equivalent to the above.
SELECT docid FROM docs WHERE docs MATCH 'linux'
  INTERSECT
SELECT docid FROM (
  SELECT docid FROM docs WHERE docs MATCH '"sqlite library"'
    UNION
  SELECT docid FROM docs WHERE docs MATCH '"sqlite database"'
);

3.2. Set Operations Using The Standard Query Syntax

FTS query set operations using the standard query syntax are similar, but not identical, to set operations with the enhanced query syntax. There are four differences, as follows:

  1. Only the implicit version of the AND operator is supported. Specifying the string "AND" as part of a standard query syntax query is interpreted as a term query for the set of documents containing the term "and".

  2. Parenthesis are not supported.

  3. The NOT operator is not supported. Instead of the NOT operator, the standard query syntax supports a unary "-" operator that may be applied to basic term and term-prefix queries (but not to phrase or NEAR queries). A term or term-prefix that has a unary "-" operator attached to it may not appear as an operand to an OR operator. An FTS query may not consist entirely of terms or term-prefix queries with unary "-" operators attached to them.

-- Search for the set of documents that contain the term "sqlite" but do
-- not contain the term "database".
SELECT * FROM docs WHERE docs MATCH 'sqlite -database';

  4. The relative precedence of the set operations is different. In particular, using the standard query syntax the "OR" operator has a higher precedence than "AND". The precedence of operators when using the standard query syntax is:

Operator | Standard Query Syntax Precedence
Unary "-" | Highest precedence (tightest grouping).
OR |
AND | Lowest precedence (loosest grouping).
  1. The following example illustrates precedence of operators using the standard query syntax:
-- Search for documents that contain at least one of the terms "database"
-- and "sqlite", and also contain the term "library". Because of the differences
-- in operator precedences, this query would have a different interpretation using
-- the enhanced query syntax.
SELECT * FROM docs WHERE docs MATCH 'sqlite OR database library';

4. Auxiliary Functions - Snippet, Offsets and Matchinfo

The FTS3 and FTS4 modules provide three special SQL scalar functions that may be useful to the developers of full-text query systems: "snippet", "offsets" and "matchinfo". The purpose of the "snippet" and "offsets" functions is to allow the user to identify the location of queried terms in the returned documents. The "matchinfo" function provides the user with metrics that may be useful for filtering or sorting query results according to relevance.

The first argument to all three special SQL scalar functions must be the FTS hidden column of the FTS table that the function is applied to. The FTS hidden column is an automatically-generated column found on all FTS tables that has the same name as the FTS table itself. For example, given an FTS table named "mail":

SELECT offsets(mail) FROM mail WHERE mail MATCH <full-text query expression>;
SELECT snippet(mail) FROM mail WHERE mail MATCH <full-text query expression>;
SELECT matchinfo(mail) FROM mail WHERE mail MATCH <full-text query expression>;

The three auxiliary functions are only useful within a SELECT statement that uses the FTS table's full-text index. If used within a SELECT that uses the "query by rowid" or "linear scan" strategies, then the snippet and offsets both return an empty string, and the matchinfo function returns a blob value zero bytes in size.

All three auxiliary functions extract a set of "matchable phrases" from the FTS query expression to work with. The set of matchable phrases for a given query consists of all phrases (including unquoted tokens and token prefixes) in the expression except those that are prefixed with a unary "-" operator (standard syntax) or are part of a sub-expression that is used as the right-hand operand of a NOT operator.

With the following provisos, each series of tokens in the FTS table that matches one of the matchable phrases in the query expression is known as a "phrase match":

  1. If a matchable phrase is part of a series of phrases connected by NEAR operators in the FTS query expression, then each phrase match must be sufficiently close to other phrase matches of the relevant types to satisfy the NEAR condition.
  2. If the matchable phrase in the FTS query is restricted to matching data in a specified FTS table column, then only phrase matches that occur within that column are considered.

4.1. The Offsets Function

For a SELECT query that uses the full-text index, the offsets() function returns a text value containing a series of space-separated integers. For each term in each phrase match of the current row, there are four integers in the returned list. Each set of four integers is interpreted as follows:

Integer | Interpretation
0 | The column number that the term instance occurs in (0 for the leftmost column of the FTS table, 1 for the next leftmost, etc.).
1 | The term number of the matching term within the full-text query expression. Terms within a query expression are numbered starting from 0 in the order that they occur.
2 | The byte offset of the matching term within the column.
3 | The size of the matching term in bytes.

The following block contains examples that use the offsets function.

CREATE VIRTUAL TABLE mail USING fts3(subject, body);
INSERT INTO mail VALUES('hello world', 'This message is a hello world message.');
INSERT INTO mail VALUES('urgent: serious', 'This mail is seen as a more serious mail');

-- The following query returns a single row (as it matches only the first
-- entry in table "mail". The text returned by the offsets function is
-- "0 0 6 5 1 0 24 5".
--
-- The first set of four integers in the result indicate that column 0
-- contains an instance of term 0 ("world") at byte offset 6. The term instance
-- is 5 bytes in size. The second set of four integers shows that column 1
-- of the matched row contains an instance of term 0 ("world") at byte offset
-- 24. Again, the term instance is 5 bytes in size.
SELECT offsets(mail) FROM mail WHERE mail MATCH 'world';

-- The following query returns also matches only the first row in table "mail".
-- In this case the returned text is "1 0 5 7 1 0 30 7".
SELECT offsets(mail) FROM mail WHERE mail MATCH 'message';

-- The following query matches the second row in table "mail". It returns the
-- text "1 0 28 7 1 1 36 4". Only those occurrences of terms "serious" and "mail"
-- that are part of an instance of the phrase "serious mail" are identified; the
-- other occurrences of "serious" and "mail" are ignored.
SELECT offsets(mail) FROM mail WHERE mail MATCH '"serious mail"';

4.2. The Snippet Function

The snippet function is used to create formatted fragments of document text for display as part of a full-text query results report. The snippet function may be passed between one and six arguments, as follows:

Argument | Default Value | Description
0 | N/A | The first argument to the snippet function must always be the FTS hidden column of the FTS table being queried and from which the snippet is to be taken. The FTS hidden column is an automatically generated column with the same name as the FTS table itself.
1 | "<b>" | The "start match" text.
2 | "</b>" | The "end match" text.
3 | "<b>...</b>" | The "ellipses" text.
4 | -1 | The FTS table column number to extract the returned fragments of text from. Columns are numbered from left to right starting with zero. A negative value indicates that the text may be extracted from any column.
5 | -15 | The absolute value of this integer argument is used as the (approximate) number of tokens to include in the returned text value. The maximum allowable absolute value is 64. The value of this argument is referred to as N in the discussion below.

The snippet function first attempts to find a fragment of text consisting of |N| tokens within the current row that contains at least one phrase match for each matchable phrase matched somewhere in the current row, where |N| is the absolute value of the sixth argument passed to the snippet function. If the text stored in a single column contains less than |N| tokens, then the entire column value is considered. Text fragments may not span multiple columns.

If such a text fragment can be found, it is returned with the following modifications:

  • If the text fragment does not begin at the start of a column value, the "ellipses" text is prepended to it.
  • If the text fragment does not finish at the end of a column value, the "ellipses" text is appended to it.
  • For each token in the text fragment that is part of a phrase match, the "start match" text is inserted into the fragment before the token, and the "end match" text is inserted immediately after it.

If more than one such fragment can be found, then fragments that contain a larger number of "extra" phrase matches are favoured. The start of the selected text fragment may be moved a few tokens forward or backward to attempt to concentrate the phrase matches toward the center of the fragment.

Assuming N is a positive value, if no fragments can be found that contain a phrase match corresponding to each matchable phrase, the snippet function attempts to find two fragments of approximately N/2 tokens that between them contain at least one phrase match for each matchable phrase matched by the current row. If this fails, attempts are made to find three fragments of N/3 tokens each and finally four N/4 token fragments. If a set of four fragments cannot be found that encompasses the required phrase matches, the four fragments of N/4 tokens that provide the best coverage are selected.

If N is a negative value, and no single fragment can be found containing the required phrase matches, the snippet function searches for two fragments of |N| tokens each, then three, then four. In other words, if the specified value of N is negative, the sizes of the fragments is not decreased if more than one fragment is required to provide the desired phrase match coverage.

After the M fragments have been located, where M is between two and four as described in the paragraphs above, they are joined together in sorted order with the "ellipses" text separating them. The three modifications enumerated earlier are performed on the text before it is returned.

Note: In this block of examples, newlines and whitespace characters have
been inserted into the document inserted into the FTS table, and the expected
results described in SQL comments. This is done to enhance readability only,
they would not be present in actual SQLite commands or output.

-- Create and populate an FTS table.
CREATE VIRTUAL TABLE text USING fts4();
INSERT INTO text VALUES('
  During 30 Nov-1 Dec, 2-3oC drops. Cool in the upper portion, minimum temperature 14-16oC
  and cool elsewhere, minimum temperature 17-20oC. Cold to very cold on mountaintops,
  minimum temperature 6-12oC. Northeasterly winds 15-30 km/hr. After that, temperature
  increases. Northeasterly winds 15-30 km/hr.
');

-- The following query returns the text value:
--
--   "<b>...</b>cool elsewhere, minimum temperature 17-20oC. <b>Cold</b> to very
--    <b>cold</b> on mountaintops, minimum temperature 6<b>...</b>".
--
SELECT snippet(text) FROM text WHERE text MATCH 'cold';

-- The following query returns the text value:
--
--   "...the upper portion, [minimum] [temperature] 14-16oC and cool elsewhere,
--    [minimum] [temperature] 17-20oC. Cold..."
--
SELECT snippet(text, '[ ']', '...') FROM text WHERE text MATCH '"min* tem*"'

4.3. The Matchinfo Function

The matchinfo function returns a blob value. If it is used within a query that does not use the full-text index (a "query by rowid" or "linear scan"), then the blob is zero bytes in size. Otherwise, the blob consists of zero or more 32-bit unsigned integers in machine byte-order. The exact number of integers in the returned array depends on both the query and the value of the second argument (if any) passed to the matchinfo function.

The matchinfo function is called with either one or two arguments. As for all auxiliary functions, the first argument must be the special FTS hidden column. The second argument, if it is specified, must be a text value comprised only of the characters 'p', 'c', 'n', 'a', 'l', 's' and 'x'. If no second argument is explicitly supplied, it defaults to "pcx". The second argument is referred to as the "format string" below.

Characters in the matchinfo format string are processed from left to right. Each character in the format string causes one or more 32-bit unsigned integer values to be added to the returned array. The "values" column in the following table contains the number of integer values appended to the output buffer for each supported format string character. In the formula given, cols is the number of columns in the FTS table, and phrases is the number of matchable phrases in the query.

Character | Values | Description
p | 1 | The number of matchable phrases in the query.
c | 1 | The number of user defined columns in the FTS table (i.e. not including the docid or the FTS hidden column).
x 3 * cols * phrases For each distinct combination of a phrase and table column, the following three values:
  • In the current row, the number of times the phrase appears in the column.
  • The total number of times the phrase appears in the column in all rows in the FTS table.
  • The total number of rows in the FTS table for which the column contains at least one instance of the phrase.
The first set of three values corresponds to the left-most column of the table (column 0) and the left-most matchable phrase in the query (phrase 0). If the table has more than one column, the second set of three values in the output array correspond to phrase 0 and column 1. Followed by phrase 0, column 2 and so on for all columns of the table. And so on for phrase 1, column 0, then phrase 1, column 1 etc. In other words, the data for occurrences of phrase p in column c may be found using the following formula:
          hits_this_row  = array[3 * (c + p*cols) + 0]
          hits_all_rows  = array[3 * (c + p*cols) + 1]
          docs_with_hits = array[3 * (c + p*cols) + 2]
n | 1 | The number of rows in the FTS4 table. This value is only available when querying FTS4 tables, not FTS3.
a | cols | For each column, the average number of tokens in the text values stored in the column (considering all rows in the FTS4 table). This value is only available when querying FTS4 tables, not FTS3.
l | cols | For each column, the length of the value stored in the current row of the FTS4 table, in tokens. This value is only available when querying FTS4 tables, not FTS3. And only if the "matchinfo=fts3" directive was not specified as part of the "CREATE VIRTUAL TABLE" statement used to create the FTS4 table.
s | cols | For each column, the length of the longest subsequence of phrase matches that the column value has in common with the query text. For example, if a table column contains the text 'a b c d e' and the query is 'a c "d e"', then the length of the longest common subsequence is 2 (phrase "c" followed by phrase "d e").

For example:

-- Create and populate an FTS4 table with two columns:
CREATE VIRTUAL TABLE t1 USING fts4(a, b);
INSERT INTO t1 VALUES('transaction default models default', 'Non transaction reads');
INSERT INTO t1 VALUES('the default transaction', 'these semantics present');
INSERT INTO t1 VALUES('single request', 'default data');

-- In the following query, no format string is specified and so it defaults
-- to "pcx". It therefore returns a single row consisting of a single blob
-- value 80 bytes in size (20 32-bit integers - 1 for "p", 1 for "c" and
-- 3*2*3 for "x"). If each block of 4 bytes in the blob is interpreted
-- as an unsigned integer in machine byte-order, the values will be:
--
--     3 2  1 3 2  0 1 1  1 2 2  0 1 1  0 0 0  1 1 1
--
-- The row returned corresponds to the second entry inserted into table t1.
-- The first two integers in the blob show that the query contained three
-- phrases and the table being queried has two columns. The next block of
-- three integers describes column 0 (in this case column "a") and phrase
-- 0 (in this case "default"). The current row contains 1 hit for "default"
-- in column 0, of a total of 3 hits for "default" that occur in column
-- 0 of any table row. The 3 hits are spread across 2 different rows.
--
-- The next set of three integers (0 1 1) pertain to the hits for "default"
-- in column 1 of the table (0 in this row, 1 in all rows, spread across
-- 1 rows).
--
SELECT matchinfo(t1) FROM t1 WHERE t1 MATCH 'default transaction "these semantics"';

-- The format string for this query is "nl". The output array will therefore
-- contain 3 integer values - 1 for "n" and 2 for "l". The query returns
-- two rows (the first two rows in the table match). The values returned are:
--
--     3  1 1
--     3  2 0
--
-- The first value in the matchinfo array returned for both rows is 3 (the
-- number of rows in the table). The following two values are the lengths
-- of the longest common subsequence of phrase matches in each column.
SELECT matchinfo(t1, 'nl') FROM t1 WHERE t1 MATCH 'default transaction';

The matchinfo function is much faster than either the snippet or offsets functions. This is because the implementation of both snippet and offsets is required to retrieve the documents being analyzed from disk, whereas all data required by matchinfo is available as part of the same portions of the full-text index that are required to implement the full-text query itself. This means that of the following two queries, the first may be an order of magnitude faster than the second:

SELECT docid, matchinfo(tbl) FROM tbl WHERE tbl MATCH <query expression>;
SELECT docid, offsets(tbl) FROM tbl WHERE tbl MATCH <query expression>;

The matchinfo function provides all the information required to calculate probabilistic "bag-of-words" relevancy scores such as Okapi BM25/BM25F that may be used to order results in a full-text search application. Appendix A of this document, "search application tips", contains an example of using the matchinfo() function efficiently.

5. Fts4aux - Direct Access to the Full-Text Index

As of version 3.7.6, SQLite includes a new virtual table module called "fts4aux", which can be used to inspect the full-text index of an exiting FTS table directly. Despite its name, fts4aux works just as well with FTS3 tables as it does with FTS4 tables. Fts4aux tables are read-only. The only way to modify the contents of an fts4aux table is by modifying the contents of the associated FTS table. The fts4aux module is automatically included in all builds that include FTS.

An fts4aux virtual table is constructed with a single argument - the unqualified name of the FTS table that it will be used to access. For example:

-- Create an FTS4 table
CREATE VIRTUAL TABLE ft USING fts4(x, y);

-- Create an fts4aux table to access the full-text index for table "ft"
CREATE VIRTUAL TABLE ft_terms USING fts4aux(ft);

For each term present in the FTS table, there are between 2 and N+1 rows in the fts4aux table, where N is the number of user-defined columns in the associated FTS table. An fts4aux table always has the same four columns, as follows, from left to right:

Column Name | Column Contents
term | Contains the text of the term for this row.
col | This column may contain either the text value '*' (i.e. a single character, UTF codepoint 42) or an integer between 0 and N-1, where N is again the number of user-defined columns in the corresponding FTS table.
documents | This column always contains an integer value greater than zero. If the "col" column contains the value '*', then this column contains the number of rows of the FTS table that contain at least one instance of the term (in any column). If col contains an integer value, then this column contains the number of rows of the FTS table that contain at least one instance of the term in the column identified by the col value. As usual, the columns of the FTS table are numbered from left to right, starting with zero.
occurrences | This column also always contains an integer value greater than zero. If the "col" column contains the value '*', then this column contains the total number of instances of the term in all rows of the FTS table (in any column). Otherwise, if col contains an integer value, then this column contains the total number of instances of the term that appear in the FTS table column identified by the col value.

For example, using the tables created above:

INSERT INTO ft(x, y) VALUES('Apple banana', 'Cherry');
INSERT INTO ft(x, y) VALUES('Banana Date Date', 'cherry');
INSERT INTO ft(x, y) VALUES('Cherry Elderberry', 'Elderberry');

-- The following query returns this data:
--
--     apple       |  *  |  1  |  1
--     apple       |  0  |  1  |  1
--     banana      |  *  |  2  |  2
--     banana      |  0  |  2  |  2
--     cherry      |  *  |  3  |  3
--     cherry      |  0  |  1  |  1
--     cherry      |  1  |  2  |  2
--     date        |  *  |  1  |  2
--     date        |  0  |  1  |  2
--     elderberry  |  *  |  1  |  2
--     elderberry  |  1  |  1  |  1
--     elderberry  |  1  |  1  |  1
--
SELECT term, col, documents, occurrences FROM ft_terms;

In the example, the values in the "term" column are all lower case, even though they were inserted into table "ft" in mixed case. This is because an fts3aux table contains the terms as extracted from the document text by the tokenizer. In this case, since table "ft" uses the simple tokenizer, this means all terms have been folded to lower case. Also, there is (for example) no row with column "term" set to "apple" and column "col" set to 1. Since there are no instances of the term "apple" in column 1, no row is present in the fts4aux table.

During a transaction, some of the data written to an FTS table may be cached in memory and written to the database only when the transaction is committed. However the implementation of the fts4aux module is only able to read data from the database. In practice this means that if an fts4aux table is queried from within a transaction in which the associated FTS table has been modified, the results of the query are likely to reflect only a (possibly empty) subset of the changes made.

6. FTS4 Options

If the "CREATE VIRTUAL TABLE" statement specifies module FTS4 (not FTS3), then special directives - FTS4 options - similar to the "tokenize=*" option may also appear in place of column names. An FTS4 option consists of the option name, followed by an "=" character, followed by the option value. The option value may optionally be enclosed in single or double quotes, with embedded quote characters escaped in the same way as for SQL literals. There may not be whitespace on either side of the "=" character. For example, to create an FTS4 table with the value of option "matchinfo" set to "fts3":

-- Create a reduced-footprint FTS4 table.
CREATE VIRTUAL TABLE papers USING fts4(author, document, matchinfo=fts3);

FTS4 currently supports the following three options:

Option | Interpretation
matchinfo | This option may only be set to the value "fts3". Attempting to set it otherwise is an error. If this option is specified, then some of the extra information stored by FTS4 is omitted. This reduces the amount of disk space consumed by an FTS4 table until it is almost the same as the amount that would be used by the equivalent FTS3 table, but also means that the data accessed by passing the 'l' flag to the matchinfo() function is not available.
compress | This option is used to specify the compress function. It is an error to specify a compress function without also specifying an uncompress function. See below for details.
uncompress | This option is used to specify the uncompress function. It is an error to specify an uncompress function without also specifying a compress function. See below for details.
order | The "order" option may be set to either "DESC" or "ASC" (in upper or lower case). If it is set to "DESC", then FTS4 stores its data in such a way as to optimize returning results in descending order by docid. If it is set to "ASC" (the default), then the data structures are optimized for returning results in ascending order by docid. In other words, if many of the queries run against the FTS4 table use "ORDER BY docid DESC", then it may improve performance to add the "order=desc" option to the CREATE VIRTUAL TABLE statement.
prefix | This option may be set to a comma-separated list of positive non-zero integers. For each integer N in the list, a separate index is created in the database file to optimize prefix queries where the query term is N bytes in length, not including the '*' character, when encoded using UTF-8. See below for details.

When using FTS4, specifying a column name that contains an "=" character and is not either a "tokenize=*" specification or a recognized FTS4 option is an error. With FTS3, the first token in the unrecognized directive is interpreted as a column name. Similarly, specifying multiple "tokenize=*" directives in a single table declaration is an error when using FTS4, whereas the second and subsequent "tokenize=*" directives are interpreted as column names by FTS3. For example:

-- An error. FTS4 does not recognize the directive "xyz=abc".
CREATE VIRTUAL TABLE papers USING fts4(author, document, xyz=abc);

-- Create an FTS3 table with three columns - "author", "document"
-- and "xyz".
CREATE VIRTUAL TABLE papers USING fts3(author, document, xyz=abc);

-- An error. FTS4 does not allow multiple tokenize=* directives
CREATE VIRTUAL TABLE papers USING fts4(tokenize=porter, tokenize=simple);

-- Create an FTS3 table with a single column named "tokenize". The
-- table uses the "porter" tokenizer.
CREATE VIRTUAL TABLE papers USING fts3(tokenize=porter, tokenize=simple);

-- An error. Cannot create a table with two columns named "tokenize".
CREATE VIRTUAL TABLE papers USING fts3(tokenize=porter, tokenize=simple, tokenize=icu);

6.1. Compress/Uncompress

The compress and uncompress options allow FTS4 content to be stored in the database in a compressed form. Both options should be set to the name of an SQL scalar function registered using sqlite3_create_function() that accepts a single argument.

The compress function should return a compressed version of the value passed to it as an argument. Each time data is written to the FTS4 table, each column value is passed to the compress function and the result value stored in the database. The compress function may return any type of SQLite value (blob, text, real, integer or null).

The uncompress function should uncompress data previously compressed by the compress function. In other words, for all SQLite values X, it should be true that uncompress(compress(X)) equals X. When data that has been compressed by the compress function is read from the database by FTS4, it is passed to the uncompress function before it is used.

If the specified compress or uncompress functions do not exist, the table may still be created. An error is not returned until the FTS4 table is read (if the uncompress function does not exist) or written (if it is the compress function that does not exist).

-- Create an FTS4 table that stores data in compressed form. This
-- assumes that the scalar functions zip() and unzip() have been (or
-- will be) added to the database handle.
CREATE VIRTUAL TABLE papers USING fts4(author, document, compress=zip, uncompress=unzip);

6.2. Prefix

The FTS4 prefix option causes FTS to index term prefixes of specified lengths in the same way that it always indexes complete terms. The prefix option must be set to a comma separated list of positive non-zero integers. For each value N in the list, prefixes of length N bytes (when encoded using UTF-8) are indexed. FTS4 uses term prefix indexes to speed up prefix queries. The cost, of course, is that indexing term prefixes as well as complete terms increases the database size and slows down write operations on the FTS4 table.

Prefix indexes may be used to optimize prefix queries in two cases. If the query is for a prefix of N bytes, then a prefix index created with "prefix=N" provides the best optimization. Or, if no "prefix=N" index is available, a "prefix=N+1" index imay be used instead. Using a "prefix=N+1" index is less efficient than a "prefix=N" index, but is better than no prefix index at all.

-- Create an FTS4 table with indexes to optimize 2 and 4 byte prefix queries.
CREATE VIRTUAL TABLE t1 USING fts4(c1, c2, prefix="2,4");

-- The following two queries are both optimized using the prefix indexes.
SELECT * FROM t1 WHERE t1 MATCH 'ab*';
SELECT * FROM t1 WHERE t1 MATCH 'abcd*';

-- The following two queries are both partially optimized using the prefix
-- indexes. The optimization is not as pronounced as it is for the queries
-- above, but still an improvement over no prefix indexes at all.
SELECT * FROM t1 WHERE t1 MATCH 'a*';
SELECT * FROM t1 WHERE t1 MATCH 'abc*';

7. Tokenizers

An FTS tokenizer is a set of rules for extracting terms from a document or basic FTS full-text query.

Unless a specific tokenizer is specified as part of the CREATE VIRTUAL TABLE statement used to create the FTS table, the default tokenizer, "simple", is used. The simple tokenizer extracts tokens from a document or basic FTS full-text query according to the following rules:

  • A term is a contiguous sequence of eligible characters, where eligible characters are all alphanumeric characters, the "_" character, and all characters with UTF codepoints greater than or equal to 128. All other characters are discarded when splitting a document into terms. Their only contribution is to separate adjacent terms.

  • All uppercase characters within the ASCII range (UTF codepoints less than 128), are transformed to their lowercase equivalents as part of the tokenization process. Thus, full-text queries are case-insensitive when using the simple tokenizer.

For example, when a document containing the text "Right now, they're very frustrated.", the terms extracted from the document and added to the full-text index are, in order, "right now they re very frustrated". Such a document would match a full-text query such as "MATCH 'Frustrated'", as the simple tokenizer transforms the term in the query to lowercase before searching the full-text index.

As well as the "simple" tokenizer, the FTS source code features a tokenizer that uses the Porter Stemming algorithm. This tokenizer uses the same rules to separate the input document into terms, but as well as folding all terms to lower case it uses the Porter Stemming algorithm to reduce related English language words to a common root. For example, using the same input document as in the paragraph above, the porter tokenizer extracts the following tokens: "right now thei veri frustrat". Even though some of these terms are not even English words, in some cases using them to build the full-text index is more useful than the more intelligible output produced by the simple tokenizer. Using the porter tokenizer, the document not only matches full-text queries such as "MATCH 'Frustrated'", but also queries such as "MATCH 'Frustration'", as the term "Frustration" is reduced by the Porter stemmer algorithm to "frustrat" - just as "Frustrated" is. So, when using the porter tokenizer, FTS is able to find not just exact matches for queried terms, but matches against similar English language terms. For more information on the Porter Stemmer algorithm, please refer to the page linked above.

Example illustrating the difference between the "simple" and "porter" tokenizers:

-- Create a table using the simple tokenizer. Insert a document into it.
CREATE VIRTUAL TABLE simple USING fts3(tokenize=simple);
INSERT INTO simple VALUES('Right now they''re very frustrated');

-- The first of the following two queries matches the document stored in
-- table "simple". The second does not.
SELECT * FROM simple WHERE simple MATCH 'Frustrated';
SELECT * FROM simple WHERE simple MATCH 'Frustration';

-- Create a table using the porter tokenizer. Insert the same document into it
CREATE VIRTUAL TABLE porter USING fts3(tokenize=porter);
INSERT INTO porter VALUES('Right now they''re very frustrated');

-- Both of the following queries match the document stored in table "porter".
SELECT * FROM porter WHERE porter MATCH 'Frustrated';
SELECT * FROM porter WHERE porter MATCH 'Frustration';

If this extension is compiled with the SQLITE_ENABLE_ICU pre-processor symbol defined, then there exists a built-in tokenizer named "icu" implemented using the ICU library. The first argument passed to the xCreate() method (see fts3_tokenizer.h) of this tokenizer may be an ICU locale identifier. For example "tr_TR" for Turkish as used in Turkey, or "en_AU" for English as used in Australia. For example:

CREATE VIRTUAL TABLE thai_text USING fts3(text, tokenize=icu th_TH)

The ICU tokenizer implementation is very simple. It splits the input text according to the ICU rules for finding word boundaries and discards any tokens that consist entirely of white-space. This may be suitable for some applications in some locales, but not all. If more complex processing is required, for example to implement stemming or discard punctuation, this can be done by creating a tokenizer implementation that uses the ICU tokenizer as part of its implementation.

7.1. Custom (User Implemented) Tokenizers

As well as the built-in "simple", "porter" and (possibly) "icu" tokenizers, FTS exports an interface that allows users to implement custom tokenizers using C. The interface used to create a new tokenizer is defined and described in the fts3_tokenizer.h source file.

Registering a new FTS tokenizer is similar to registering a new virtual table module with SQLite. The user passes a pointer to a structure containing pointers to various callback functions that make up the implementation of the new tokenizer type. For tokenizers, the structure (defined in fts3_tokenizer.h) is called "sqlite3_tokenizer_module".

FTS does not expose a C-function that users call to register new tokenizer types with a database handle. Instead, the pointer must be encoded as an SQL blob value and passed to FTS through the SQL engine by evaluating a special scalar function, "fts3_tokenizer()". The fts3_tokenizer() function may be called with one or two arguments, as follows:

SELECT fts3_tokenizer(<tokenizer-name>);
SELECT fts3_tokenizer(<tokenizer-name>, <sqlite3_tokenizer_module ptr>);

Where is a string identifying the tokenizer and is a pointer to an sqlite3_tokenizer_module structure encoded as an SQL blob. If the second argument is present, it is registered as tokenizer and a copy of it returned. If only one argument is passed, a pointer to the tokenizer implementation currently registered as is returned, encoded as a blob. Or, if no such tokenizer exists, an SQL exception (error) is raised.

SECURITY WARNING: If the fts3/4 extension is used in an environment where potentially malicious users may execute arbitrary SQL, they should be prevented from invoking the fts3_tokenizer() function, possibly using the authorisation callback.

The following block contains an example of calling the fts3_tokenizer() function from C code:

/*
** Register a tokenizer implementation with FTS3 or FTS4.
*/
int registerTokenizer(
  sqlite3 *db,
  char *zName,
  const sqlite3_tokenizer_module *p
){
  int rc;
  sqlite3_stmt *pStmt;
  const char *zSql = "SELECT fts3_tokenizer(?, ?)";

  rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
  if( rc!=SQLITE_OK ){
    return rc;
  }

  sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
  sqlite3_bind_blob(pStmt, 2, &p, sizeof(p), SQLITE_STATIC);
  sqlite3_step(pStmt);

  return sqlite3_finalize(pStmt);
}

/*
** Query FTS for the tokenizer implementation named zName.
*/
int queryTokenizer(
  sqlite3 *db,
  char *zName,
  const sqlite3_tokenizer_module **pp
){
  int rc;
  sqlite3_stmt *pStmt;
  const char *zSql = "SELECT fts3_tokenizer(?)";

  *pp = 0;
  rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
  if( rc!=SQLITE_OK ){
    return rc;
  }

  sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
  if( SQLITE_ROW==sqlite3_step(pStmt) ){
    if( sqlite3_column_type(pStmt, 0)==SQLITE_BLOB ){
      memcpy(pp, sqlite3_column_blob(pStmt, 0), sizeof(*pp));
    }
  }

  return sqlite3_finalize(pStmt);
}

8. Data Structures

This section describes at a high-level the way the FTS module stores its index and content in the database. It is not necessary to read or understand the material in this section in order to use FTS in an application. However, it may be useful to application developers attempting to analyze and understand FTS performance characteristics, or to developers contemplating enhancements to the existing FTS feature set.

For each FTS virtual table in a database, three to five real (non-virtual) tables are created to store the underlying data. These real tables are called "shadow tables". The real tables are named "%_content", "%_segdir", "%_segments", "%_stat", and "%_docsize", where "%" is replaced by the name of the FTS virtual table.

The leftmost column of the "%_content" table is an INTEGER PRIMARY KEY field named "docid". Following this is one column for each column of the FTS virtual table as declared by the user, named by prepending the column name supplied by the user with "cN", where N is the index of the column within the table, numbered from left to right starting with 0. Data types supplied as part of the virtual table declaration are not used as part of the %_content table declaration. For example:

-- Virtual table declaration
CREATE VIRTUAL TABLE abc USING fts4(a NUMBER, b TEXT, c);

-- Corresponding %_content table declaration
CREATE TABLE abc_content(docid INTEGER PRIMARY KEY, c0a, c1b, c2c);

The %_content table contains the unadulterated data inserted by the user into the FTS virtual table by the user. If the user does not explicitly supply a "docid" value when inserting records, one is selected automatically by the system.

The %_stat and %_docsize tables are only created if the FTS table uses the FTS4 module, not FTS3. Furthermore, the %_docsize table is omitted if the FTS4 table is created with the "matchinfo=fts3" directive specified as part of the CREATE VIRTUAL TABLE statement. If they are created, the schema of the two tables is as follows:

CREATE TABLE %_stat(
  id INTEGER PRIMARY KEY,
  value BLOB
);

CREATE TABLE %_docsize(
  docid INTEGER PRIMARY KEY,
  size BLOB
);

For each row in the FTS table, the %_docsize table contains a corresponding row with the same "docid" value. The "size" field contains a blob consisting of N FTS varints, where N is the number of user-defined columns in the table. Each varint in the "size" blob is the number of tokens in the corresponding column of the associated row in the FTS table. The %_stat table always contains a single row with the "id" column set to 0. The "value" column contains a blob consisting of N+1 FTS varints, where N is again the number of user-defined columns in the FTS table. The first varint in the blob is set to the total number of rows in the FTS table. The second and subsequent varints contain the total number of tokens stored in the corresponding column for all rows of the FTS table.

The two remaining tables, %_segments and %_segdir, are used to store the full-text index. Conceptually, this index is a lookup table that maps each term (word) to the set of docid values corresponding to records in the %_content table that contain one or more occurrences of the term. To retrieve all documents that contain a specified term, the FTS module queries this index to determine the set of docid values for records that contain the term, then retrieves the required documents from the %_content table. Regardless of the schema of the FTS virtual table, the %_segments and %_segdir tables are always created as follows:

CREATE TABLE %_segments(
  blockid INTEGER PRIMARY KEY,       -- B-tree node id
  block blob                         -- B-tree node data
);

CREATE TABLE %_segdir(
  level INTEGER,
  idx INTEGER,
  start_block INTEGER,               -- Blockid of first node in %_segments
  leaves_end_block INTEGER,          -- Blockid of last leaf node in %_segments
  end_block INTEGER,                 -- Blockid of last node in %_segments
  root BLOB,                         -- B-tree root node
  PRIMARY KEY(level, idx)
);

The schema depicted above is not designed to store the full-text index directly. Instead, it is used to one or more b-tree structures. There is one b-tree for each row in the %_segdir table. The %_segdir table row contains the root node and various meta-data associated with the b-tree structure, and the %_segments table contains all other (non-root) b-tree nodes. Each b-tree is referred to as a "segment". Once it has been created, a segment b-tree is never updated (although it may be deleted altogether).

The keys used by each segment b-tree are terms (words). As well as the key, each segment b-tree entry has an associated "doclist" (document list). A doclist consists of zero or more entries, where each entry consists of:

  • A docid (document id), and
  • A list of term offsets, one for each occurrence of the term within the document. A term offset indicates the number of tokens (words) that occur before the term in question, not the number of characters or bytes. For example, the term offset of the term "war" in the phrase "Ancestral voices prophesying war!" is 3.

Entries within a doclist are sorted by docid. Positions within a doclist entry are stored in ascending order.

The contents of the logical full-text index is found by merging the contents of all segment b-trees. If a term is present in more than one segment b-tree, then it maps to the union of each individual doclist. If, for a single term, the same docid occurs in more than one doclist, then only the doclist that is part of the most recently created segment b-tree is considered valid.

Multiple b-tree structures are used instead of a single b-tree to reduce the cost of inserting records into FTS tables. When a new record is inserted into an FTS table that already contains a lot of data, it is likely that many of the terms in the new record are already present in a large number of existing records. If a single b-tree were used, then large doclist structures would have to be loaded from the database, amended to include the new docid and term-offset list, then written back to the database. Using multiple b-tree tables allows this to be avoided by creating a new b-tree which can be merged with the existing b-tree (or b-trees) later on. Merging of b-tree structures can be performed as a background task, or once a certain number of separate b-tree structures have been accumulated. Of course, this scheme makes queries more expensive (as the FTS code may have to look up individual terms in more than one b-tree and merge the results), but it has been found that in practice this overhead is often negligible.

8.1. Variable Length Integer (varint) Format

Integer values stored as part of segment b-tree nodes are encoded using the FTS varint format. This encoding is similar, but not identical, to the SQLite varint format.

An encoded FTS varint consumes between one and ten bytes of space. The number of bytes required is determined by the sign and magnitude of the integer value encoded. More accurately, the number of bytes used to store the encoded integer depends on the position of the most significant set bit in the 64-bit twos-complement representation of the integer value. Negative values always have the most significant bit set (the sign bit), and so are always stored using the full ten bytes. Positive integer values may be stored using less space.

The final byte of an encoded FTS varint has its most significant bit cleared. All preceding bytes have the most significant bit set. Data is stored in the remaining seven least significant bits of each byte. The first byte of the encoded representation contains the least significant seven bits of the encoded integer value. The second byte of the encoded representation, if it is present, contains the seven next least significant bits of the integer value, and so on. The following table contains examples of encoded integer values:

Decimal | Hexadecimal | Encoded Representation
43 | 0x000000000000002B | 0x2B
200815 | 0x000000000003106F | 0x9C 0xA0 0x0C
-1 | 0xFFFFFFFFFFFFFFFF | 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0x01

8.2. Segment B-Tree Format

Segment b-trees are prefix-compressed b+-trees. There is one segment b-tree for each row in the %_segdir table (see above). The root node of the segment b-tree is stored as a blob in the "root" field of the corresponding row of the %_segdir table. All other nodes (if any exist) are stored in the "blob" column of the %_segments table. Nodes within the %_segments table are identified by the integer value in the blockid field of the corresponding row. The following table describes the fields of the %_segdir table:

Column | Interpretation
level | Between them, the contents of the "level" and "idx" fields define the relative age of the segment b-tree. The smaller the value stored in the "level" field, the more recently the segment b-tree was created. If two segment b-trees are of the same "level", the segment with the larger value stored in the "idx" column is more recent. The PRIMARY KEY constraint on the %_segdir table prevents any two segments from having the same value for both the "level" and "idx" fields.
idx | See above.
start_block | The blockid that corresponds to the node with the smallest blockid that belongs to this segment b-tree. Or zero if the entire segment b-tree fits on the root node. If it exists, this node is always a leaf node.
leaves_end_block | The blockid that corresponds to the leaf node with the largest blockid that belongs to this segment b-tree. Or zero if the entire segment b-tree fits on the root node.
end_block | The blockid that corresponds to the interior node with the largest blockid that belongs to this segment b-tree. Or zero if the entire segment b-tree fits on the root node. If it exists, this node is always an interior node.
root | Blob containing the root node of the segment b-tree.

Apart from the root node, the nodes that make up a single segment b-tree are always stored using a contiguous sequence of blockids. Furthermore, the nodes that make up a single level of the b-tree are themselves stored as a contiguous block, in b-tree order. The contiguous sequence of blockids used to store the b-tree leaves are allocated starting with the blockid value stored in the "start_block" column of the corresponding %_segdir row, and finishing at the blockid value stored in the "leaves_end_block" field of the same row. It is therefore possible to iterate through all the leaves of a segment b-tree, in key order, by traversing the %_segments table in blockid order from "start_block" to "leaves_end_block".

8.2.1. Segment B-Tree Leaf Nodes

The following diagram depicts the format of a segment b-tree leaf node.

Segment B-Tree Leaf Node Format

The first term stored on each node ("Term 1" in the figure above) is stored verbatim. Each subsequent term is prefix-compressed with respect to its predecessor. Terms are stored within a page in sorted (memcmp) order.

8.2.2. Segment B-Tree Interior Nodes

The following diagram depicts the format of a segment b-tree interior (non-leaf) node.

Segment B-Tree Interior Node Format

8.3. Doclist Format

A doclist consists of an array of 64-bit signed integers, serialized using the FTS varint format. Each doclist entry is made up of a series of two or more integers, as follows:

  1. The docid value. The first entry in a doclist contains the literal docid value. The first field of each subsequent doclist entry contains the difference between the new docid and the previous one (always a positive number).
  2. Zero or more term-offset lists. A term-offset list is present for each column of the FTS virtual table that contains the term. A term-offset list consists of the following:
    1. Constant value 1. This field is omitted for any term-offset list associated with column 0.
    2. The column number (1 for the second leftmost column, etc.). This field is omitted for any term-offset list associated with column 0.
    3. A list of term-offsets, sorted from smallest to largest. Instead of storing the term-offset value literally, each integer stored is the difference between the current term-offset and the previous one (or zero if the current term-offset is the first), plus 2.
  3. Constant value 0.

FTS3 Doclist Format

FTS Doclist Entry Format

For doclists for which the term appears in more than one column of the FTS virtual table, term-offset lists within the doclist are stored in column number order. This ensures that the term-offset list associated with column 0 (if any) is always first, allowing the first two fields of the term-offset list to be omitted in this case.

Appendix A: Search Application Tips

FTS is primarily designed to support Boolean full-text queries - queries to find the set of documents that match a specified criteria. However, many (most?) search applications require that results are somehow ranked in order of "relevance", where "relevance" is defined as the likelihood that the user who performed the search is interested in a specific element of the returned set of documents. When using a search engine to find documents on the world wide web, the user expects that the most useful, or "relevant", documents will be returned as the first page of results, and that each subsequent page contains progressively less relevant results. Exactly how a machine can determine document relevance based on a users query is a complicated problem and the subject of much ongoing research.

One very simple scheme might be to count the number of instances of the users search terms in each result document. Those documents that contain many instances of the terms are considered more relevant than those with a small number of instances of each term. In an FTS application, the number of term instances in each result could be determined by counting the number of integers in the return value of the offsets function. The following example shows a query that could be used to obtain the ten most relevant results for a query entered by the user:

-- This example (and all others in this section) assumes the following schema
CREATE VIRTUAL TABLE documents USING fts3(title, content);

-- Assuming the application has supplied an SQLite user function named "countintegers"
-- that returns the number of space-separated integers contained in its only argument,
-- the following query could be used to return the titles of the 10 documents that contain
-- the greatest number of instances of the users query terms. Hopefully, these 10
-- documents will be those that the users considers more or less the most "relevant".
SELECT title FROM documents
  WHERE documents MATCH <query>
  ORDER BY countintegers(offsets(documents)) DESC
  LIMIT 10 OFFSET 0

The query above could be made to run faster by using the FTS matchinfo function to determine the number of query term instances that appear in each result. The matchinfo function is much more efficient than the offsets function. Furthermore, the matchinfo function provides extra information regarding the overall number of occurrences of each query term in the entire document set (not just the current row) and the number of documents in which each query term appears. This may be used (for example) to attach a higher weight to less common terms which may increase the overall computed relevancy of those results the user considers more interesting.

-- If the application supplies an SQLite user function called "rank" that
-- interprets the blob of data returned by matchinfo and returns a numeric
-- relevancy based on it, then the following SQL may be used to return the
-- titles of the 10 most relevant documents in the dataset for a users query.
SELECT title FROM documents
  WHERE documents MATCH <query>
  ORDER BY rank(matchinfo(documents)) DESC
  LIMIT 10 OFFSET 0

The SQL query in the example above uses less CPU than the first example in this section, but still has a non-obvious performance problem. SQLite satisfies this query by retrieving the value of the "title" column and matchinfo data from the FTS module for every row matched by the users query before it sorts and limits the results. Because of the way SQLite's virtual table interface works, retrieving the value of the "title" column requires loading the entire row from disk (including the "content" field, which may be quite large). This means that if the users query matches several thousand documents, many megabytes of "title" and "content" data may be loaded from disk into memory even though they will never be used for any purpose.

The SQL query in the following example block is one solution to this problem. In SQLite, when a sub-query used in a join contains a LIMIT clause, the results of the sub-query are calculated and stored in temporary table before the main query is executed. This means that SQLite will load only the docid and matchinfo data for each row matching the users query into memory, determine the docid values corresponding to the ten most relevant documents, then load only the title and content information for those 10 documents only. Because both the matchinfo and docid values are gleaned entirely from the full-text index, this results in dramatically less data being loaded from the database into memory.

SELECT title FROM documents JOIN (
    SELECT docid, rank(matchinfo(documents)) AS rank
    FROM documents
    WHERE documents MATCH <query>
    ORDER BY rank DESC
    LIMIT 10 OFFSET 0
) AS ranktable USING(docid)
ORDER BY ranktable.rank DESC

The next block of SQL enhances the query with solutions to two other problems that may arise in developing search applications using FTS:

  1. The snippet function cannot be used with the above query. Because the outer query does not include a "WHERE ... MATCH" clause, the snippet function may not be used with it. One solution is to duplicate the WHERE clause used by the sub-query in the outer query. The overhead associated with this is usually negligible.

  2. The relevancy of a document may depend on something other than just the data available in the return value of matchinfo. For example each document in the database may be assigned a static weight based on factors unrelated to its content (origin, author, age, number of references etc.). These values can be stored by the application in a separate table that can be joined against the documents table in the sub-query so that the rank function may access them.

This version of the query is very similar to that used by the sqlite.org documentation search application.

-- This table stores the static weight assigned to each document in FTS table
-- "documents". For each row in the documents table there is a corresponding row
-- with the same docid value in this table.
CREATE TABLE documents_data(docid INTEGER PRIMARY KEY, weight);

-- This query is similar to the one in the block above, except that:
--
--   1. It returns a "snippet" of text along with the document title for display. So
--      that the snippet function may be used, the "WHERE ... MATCH ..." clause from
--      the sub-query is duplicated in the outer query.
--
--   2. The sub-query joins the documents table with the document_data table, so that
--      implementation of the rank function has access to the static weight assigned
--      to each document.
SELECT title, snippet(documents) FROM documents JOIN (
    SELECT docid, rank(matchinfo(documents), documents_data.weight) AS rank
    FROM documents JOIN documents_data USING(docid)
    WHERE documents MATCH <query>
    ORDER BY rank DESC
    LIMIT 10 OFFSET 0
) AS ranktable USING(docid)
WHERE documents MATCH <query>
ORDER BY ranktable.rank DESC

All the example queries above return the ten most relevant query results. By modifying the values used with the OFFSET and LIMIT clauses, a query to return (say) the next ten most relevant results is easy to construct. This may be used to obtain the data required for a search applications second and subsequent pages of results.

The next block contains an example rank function that uses matchinfo data implemented in C. Instead of a single weight, it allows a weight to be externally assigned to each column of each document. It may be registered with SQLite like any other user function using sqlite3_create_function.

/*
** SQLite user defined function to use with matchinfo() to calculate the
** relevancy of an FTS match. The value returned is the relevancy score
** (a real value greater than or equal to zero). A larger value indicates
** a more relevant document.
**
** The overall relevancy returned is the sum of the relevancies of each
** column value in the FTS table. The relevancy of a column value is the
** sum of the following for each reportable phrase in the FTS query:
**
**   (<hit count> / <global hit count>) * <column weight>
**
** where <hit count> is the number of instances of the phrase in the
** column value of the current row and <global hit count> is the number
** of instances of the phrase in the same column of all rows in the FTS
** table. The <column weight> is a weighting factor assigned to each
** column by the caller (see below).
**
** The first argument to this function must be the return value of the FTS
** matchinfo() function. Following this must be one argument for each column
** of the FTS table containing a numeric weight factor for the corresponding
** column. Example:
**
**     CREATE VIRTUAL TABLE documents USING fts3(title, content)
**
** The following query returns the docids of documents that match the full-text
** query <query> sorted from most to least relevant. When calculating
** relevance, query term instances in the 'title' column are given twice the
** weighting of those in the 'content' column.
**
**     SELECT docid FROM documents
**     WHERE documents MATCH <query>
**     ORDER BY rank(matchinfo(documents), 1.0, 0.5) DESC
*/
static void rankfunc(sqlite3_context *pCtx, int nVal, sqlite3_value **apVal){
  int *aMatchinfo;                /* Return value of matchinfo() */
  int nCol;                       /* Number of columns in the table */
  int nPhrase;                    /* Number of phrases in the query */
  int iPhrase;                    /* Current phrase */
  double score = 0.0;             /* Value to return */

  assert( sizeof(int)==4 );

  /* Check that the number of arguments passed to this function is correct.
  ** If not, jump to wrong_number_args. Set aMatchinfo to point to the array
  ** of unsigned integer values returned by FTS function matchinfo. Set
  ** nPhrase to contain the number of reportable phrases in the users full-text
  ** query, and nCol to the number of columns in the table.
  */
  if( nVal<1 ) goto wrong_number_args;
  aMatchinfo = (unsigned int *)sqlite3_value_blob(apVal[0]);
  nPhrase = aMatchinfo[0];
  nCol = aMatchinfo[1];
  if( nVal!=(1+nCol) ) goto wrong_number_args;

  /* Iterate through each phrase in the users query. */
  for(iPhrase=0; iPhrase<nPhrase; iPhrase++){
    int iCol;                     /* Current column */

    /* Now iterate through each column in the users query. For each column,
    ** increment the relevancy score by:
    **
    **   (<hit count> / <global hit count>) * <column weight>
    **
    ** aPhraseinfo[] points to the start of the data for phrase iPhrase. So
    ** the hit count and global hit counts for each column are found in
    ** aPhraseinfo[iCol*3] and aPhraseinfo[iCol*3+1], respectively.
    */
    int *aPhraseinfo = &aMatchinfo[2 + iPhrase*nCol*3];
    for(iCol=0; iCol<nCol; iCol++){
      int nHitCount = aPhraseinfo[3*iCol];
      int nGlobalHitCount = aPhraseinfo[3*iCol+1];
      double weight = sqlite3_value_double(apVal[iCol+1]);
      if( nHitCount>0 ){
        score += ((double)nHitCount / (double)nGlobalHitCount) * weight;
      }
    }
  }

  sqlite3_result_double(pCtx, score);
  return;

  /* Jump here if the wrong number of arguments are passed to this function */
wrong_number_args:
  sqlite3_result_error(pCtx, "wrong number of arguments to function rank()", -1);
}


How To Compile SQLite

SQLite is ANSI-C source code. It must be compiled into machine code before it is useful. This article is a guide to the various ways of compiling SQLite.

This article does not contain a step-by-step recipe for compiling SQLite. That would be difficult since each development situation is different. Rather, this article describes and illustrates the principals behind the compilation of SQLite. Typical compilation commands are provided as examples with the expectation that application developers can use these examples as guidance for developing their own custom compilation procedures. In other words, this article provides ideas and insights, not turnkey solutions.

Amalgamation Versus Individual Source Files

SQLite is built from literally hundreds of files of C code and script spread across multiple directories. The implementation of SQLite is pure ANSI-C, but many of the C-language source code files are either either generated or transformed by auxiliary C programs and AWK, SED, and TCL scripts prior to being incorporated into the finished SQLite library. Building the necessary C programs and transforming and/or creating the C-language source code for SQLite is a complex process.

To simplify matters, SQLite is also available as a pre-packaged amalgamation source code file: sqlite3.c. The amalgamation is a single file of ANSI-C code that implements the entire SQLite library. The amalgamation is much easier to deal with. Everything is contained within a single code files, so it is easy to drop into the source tree of a larger C or C++ program. All the code generation and transformation steps have already been carried out so there are no auxiliary C programs to configure and compile and no scripts to run. And, because the entire library is contained in a single translation unit, compilers are able to do more advanced optimizations resulting in a 5% to 10% performance improvement. For these reasons, the amalgamation source file ("sqlite3.c") is recommended for all applications.

The use of the amalgamation is recommended for all applications.

Building SQLite directly from individual source code files is certainly possible, but it is not recommended. For some specialized applications, it might be necessary to modify the build process in ways that cannot be done using just the prebuilt amalgamation source file downloaded from the website. For those situations, it is recommended that a customized amalgamation be built (as described below) and used. In other words, even if a project requires building SQLite beginning with individual source files, it is still recommended that an amalgamation source file be used as an intermediate step.

Compiling The Command-Line Interface

A build of the command-line interface requires three source files:

  • sqlite3.c: The SQLite amalgamation source file
  • sqlite3.h: The header files that accompanies sqlite3.c and defines the C-language interfaces to SQLite.
  • shell.c: The command-line interface program itself. This is the C source code file that contains the definition of the main() routine and the loop that prompts for user input and passes that input into the SQLite database engine for processing.

All three of the above source files are contained in the amalgamation tarball available on the download page.

To build the CLI, simply put these three files in the same directory and compile them together. The command to compile C programs varies from one machine to the next but on unix systems typically looks something like this:

gcc shell.c sqlite3.c -lpthread -ldl

The pthreads library is needed to make SQLite threadsafe. But since the CLI is single threaded, we could instruct SQLite to build in a non-threadsafe mode and thereby omit the pthreads library:

gcc -DSQLITE_THREADSAFE=0 shell.c sqlite3.c -ldl

The -ldl library is needed to support dynamic loading, the sqlite3_load_extension() interface and the load_extension() SQL function. If these features are not required, then they can be omitted using SQLITE_OMIT_LOAD_EXTENSION compile-time option:

gcc -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION shell.c sqlite3.c

One might want to provide other compile-time options such as SQLITE_ENABLE_FTS3 for full-text search or SQLITE_ENABLE_RTREE for the R*Tree search engine extension. And one would normally to specify some compiler optimization switches too. (The precompiled CLI available for download from the SQLite website uses "-Os".) There are countless possible variations here.

The key point is this: Building the CLI consists of compiling together two C-language files. The shell.c file contains the definition of the entry point and the user input loop and the SQLite amalgamation sqlite3.c contains the complete implementation of the SQLite library.

Compiling The TCL Interface

The TCL interface for SQLite is a small module that is added into the regular amalgamation. The result is a new amalgamated source file called "tclsqlite3.c". This single source file is all that is needed to generate a shared library that can be loaded into a standard tclsh or wish using the TCL load command, or to generate a standalone tclsh that comes with SQLite built in. A copy of the tcl amalgamation is included on the download page as a file in the TEA tarball.

To generate a TCL-loadable library for SQLite on Linux, the following command will suffice:

gcc -o libtclsqlite3.so -shared tclsqlite3.c -lpthread -ldl -ltcl

Building shared libraries for Mac OS X and Windows is not nearly so simple, unfortunately. For those platforms it is best to use the configure script and makefile that is included with the TEA tarball.

To generate a standalone tclsh that is statically linked with SQLite, use this compiler invocation:

gcc -DTCLSH=1 tclsqlite3.c -ltcl -lpthread -ldl -lz -lm

The trick here is the -DTCLSH=1 option. The TCL interface module for SQLite includes a main() procedure that initializes a TCL interpreter and enters a command-line loop when it is compiled with -DTCLSH=1. The command above works on both Linux and Mac OS X, though one may need to adjust the library options depending on the platform and which version of TCL one is linking against.

Building The Amalgamation

The versions of the SQLite amalgamation that are supplied on the download page are normally adequate for most users. However, some projects may want or need to build their own amalgamations. A common reason for building a custom amalgamation is in order to use certain compile-time options to customize the SQLite library. Recall that the SQLite amalgamation contains a lot of C-code that is generated by auxiliary programs and scripts. Many of the compile-time options effect this generated code and must be supplied to the code generators before the amalgamation is assembled. The set of compile-time options that must be passed into the code generators can vary from one release of SQLite to the next, but at the time of this writing (circa SQLite 3.6.20, 2009-11-04) the set of options that must be known by the code generators includes:

  • SQLITE_ENABLE_UPDATE_DELETE_LIMIT
  • SQLITE_OMIT_ALTERTABLE
  • SQLITE_OMIT_ANALYZE
  • SQLITE_OMIT_ATTACH
  • SQLITE_OMIT_AUTOINCREMENT
  • SQLITE_OMIT_CAST
  • SQLITE_OMIT_COMPOUND_SELECT
  • SQLITE_OMIT_EXPLAIN
  • SQLITE_OMIT_FOREIGN_KEY
  • SQLITE_OMIT_PRAGMA
  • SQLITE_OMIT_REINDEX
  • SQLITE_OMIT_SUBQUERY
  • SQLITE_OMIT_TEMPDB
  • SQLITE_OMIT_TRIGGER
  • SQLITE_OMIT_VACUUM
  • SQLITE_OMIT_VIEW
  • SQLITE_OMIT_VIRTUALTABLE

To build a custom amalgamation, first download the original individual source files onto a unix or unix-like development platform. (Any Linux or Mac OS X machine will suffice. Windows will work if loaded with Cygwin.) Be sure to get the original source files not the "preprocessed source files". One can obtain the complete set of original source files either from the download page or directly from the configuration management system.

Suppose the SQLite source tree is stored in a directory named "sqlite". Plan to construct the amalgamation in a parallel directory named (for example) "bld". First construct an appropriate Makefile by either running the configure script at the top of the SQLite source tree, or by making a copy of one of the template Makefiles at the top of the source tree. Then hand edit this Makefile to include the desired compile-time options. Finally run:

make sqlite3.c

The "sqlite3.c" make target will automatically construct the regular "sqlite3.c" amalgamation source file, its header file "sqlite3.h", and the "tclsqlite3.c" amalgamation source file that includes the TCL interface. Afterwards, the needed files can be copied into project directories and compiled according to the procedures outlined above.


How To Corrupt An SQLite Database File

An SQLite database is highly resistant to corruption. If an application crash, or an operating-system crash, or even a power failure occurs in the middle of a transaction, the partially written transaction should be automatically rolled back the next time the database file is accessed. The recovery process is fully automatic and does not require any action on the part of the user or the application.

Though SQLite is resistant to database corruption, it is not immune. This document describes the various ways that an SQLite database might go corrupt.

1.0 File overwrite by a rogue thread or process

SQLite database files are ordinary disk files. That means that any process can open the file and overwrite it with garbage. There is nothing that the SQLite library can do to defend against this.

1.1 Continuing to use a file descriptor after it has been closed

We have seen cases where a file descriptor was open on a log file, then that file descriptor was closed and reopened on an SQLite database. Later, some other thread continued to write log information into the old file descriptor, not realizing that the log file had been closed already. But because the file descriptor had been reopened by SQLite, the information that was intended to go into the log file ended up overwriting parts of the SQLite database, leading to corruption of the database.

1.2 Backup or restore while a transaction is active

Systems that run automatic backups in the background might try to make a backup copy of an SQLite database file while it is in the middle of a transaction. The backup copy then might contain some old and some new content, and thus be corrupt.

The best approach to make reliable backup copies of an SQLite database is to make use of the backup API that is part of the SQLite library. Failing that, it is safe to make a copy of an SQLite database file as long as there are no transactions in progress by any process. If the previous transaction failed, then it is important that any rollback journal (the *-journal file) or write-ahead log (the *-wal file) be copied together with the database file itself.

1.3 Deleting a hot journal

SQLite normally stores all content in a single disk file. However, while performing a transaction, information necessary to roll back that transaction following a crash or power failure is stored in auxiliary journal files. These journal files have the same name as the original database file with the addition of -journal or -wal suffix.

SQLite must see the journal files in order to recover from a crash or power failure. If the journal files are moved, deleted, or renamed after a crash or power failure, then automatic recovery will not work and the database may go corrupt.

Another manifestation of this problem is database corruption caused by inconsistent use of 8+3 filenames.

2.0 File locking problems

SQLite uses file locks on the database file, and on the write-ahead log or WAL file, to coordinate access between concurrent processes. Without coordination, two threads or processes might try to make incompatible changes to a database file at the same time, resulting in database corruption.

2.1 Filesystems with broken or missing lock implementations

SQLite depends on the underlying filesystem to do locking as the documentation says it will. But some filesystems contain bugs in their locking logic such that the locks do not always behave as advertised. This is especially true of network filesystems and NFS in particular. If SQLite is used on a filesystem where the locking primitives contain bugs, and if two or more threads or processes try to access the same database at the same time, then database corruption might result.

2.2 Posix advisory locks canceled by a separate thread doing close()

The default locking mechanism used by SQLite on unix platforms is POSIX advisory locking. Unfortunately, POSIX advisory locking has design quirks that make it prone to misuse and failure. In particular, any thread in the same process with a file descriptor that is holding a POSIX advisory lock can override that lock using a different file descriptor. One particularly pernicious problem is that the close() system call will cancel all POSIX advisory locks on the same file for all threads and all file descriptors in the process.

So, for example, suppose a multi-thread process has two or more threads with separate SQLite database connections to the same database file. Then a third thread comes along and wants to read something out of that same database file on its own, without using the SQLite library. The third thread does an open(), a read() and then a close(). One would think this would be harmless. But the close() system call caused the locks held on the database by all the other threads to be dropped. Those other threads have no way of knowing that their locks have just been trashed (POSIX does not provide any mechanism to determine this) and so they keep on running under the assumption that their locks are still valid. This can lead to two or more threads or processes trying to write to the database at the same time, resulting in database corruption.

Note that it is perfectly safe for two or more threads to access the same SQLite database file using the SQLite library. The unix drivers for SQLite know about the POSIX advisory locking quirks and work around them. This problem only arises when a thread tries to bypass the SQLite library and read the database file directly.

2.2.1 Multiple copies of SQLite linked into the same application

As pointed out in the previous paragraph, SQLite takes steps to work around the quirks of POSIX advisory locking. Part of that work-around involves keeping a global list (mutex protected) of open SQLite database files. But, if multiple copies of SQLite are linked into the same application, then there will be multiple instances of this global list. Database connections opened using one copy of the SQLite library will be unaware of database connections opened using the other copy, and will be unable to work around the POSIX advisory locking quirks. A close() operation on one connection might unknowingly clear the locks on a different database connection, leading to database corruption.

The scenario above sounds far-fetched. But the SQLite developers are aware of at least one commercial product that was release with exactly this bug. The vendor came to the SQLite developers seeking help in tracking down some infrequent database corruption issues they were seeing on Linux and Mac. The problem was eventually traced to the fact that the application was linking against two separate copies of SQLite. The solution was to change the application build procedures to link against just one copy of SQLite instead of two.

2.3 Two processes using different locking protocols

The default locking mechanism used by SQLite on unix platforms is POSIX advisory locking, but there are other options. By selecting an alternative sqlite3_vfs using the sqlite3_open_v2() interface, an application can make use of other locking protocols that might be more appropriate to certain filesystems. For example, dot-file locking might be select for use in an application that has to run on an NFS filesystem that does not support POSIX advisory locking.

It is important that all connections to the same database file use the same locking protocol. If one application is using POSIX advisory locks and another application is using dot-file locking, then the two applications will not see each others locks and will not be able to coordinate database access, possibly leading to database corruption.

3.0 Failure to sync

In order to guarantee that database files are always consistent, SQLite will occasionally ask the operating system to flush all pending writes to persistent storage then wait for that flush to complete. This is accomplished using the fsync() system call under unix and FlushFileBuffers() under windows. We call this flush of pending writes a "sync".

Actually, if one is only concerned with atomic and consistent writes and is willing to forego durable writes, the sync operation does not need to wait until the content is completely stored on persistent media. Instead, the sync operation can be thought of as an I/O barrier. As long as all writes that occur before the sync are completed before any write that happens after the sync, no database corruption will occur. If sync is operating as an I/O barrier and not as a true sync, then a power failure or system crash might cause one or more previously committed transactions to roll back (in violation of the "durable" property of "ACID") but the database will at least continue to be consistent, and that is what most people care about.

3.1 Disk drives that do not honor sync requests

Unfortunately, most consumer-grade mass storage devices lie about syncing. Disk drives will report that content is safely on persistent media as soon as it reaches the track buffer and before actually being written to oxide. This makes the disk drives seem to operate faster (which is vitally important to the manufacturer so that they can show good benchmark numbers in trade magazines). And in fairness, the lie normally causes no harm, as long as there is no power loss or hard reset prior to the track buffer actually being written to oxide. But if a power loss or hard reset does occur, and if that results in content that was written after a sync reaching oxide while content written before the sync is still in a track buffer, then database corruption can occur.

USB flash memory sticks seem to be especially pernicious liars regarding sync requests. One can easily see this by committing a large transaction to an SQLite database on a USB memory stick. The COMMIT command will return relatively quickly, indicating that the memory stick has told the operating system and the operating system has told SQLite that all content is safely in persistent storage, and yet the LED on the end of the memory stick will continue flashing for several more seconds. Pulling out the memory stick while the LED is still flashing will frequently result in database corruption.

Note that SQLite must believe whatever the operating system and hardware tell it about the status of sync requests. There is no way for SQLite to detect that either is lying and that writes might be occurring out-of-order. However, SQLite in WAL mode is far more forgiving of out-of-order writes than in the default rollback journal modes. In WAL mode, the only time that a failed sync operation can cause database corruption is during a checkpoint operation. A sync failure during a COMMIT might result in loss of durability but not in a corrupt database file. Hence, one line of defense against database corruption due to failed sync operations is to use SQLite in WAL mode and to checkpoint as infrequently as possible.

3.2 Disabling sync using PRAGMAs

The sync operations that SQLite performs to help ensure integrity can be disabled at run-time using the synchronous pragma. By setting PRAGMA synchronous=OFF, all sync operations are omitted. This makes SQLite seem to run faster, but it also allows the operating system to freely reorder writes, which could result in database corruption if a power failure or hard reset occurs prior to all content reaching persistent storage.

For maximum reliability and for robustness against database corruption, SQLite should always be run with its default synchronous setting of FULL.

4.0 Disk drive failures

An SQLite database can become corrupt if the content changes on disk due to a disk drive failure. It is very rare, but disks will occasionally flip a bit in the middle of a sector.

We are told that in some flash memory controllers the wear-leveling logic can cause random filesystem damage if power is interrupted during a write. This can manifest, for example, as random changes in the middle of a file that was not even open at the time of the power loss. So, for example, a device would be writing content into an MP3 file in flash memory when a power loss occurs, and that could result in an SQLite database being corrupted even though the database as not even in use at the time of the power loss.

5.0 Memory corruption

SQLite is a C-library that runs in the same address space as the application that it serves. That means that stray pointers, buffer overruns, heap corruption, or other malfunctions in application can corrupt internal SQLite data structure and ultimately result in a corrupt database file. Normally these kinds of problems manifest themselves as segfaults prior to any database corruption occurring, but there have been instances where application code errors have caused SQLite to malfunction subtly so as to corrupt the database file rather than panicking.

6.0 Other operating system problems

Sometimes operating systems will exhibit non-standard behavior which can lead to problems. Sometimes this non-standard behavior is deliberate, and sometimes it is a mistake in the implementation. But in any event, if the operating performs differently from they way SQLite expects it to perform, the possibility of database corruption exists.

6.1 Linux Threads

Some older versions of Linux used the LinuxThreads library for thread support. LinuxThreads is similar to Pthreads, but is subtly different with respect to handling of POSIX advisory locks. SQLite versions 2.2.3 through 3.6.23 recognized that LinuxThreads where being used at runtime and took appropriate action to work around the non-standard behavior of LinuxThreads. But most modern Linux implementations make use of the newer, and correct, NPTL implementation of Pthreads. Beginning with SQLite version 3.7.0, the use of NPTL is assumed. No checks are made. Hence, recent versions of SQLite will subtly malfunction and may corrupt database files if used in multi-threaded application that run on older linux systems that make use of LinuxThreads.

6.2 Failures of mmap() on QNX

There exists some subtle problem with mmap() on QNX such that making a second mmap() call against the a single file descriptor can cause the memory obtained from the first mmap() call to be zeroed. SQLite on unix uses mmap() to create a shared memory region for transaction coordination in WAL mode, and it will call mmap() multiple times for large transactions. The QNX mmap() has been demonstrated to corrupt database file under that scenario. QNX engineers are aware of this problem and are working on a solution; the problem may have already been fixed by the time you read this.

7.0 Bugs in SQLite

SQLite is very carefully tested to help ensure that it is as bug-free as possible. Among the many tests that are carried out for every SQLite version are tests that simulate power failures, I/O errors, and out-of-memory (OOM) errors and verify that no database corrupt occurs during any of these events. SQLite is also field-proven with approximately two billion active deployments with no serious problems.

Nevertheless, no software is 100% perfect. There have been a few historical bugs in SQLite (now fixed) that could cause database corruption. And there may be yet a few more that remain undiscovered. Because of the extensive testing and widespread use of SQLite, bugs that result in database corruption tend to be very obscure. The likelihood of an application encountering an SQLite bug is small. To illustrate this, an account is given below of all database-corruption bugs found in SQLite during the two-year period from 2009-04-01 to 2011-04-01. This account should give the reader an intuitive sense of the kinds of bugs in SQLite that manage to slip through testing procedures and make it into a release.

7.1 False corruption reports due to database shrinkage

If a database is written by SQLite version 3.7.0 or later and then written again by SQLite version 3.6.23 or earlier in such a way as to make the size of the database file decrease, then the next time that SQLite version 3.7.0 access the database file, it might report that the database file is corrupt. The database file is not really corrupt, however. Version 3.7.0 was simply begin overly zealous in its corruption detection.

The problem was fixed on 2011-02-20. The fix first appears in SQLite version 3.7.6.

7.2 Corruption follow switches between rollback and WAL modes

Repeatedly switching an SQLite database in and out of WAL mode and running the VACUUM command in between switches, in one process or thread, can cause another process or thread that has the database file open to miss the fact that the database has changed. That second process or thread might then try to modify the database using a stale cache and cause database corruption.

This problem was discovered during internal testing and has never been observed in the wild. The problem was fixed on 2011-01-27 and in version 3.7.5.

7.3 I/O while obtaining a lock leads to corruption

If the operating system returns an I/O error while attempting to obtain a certain lock on shared memory in WAL mode then SQLite might fail to reset its cache, which could lead to database corruption if subsequent writes are attempted.

Note that this problem only occurs if the attempt to acquire the lock resulted in an I/O error. If the lock is simply not granted (because some other thread or process is already holding a conflicting lock) then no corruption will ever occur. We are not aware of any operating systems that will fail with an I/O error while attempting to get a file lock on shared memory. So this is a theoretical problem rather than a real problem. Needless to say, this problem has never been observed in the wild. The problem was discovered while doing stress testing of SQLite in a test harness that simulates I/O errors.

This problem was fixed on 2010-09-20 for SQLite version 3.7.3.

7.4 Database pages leak from the free page list

When content is deleted from an SQLite database, pages that are no longer used are added to a free list and are reused to hold content added but subsequent inserts. A bug in SQLite that was present in version 3.6.16 through 3.7.2 might cause pages to go missing out of the free list when incremental_vacuum was used. This would not cause data loss. But it would result in the database file being larger than necessary. And it would cause the integrity_check pragma to report pages missing from the free list.

This problem was fixed on 2010-08-23 for SQLite version 3.7.2.

7.5 Corruption following alternating writes from 3.6 and 3.7.

SQLite version 3.7.0 introduced a number of new enhancements to the SQLite database file format (such as but not limited to WAL). The 3.7.0 release was a shake-out release for these new features. We expected to find problems and were not disappointed.

If a database were originally created using SQLite version 3.7.0, then written by SQLite version 3.6.23.1 such that the size of the database file increased, then written again by SQLite version 3.7.0, the database file could go corrupt.

This problem was fixed on 2010-08-04 for SQLite version 3.7.1.


SQLite Home Page

Choose any three.
About Sitemap Documentation Download License News Support

Welcome.

SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. SQLite is the most widely deployed SQL database engine in the world. The source code for SQLite is in the public domain.

Sponsors

Ongoing development and maintenance of SQLite is sponsored in part by SQLite Consortium members, including:

Current Status

  • Version 3.7.9 of SQLite is recommended for all new development. Upgrading from version 3.7.6.3, 3.7.7, 3.7.7.1, or 3.7.8 is optional. Upgrading from all other SQLite versions is recommended.

Common Links

  • Features
  • Frequently Asked Questions
  • Well-known Users
  • Getting Started
  • SQL Syntax
    • Pragmas
    • SQL functions
    • Date & time functions
    • Aggregate functions
  • C/C++ Interface Spec
    • Introduction
    • List of C-language APIs
  • The TCL Interface Spec
  • Development Timeline
  • Report a Bug


In-Memory Databases

An SQLite database is normally stored in a single ordinary disk file. However, in certain circumstances, the database might be stored in memory.

The most common way to force an SQLite database to exist purely in memory is to open the database using the special filename ":memory:". In other words, instead of passing the name of a real disk file into one of the sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() functions, pass in the string ":memory:". For example:

rc = sqlite3_open(":memory:", &db);

When this is done, no disk file is opened. Instead, a new database is created purely in memory. The database ceases to exist as soon as the database connection is closed. Every :memory: database is distinct from every other. So, opening two database connections each with the filename ":memory:" will create two independent in-memory databases.

The special filename ":memory:" can be used anywhere that a database filename is permitted. For example, it can be used as the filename in an ATTACH command:

ATTACH DATABASE ':memory:' AS aux1;

Note that in order for the special ":memory:" name to apply and to create a pure in-memory database, there must be no additional text in the filename. Thus, a disk-based database can be created in a file by prepending a pathname, like this: "./:memory:".

Temporary Databases

When the name of the database file handed to sqlite3_open() or to ATTACH is an empty string, then a new temporary file is created to hold the database.

rc = sqlite3_open("", &db);
ATTACH DATABASE '' AS aux2;

A different temporary file is created each time, so that just like as with the special ":memory:" string, two database connections to temporary databases each have their own private database. Temporary databases are automatically deleted when the connection that created them closes.

Even though a disk file is allocated for each temporary database, in practice the temporary database usually resides in the in-memory pager cache and hence is very little difference between a pure in-memory database created by ":memory:" and a temporary database created by an empty filename. The sole difference is that a ":memory:" database must remain in memory at all times whereas parts of a temporary database might be flushed to disk if database becomes large or if SQLite comes under memory pressure.

The previous paragraphs describe the behavior of temporary databases under the default SQLite configuration. An application can use the temp_store pragma and the SQLITE_TEMP_STORE compile-time parameter to force temporary databases to behave as pure in-memory databases, if desired.


Internal Versus External BLOBs

Choose any three.
About Sitemap Documentation Download License News Support

Internal Versus External BLOBs in SQLite

If you have a database of large BLOBs, do you get better read performance when you store the complete BLOB content directly in the database or is it faster to store each BLOB in a separate file and store just the corresponding filename in the database?

To try answer this, we ran 49 test cases with various BLOB sizes and SQLite page sizes on a Linux workstation (Ubuntu circa 2011 with the Ext4 filesystem on a fast SATA disk). For each test case, a database was created that contains 100MB of BLOB content. The sizes of the BLOBs ranged from 10KB to 1MB. The number of BLOBs varied in order to keep the total BLOB content at about 100MB. (Hence, 100 BLOBs for the 1MB size and 10000 BLOBs for the 10K size and so forth.) SQLite version 3.7.8 was used.

The matrix below shows the time needed to read BLOBs stored in separate files divided by the time needed to read BLOBs stored entirely in the database. Hence, for numbers larger than 1.0, it is faster to store the BLOBs directly in the database. For numbers smaller than 1.0, it is faster to store the BLOBs in separate files.

In every case, the pager cache size was adjusted to keep the amount of cache memory at about 2MB. For example, a 2000 page cache was used for 1024 byte pages and a 31 page cache was used for 65536 byte pages. The BLOB values were read in a random order.

Database Page Size | BLOB size
 | 10k | 20k | 50k | 100k | 200k | 500k | 1m
1024 | 1.535 | 1.020 | 0.608 | 0.456 | 0.330 | 0.247 | 0.233
2048 | 2.004 | 1.437 | 0.870 | 0.636 | 0.483 | 0.372 | 0.340
4096 | 2.261 | 1.886 | 1.173 | 0.890 | 0.701 | 0.526 | 0.487
8192 | 2.240 | 1.866 | 1.334 | 1.035 | 0.830 | 0.625 | 0.720
16384 | 2.439 | 1.757 | 1.292 | 1.023 | 0.829 | 0.820 | 0.598
32768 | 1.878 | 1.843 | 1.296 | 0.981 | 0.976 | 0.675 | 0.613
65536 | 1.256 | 1.255 | 1.339 | 0.983 | 0.769 | 0.687 | 0.609

We deduce the following rules of thumb from the matrix above:

  • A database page size of 8192 or 16384 gives the best performance for large BLOB I/O.

  • For BLOBs smaller than 100KB, reads are faster when the BLOBs are stored directly in the database file. For BLOBs larger than 100KB, reads from a separate file are faster.

Of course, your mileage may vary depending on hardware, filesystem, and operating system. Double-check these figures on target hardware before committing to a particular design.


Website Keyword Index

Other Documentation Indices:
  • Categorical Document List
  • Books About SQLite
  • Alphabetical List Of Documents
  • Permuted Document Title Index
  • abs() SQL function
  • affinity
  • Aggregate Functions
  • alphabetical listing of SQLite documents
  • ALTER TABLE
  • alter-table-stmt syntax diagram
  • amalgamation
  • amalgamation tarball
  • ANALYZE
  • analyze-stmt syntax diagram
  • application file-format
  • application-defined SQL function
  • asynchronous I/O backend
  • asynchronous VFS
  • atomic commit
  • ATTACH DATABASE
  • attach-stmt syntax diagram
  • auto_vacuum pragma
  • autocommit mode
  • AUTOINCREMENT
  • automatic indexing
  • Automatic indexing
  • automatic_index pragma
  • avg() aggregate function
  • backup API
  • BEGIN TRANSACTION
  • begin-stmt syntax diagram
  • BETWEEN
  • BINARY collating function
  • binary operators
  • BLOB handle
  • books about SQLite
  • boolean datatype
  • boolean expression
  • bound parameter
  • btree design
  • build product names
  • building the amalgamation
  • built-in memory allocators
  • C-API function list
  • C-language Interface
  • cache_size pragma
  • CASE expression
  • case_sensitive_like pragma
  • CAST expression
  • categorical listing of SQLite documents
  • cell format summary
  • cell payload
  • change counter
  • changes() SQL function
  • CHECK
  • CHECK constraint
  • checkpoint
  • checkpoint_fullfsync pragma
  • checkpointed
  • checkpointing
  • child key
  • child table
  • CLI
  • coalesce() SQL function
  • COLLATE operator
  • collating function
  • collation_list pragma
  • column access functions
  • column affinity
  • column definition
  • column-constraint syntax diagram
  • column-def syntax diagram
  • Command Line Interface
  • command-line shell
  • comment
  • comment-syntax syntax diagram
  • COMMIT
  • commit-stmt syntax diagram
  • comparison affinity rules
  • comparison expressions
  • compile fts
  • compile-time options
  • compile_options pragma
  • compiling the CLI
  • compiling the TCL interface
  • compound query
  • compound select
  • compound-operator syntax diagram
  • compressed FTS4 content
  • configuration option
  • conflict clause
  • conflict-clause syntax diagram
  • constraints
  • Core Functions
  • core URI query parameters
  • count() aggregate function
  • count_changes pragma
  • covering index
  • covering indices
  • CREATE INDEX
  • CREATE TABLE
  • CREATE TRIGGER
  • CREATE VIEW
  • CREATE VIRTUAL TABLE
  • create-index-stmt syntax diagram
  • create-table-stmt syntax diagram
  • create-trigger-stmt syntax diagram
  • create-view-stmt syntax diagram
  • create-virtual-table-stmt syntax diagram
  • custom builds
  • custom r-tree queries
  • database connection
  • database corruption caused by inconsistent use of 8+3 filenames
  • database header
  • Database Object Name Resolution
  • database_list pragma
  • datatype
  • date and time datatype
  • Date And Time Functions
  • date() SQL function
  • datetime() SQL function
  • debugging memory allocator
  • default memory allocator
  • default_cache_size pragma
  • DELETE
  • delete-stmt syntax diagram
  • delete-stmt-limited syntax diagram
  • deleting a hot journal
  • deprecated
  • DETACH DATABASE
  • detach-stmt syntax diagram
  • DISTINCT
  • download page
  • DROP INDEX
  • DROP TABLE
  • DROP TRIGGER
  • DROP VIEW
  • drop-index-stmt syntax diagram
  • drop-table-stmt syntax diagram
  • drop-trigger-stmt syntax diagram
  • drop-view-stmt syntax diagram
  • dynamic typing
  • empty_result_callbacks pragma
  • encoding pragma
  • enhanced query syntax
  • error code
  • ESCAPE
  • EXCLUSIVE lock
  • EXISTS operator
  • experimental
  • experimental memory allocators
  • EXPLAIN
  • explain query plan
  • EXPLAIN QUERY PLAN
  • expr syntax diagram
  • expression affinity
  • expression syntax
  • extended error code
  • extended result code
  • file format
  • file I/O
  • file locking and concurrency control
  • file locking states
  • flattening optimization
  • footprint
  • foreign key actions
  • foreign key constraint
  • FOREIGN KEY constraints
  • foreign key constraints are enabled
  • foreign-key-clause syntax diagram
  • foreign_key_list pragma
  • foreign_keys pragma
  • free-page list
  • freelist
  • freelist_count pragma
  • FROM clause
  • FTS auxiliary functions
  • FTS hidden column
  • FTS MATCH
  • FTS shadow tables
  • FTS3
  • FTS4
  • fts4 compress option
  • FTS4 options
  • FTS4 order option
  • FTS4 prefix option
  • fts4 prefix option
  • fts4aux
  • full-text search
  • full_column_names pragma
  • fullfsync pragma
  • function creation routines
  • GLOB
  • glob() SQL function
  • GROUP BY
  • group_concat() aggregate function
  • hex() SQL function
  • hidden column
  • host parameter
  • host parameter name
  • hot journal
  • how to compile
  • how to corrupt
  • How To Corrupt Your Database Files
  • ifnull() SQL function
  • ignore_check_constraints pragma
  • IN operator
  • in-header database size
  • in-memory database
  • incremental_vacuum pragma
  • index_info pragma
  • index_list pragma
  • INDEXED BY
  • indexed-column syntax diagram
  • indexing
  • indexing tutorial
  • INSERT
  • insert-stmt syntax diagram
  • INSTEAD OF
  • INSTEAD OF trigger
  • INTEGER PRIMARY KEY
  • integrity_check pragma
  • IS NOT operator
  • IS operator
  • join order
  • join-constraint syntax diagram
  • join-op syntax diagram
  • join-source syntax diagram
  • journal_mode pragma
  • journal_size_limit pragma
  • julianday() SQL function
  • keyword index
  • last_insert_rowid() SQL function
  • legacy_file_format pragma
  • length() SQL function
  • library size
  • LIKE
  • LIKE optimization
  • like() SQL function
  • limit category
  • limits
  • literal value
  • literal-value syntax diagram
  • load_extension() SQL function
  • locking_mode pragma
  • lookaside memory allocator
  • lower() SQL function
  • ltrim() SQL function
  • mailing lists
  • MATCH
  • matchinfo
  • matchinfo_fts3
  • max() aggregate function
  • max() SQL function
  • max_page_count pragma
  • MC/DC testing
  • memory
  • memory allocation
  • memory statistics
  • min() aggregate function
  • min() SQL function
  • NOCASE collating function
  • NOT EXISTS operator
  • NOT IN operator
  • NOT INDEXED
  • nullif() SQL function
  • numeric-literal syntax diagram
  • object resolution
  • offsets
  • omitfeatures
  • ON CONFLICT
  • ON CONFLICT clause
  • optimizer
  • or optimization
  • or-connected-terms
  • order by
  • ordering-term syntax diagram
  • OS backend
  • overflow page
  • page cache
  • page_count pragma
  • page_size pragma
  • pagecache memory allocator
  • parameter
  • parameter binding
  • parent key
  • parent table
  • parser_trace pragma
  • PENDING lock
  • permuted index
  • porting SQLite
  • PRAGMA
  • PRAGMA auto_vacuum
  • PRAGMA automatic_index
  • PRAGMA cache_size
  • PRAGMA case_sensitive_like
  • PRAGMA checkpoint_fullfsync
  • PRAGMA collation_list
  • PRAGMA compile_options
  • PRAGMA count_changes
  • PRAGMA database_list
  • PRAGMA default_cache_size
  • PRAGMA empty_result_callbacks
  • PRAGMA encoding
  • PRAGMA foreign_key_list
  • PRAGMA foreign_keys
  • PRAGMA freelist_count
  • PRAGMA full_column_names
  • PRAGMA fullfsync
  • PRAGMA ignore_check_constraints
  • PRAGMA incremental_vacuum
  • PRAGMA index_info
  • PRAGMA index_list
  • PRAGMA integrity_check
  • PRAGMA journal_mode
  • PRAGMA journal_size_limit
  • PRAGMA legacy_file_format
  • pragma list
  • PRAGMA locking_mode
  • PRAGMA max_page_count
  • PRAGMA page_count
  • PRAGMA page_size
  • PRAGMA parser_trace
  • PRAGMA quick_check
  • PRAGMA read_uncommitted
  • PRAGMA recursive_triggers
  • PRAGMA reverse_unordered_selects
  • PRAGMA schema_version
  • PRAGMA secure_delete
  • PRAGMA short_column_names
  • PRAGMA synchronous
  • PRAGMA table_info
  • PRAGMA temp_store
  • PRAGMA temp_store_directory
  • PRAGMA user_version
  • PRAGMA vdbe_listing
  • PRAGMA vdbe_trace
  • PRAGMA wal_autocheckpoint
  • PRAGMA wal_checkpoint
  • PRAGMA writable_schema
  • pragma-stmt syntax diagram
  • pragma-value syntax diagram
  • prefix queries
  • prefix query
  • prepared statement
  • private branches
  • professional support
  • protected sqlite3_value
  • qualified-table-name syntax diagram
  • query
  • query parameters with special meaning to SQLite
  • query planner
  • Quick Start Guide
  • quick_check pragma
  • quote() SQL function
  • R-Tree extension
  • R-Trees
  • raise-function syntax diagram
  • random() SQL function
  • randomblob() SQL function
  • range query optimization
  • read-only WAL databases
  • read_uncommitted pragma
  • record format
  • recursive_triggers pragma
  • REGEXP
  • REINDEX
  • reindex-stmt syntax diagram
  • RELEASE
  • release-stmt syntax diagram
  • relfootprint
  • REPLACE
  • replace() SQL function
  • RESERVED lock
  • result code
  • result-column syntax diagram
  • result-set expressions
  • reverse_unordered_selects pragma
  • Robson proof
  • ROLLBACK
  • rollback journal
  • rollback journal format
  • rollback-stmt syntax diagram
  • round() SQL function
  • ROWID
  • rowid
  • RTRIM collating function
  • rtrim() SQL function
  • rules for determining column affinity
  • SAVEPOINT
  • savepoint-stmt syntax diagram
  • schema_version pragma
  • scratch memory allocator
  • search application tips
  • second edition file format document
  • secure_delete pragma
  • segment btree
  • SELECT
  • select-core syntax diagram
  • select-stmt syntax diagram
  • serial type
  • Session Module C-API function list
  • Session Module C-language Interface
  • shared cache
  • shared cache mode
  • SHARED lock
  • short filenames
  • short_column_names pragma
  • signed-number syntax diagram
  • simple fts queries
  • single-source syntax diagram
  • SLT
  • snippet
  • sorting
  • soundex() SQL function
  • SQL Logic Tests
  • SQL parameter
  • SQL statement compiler
  • sql-stmt syntax diagram
  • sql-stmt-list syntax diagram
  • SQLite Consortium
  • SQLite Keywords
  • SQLite Shared-Cache Mode
  • sqlite3
  • sqlite3_aggregate_context
  • sqlite3_aggregate_count
  • sqlite3_auto_extension
  • sqlite3_backup
  • sqlite3_backup__remaining()
  • sqlite3_backup_finish()
  • sqlite3_backup_init()
  • sqlite3_backup_pagecount()
  • sqlite3_backup_remaining
  • sqlite3_backup_step()
  • sqlite3_bind_blob
  • sqlite3_bind_double
  • sqlite3_bind_int
  • sqlite3_bind_int64
  • sqlite3_bind_null
  • sqlite3_bind_parameter_count
  • sqlite3_bind_parameter_index
  • sqlite3_bind_parameter_name
  • sqlite3_bind_text
  • sqlite3_bind_text16
  • sqlite3_bind_value
  • sqlite3_bind_zeroblob
  • sqlite3_blob
  • sqlite3_blob_bytes
  • sqlite3_blob_close
  • sqlite3_blob_open
  • sqlite3_blob_read
  • sqlite3_blob_reopen
  • sqlite3_blob_write
  • sqlite3_busy_handler
  • sqlite3_busy_timeout
  • sqlite3_changes
  • sqlite3_clear_bindings
  • sqlite3_close
  • sqlite3_collation_needed
  • sqlite3_collation_needed16
  • sqlite3_column_blob
  • sqlite3_column_bytes
  • sqlite3_column_bytes16
  • sqlite3_column_count
  • sqlite3_column_database_name
  • sqlite3_column_database_name16
  • sqlite3_column_decltype
  • sqlite3_column_decltype16
  • sqlite3_column_double
  • sqlite3_column_int
  • sqlite3_column_int64
  • sqlite3_column_name
  • sqlite3_column_name16
  • sqlite3_column_origin_name
  • sqlite3_column_origin_name16
  • sqlite3_column_table_name
  • sqlite3_column_table_name16
  • sqlite3_column_text
  • sqlite3_column_text16
  • sqlite3_column_type
  • sqlite3_column_value
  • sqlite3_commit_hook
  • sqlite3_compileoption_get
  • sqlite3_compileoption_used
  • sqlite3_complete
  • sqlite3_complete16
  • sqlite3_config
  • sqlite3_context
  • sqlite3_context_db_handle
  • sqlite3_create_collation
  • sqlite3_create_collation16
  • sqlite3_create_collation_v2
  • sqlite3_create_function
  • sqlite3_create_function16
  • sqlite3_create_function_v2
  • sqlite3_create_module
  • sqlite3_create_module_v2
  • sqlite3_data_count
  • sqlite3_db_config
  • sqlite3_db_handle
  • sqlite3_db_mutex
  • sqlite3_db_status
  • sqlite3_declare_vtab
  • sqlite3_enable_load_extension
  • sqlite3_enable_shared_cache
  • sqlite3_errcode
  • sqlite3_errmsg
  • sqlite3_errmsg16
  • sqlite3_exec
  • sqlite3_expired
  • sqlite3_extended_errcode
  • sqlite3_extended_result_codes
  • sqlite3_file
  • sqlite3_file_control
  • sqlite3_finalize
  • sqlite3_free
  • sqlite3_free_table
  • sqlite3_get_autocommit
  • sqlite3_get_auxdata
  • sqlite3_get_table
  • sqlite3_global_recover
  • sqlite3_index_info
  • sqlite3_initialize
  • sqlite3_int64
  • sqlite3_interrupt
  • sqlite3_io_methods
  • sqlite3_last_insert_rowid
  • sqlite3_libversion
  • sqlite3_libversion_number
  • sqlite3_limit
  • sqlite3_load_extension
  • sqlite3_log
  • sqlite3_malloc
  • sqlite3_mem_methods
  • sqlite3_memory_alarm
  • sqlite3_memory_highwater
  • sqlite3_memory_used
  • sqlite3_module
  • sqlite3_module.xBegin
  • sqlite3_module.xBestIndex
  • sqlite3_module.xClose
  • sqlite3_module.xColumn
  • sqlite3_module.xCommit
  • sqlite3_module.xConnect
  • sqlite3_module.xCreate
  • sqlite3_module.xDisconnect
  • sqlite3_module.xEof
  • sqlite3_module.xFilter
  • sqlite3_module.xFindFunction
  • sqlite3_module.xNext
  • sqlite3_module.xOpen
  • sqlite3_module.xRename
  • sqlite3_module.xRollback
  • sqlite3_module.xRowid
  • sqlite3_module.xSavepoint
  • sqlite3_module.xSync
  • sqlite3_module.xUpdate
  • sqlite3_mprintf
  • sqlite3_mutex
  • sqlite3_mutex_alloc
  • sqlite3_mutex_enter
  • sqlite3_mutex_free
  • sqlite3_mutex_held
  • sqlite3_mutex_leave
  • sqlite3_mutex_methods
  • sqlite3_mutex_notheld
  • sqlite3_mutex_try
  • sqlite3_next_stmt
  • sqlite3_open
  • sqlite3_open16
  • sqlite3_open_v2
  • sqlite3_os_end
  • sqlite3_os_init
  • sqlite3_overload_function
  • sqlite3_pcache
  • sqlite3_pcache_methods
  • sqlite3_prepare
  • sqlite3_prepare16
  • sqlite3_prepare16_v2
  • sqlite3_prepare_v2
  • sqlite3_profile
  • sqlite3_progress_handler
  • sqlite3_randomness
  • sqlite3_realloc
  • sqlite3_release_memory
  • sqlite3_reset
  • sqlite3_reset_auto_extension
  • sqlite3_result_blob
  • sqlite3_result_double
  • sqlite3_result_error
  • sqlite3_result_error16
  • sqlite3_result_error_code
  • sqlite3_result_error_nomem
  • sqlite3_result_error_toobig
  • sqlite3_result_int
  • sqlite3_result_int64
  • sqlite3_result_null
  • sqlite3_result_text
  • sqlite3_result_text16
  • sqlite3_result_text16be
  • sqlite3_result_text16le
  • sqlite3_result_value
  • sqlite3_result_zeroblob
  • sqlite3_rollback_hook
  • sqlite3_set_authorizer
  • sqlite3_set_auxdata
  • sqlite3_shutdown
  • sqlite3_sleep
  • sqlite3_snprintf
  • sqlite3_soft_heap_limit
  • sqlite3_soft_heap_limit64
  • sqlite3_sourceid
  • sqlite3_sql
  • sqlite3_status
  • sqlite3_step
  • sqlite3_stmt
  • sqlite3_stmt_readonly
  • sqlite3_stmt_status
  • sqlite3_strnicmp
  • sqlite3_table_column_metadata
  • sqlite3_temp_directory
  • sqlite3_test_control
  • sqlite3_thread_cleanup
  • sqlite3_threadsafe
  • sqlite3_total_changes
  • sqlite3_trace
  • sqlite3_transfer_bindings
  • sqlite3_uint64
  • sqlite3_unlock_notify
  • sqlite3_update_hook
  • sqlite3_uri_parameter
  • sqlite3_user_data
  • sqlite3_value
  • sqlite3_value_blob
  • sqlite3_value_bytes
  • sqlite3_value_bytes16
  • sqlite3_value_double
  • sqlite3_value_int
  • sqlite3_value_int64
  • sqlite3_value_numeric_type
  • sqlite3_value_text
  • sqlite3_value_text16
  • sqlite3_value_text16be
  • sqlite3_value_text16le
  • sqlite3_value_type
  • sqlite3_version,
  • sqlite3_vfs
  • sqlite3_vfs.xAccess
  • sqlite3_vfs.xOpen
  • sqlite3_vfs_find
  • sqlite3_vfs_register
  • sqlite3_vfs_unregister
  • sqlite3_vmprintf
  • sqlite3_vsnprintf
  • sqlite3_vtab
  • sqlite3_vtab_config
  • sqlite3_vtab_cursor
  • sqlite3_vtab_on_conflict
  • sqlite3_wal_autocheckpoint
  • sqlite3_wal_checkpoint
  • sqlite3_wal_checkpoint_v2
  • sqlite3_wal_hook
  • SQLITE_4_BYTE_ALIGNED_MALLOC
  • SQLITE_ABORT
  • SQLITE_ACCESS_EXISTS
  • SQLITE_ACCESS_READ
  • SQLITE_ACCESS_READWRITE
  • SQLITE_ALTER_TABLE
  • SQLITE_ANALYZE
  • SQLITE_ANY
  • SQLITE_ATTACH
  • SQLITE_AUTH
  • SQLITE_BLOB
  • SQLITE_BUSY
  • SQLITE_BUSY_RECOVERY
  • SQLITE_CANTOPEN
  • SQLITE_CANTOPEN_NOTEMPDIR
  • SQLITE_CASE_SENSITIVE_LIKE
  • SQLITE_CHECKPOINT_FULL
  • SQLITE_CHECKPOINT_PASSIVE
  • SQLITE_CHECKPOINT_RESTART
  • sqlite_compileoption_get() SQL function
  • sqlite_compileoption_used() SQL function
  • SQLITE_CONFIG_GETMALLOC
  • SQLITE_CONFIG_GETMUTEX
  • SQLITE_CONFIG_GETPCACHE
  • SQLITE_CONFIG_HEAP
  • SQLITE_CONFIG_LOG
  • SQLITE_CONFIG_LOOKASIDE
  • SQLITE_CONFIG_MALLOC
  • SQLITE_CONFIG_MEMSTATUS
  • SQLITE_CONFIG_MULTITHREAD
  • SQLITE_CONFIG_MUTEX
  • SQLITE_CONFIG_PAGECACHE
  • SQLITE_CONFIG_PCACHE
  • SQLITE_CONFIG_SCRATCH
  • SQLITE_CONFIG_SERIALIZED
  • SQLITE_CONFIG_SINGLETHREAD
  • SQLITE_CONFIG_URI
  • SQLITE_CONSTRAINT
  • SQLITE_COPY
  • SQLITE_CORRUPT
  • SQLITE_CORRUPT_VTAB
  • SQLITE_CREATE_INDEX
  • SQLITE_CREATE_TABLE
  • SQLITE_CREATE_TEMP_INDEX
  • SQLITE_CREATE_TEMP_TABLE
  • SQLITE_CREATE_TEMP_TRIGGER
  • SQLITE_CREATE_TEMP_VIEW
  • SQLITE_CREATE_TRIGGER
  • SQLITE_CREATE_VIEW
  • SQLITE_CREATE_VTABLE
  • SQLITE_DBCONFIG_ENABLE_FKEY
  • SQLITE_DBCONFIG_ENABLE_TRIGGER
  • SQLITE_DBCONFIG_LOOKASIDE
  • SQLITE_DBSTATUS options
  • SQLITE_DBSTATUS_CACHE_HIT
  • SQLITE_DBSTATUS_CACHE_MISS
  • SQLITE_DBSTATUS_CACHE_USED
  • SQLITE_DBSTATUS_LOOKASIDE_HIT
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
  • SQLITE_DBSTATUS_LOOKASIDE_USED
  • SQLITE_DBSTATUS_MAX
  • SQLITE_DBSTATUS_SCHEMA_USED
  • SQLITE_DBSTATUS_STMT_USED
  • SQLITE_DEBUG
  • SQLITE_DEFAULT_AUTOVACUUM
  • SQLITE_DEFAULT_CACHE_SIZE
  • SQLITE_DEFAULT_FILE_FORMAT
  • SQLITE_DEFAULT_FILE_PERMISSIONS
  • SQLITE_DEFAULT_FOREIGN_KEYS
  • SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
  • SQLITE_DEFAULT_LOCKING_MODE
  • SQLITE_DEFAULT_MEMSTATUS
  • SQLITE_DEFAULT_PAGE_SIZE
  • SQLITE_DEFAULT_TEMP_CACHE_SIZE
  • SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
  • SQLITE_DELETE
  • SQLITE_DENY
  • SQLITE_DETACH
  • SQLITE_DIRECT_OVERFLOW_READ
  • SQLITE_DISABLE_DIRSYNC
  • SQLITE_DISABLE_LFS
  • SQLITE_DONE
  • SQLITE_DROP_INDEX
  • SQLITE_DROP_TABLE
  • SQLITE_DROP_TEMP_INDEX
  • SQLITE_DROP_TEMP_TABLE
  • SQLITE_DROP_TEMP_TRIGGER
  • SQLITE_DROP_TEMP_VIEW
  • SQLITE_DROP_TRIGGER
  • SQLITE_DROP_VIEW
  • SQLITE_DROP_VTABLE
  • SQLITE_EMPTY
  • SQLITE_ENABLE_8_3_NAMES
  • SQLITE_ENABLE_ATOMIC_WRITE
  • SQLITE_ENABLE_COLUMN_METADATA
  • SQLITE_ENABLE_FTS3
  • SQLITE_ENABLE_FTS3_PARENTHESIS
  • SQLITE_ENABLE_FTS4
  • SQLITE_ENABLE_ICU
  • SQLITE_ENABLE_IOTRACE
  • SQLITE_ENABLE_LOCKING_STYLE
  • SQLITE_ENABLE_MEMORY_MANAGEMENT
  • SQLITE_ENABLE_MEMSYS3
  • SQLITE_ENABLE_MEMSYS5
  • SQLITE_ENABLE_RTREE
  • SQLITE_ENABLE_STAT2
  • SQLITE_ENABLE_STAT3
  • SQLITE_ENABLE_UNLOCK_NOTIFY
  • SQLITE_ENABLE_UPDATE_DELETE_LIMIT
  • SQLITE_ERROR
  • SQLITE_FAIL
  • SQLITE_FCNTL_CHUNK_SIZE
  • SQLITE_FCNTL_FILE_POINTER
  • SQLITE_FCNTL_LOCKSTATE
  • SQLITE_FCNTL_OVERWRITE
  • SQLITE_FCNTL_PERSIST_WAL
  • SQLITE_FCNTL_SIZE_HINT
  • SQLITE_FCNTL_SYNC_OMITTED
  • SQLITE_FCNTL_WIN32_AV_RETRY
  • SQLITE_FLOAT
  • SQLITE_FORMAT
  • SQLITE_FULL
  • SQLITE_FUNCTION
  • SQLITE_GET_LOCKPROXYFILE
  • SQLITE_HAVE_ISNAN
  • SQLITE_IGNORE
  • SQLITE_INDEX_CONSTRAINT_EQ
  • SQLITE_INDEX_CONSTRAINT_GE
  • SQLITE_INDEX_CONSTRAINT_GT
  • SQLITE_INDEX_CONSTRAINT_LE
  • SQLITE_INDEX_CONSTRAINT_LT
  • SQLITE_INDEX_CONSTRAINT_MATCH
  • SQLITE_INSERT
  • sqlite_int64
  • SQLITE_INTEGER
  • SQLITE_INTERNAL
  • SQLITE_INTERRUPT
  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL
  • SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  • SQLITE_IOERR
  • SQLITE_IOERR_ACCESS
  • SQLITE_IOERR_BLOCKED
  • SQLITE_IOERR_CHECKRESERVEDLOCK
  • SQLITE_IOERR_CLOSE
  • SQLITE_IOERR_DELETE
  • SQLITE_IOERR_DIR_CLOSE
  • SQLITE_IOERR_DIR_FSYNC
  • SQLITE_IOERR_FSTAT
  • SQLITE_IOERR_FSYNC
  • SQLITE_IOERR_LOCK
  • SQLITE_IOERR_NOMEM
  • SQLITE_IOERR_RDLOCK
  • SQLITE_IOERR_READ
  • SQLITE_IOERR_SEEK
  • SQLITE_IOERR_SHMLOCK
  • SQLITE_IOERR_SHMMAP
  • SQLITE_IOERR_SHMOPEN
  • SQLITE_IOERR_SHMSIZE
  • SQLITE_IOERR_SHORT_READ
  • SQLITE_IOERR_TRUNCATE
  • SQLITE_IOERR_UNLOCK
  • SQLITE_IOERR_WRITE
  • SQLITE_LAST_ERRNO
  • SQLITE_LIMIT_ATTACHED
  • SQLITE_LIMIT_COLUMN
  • SQLITE_LIMIT_COMPOUND_SELECT
  • SQLITE_LIMIT_EXPR_DEPTH
  • SQLITE_LIMIT_FUNCTION_ARG
  • SQLITE_LIMIT_LENGTH
  • SQLITE_LIMIT_LIKE_PATTERN_LENGTH
  • SQLITE_LIMIT_SQL_LENGTH
  • SQLITE_LIMIT_TRIGGER_DEPTH
  • SQLITE_LIMIT_VARIABLE_NUMBER
  • SQLITE_LIMIT_VDBE_OP
  • SQLITE_LOCK_EXCLUSIVE
  • SQLITE_LOCK_NONE
  • SQLITE_LOCK_PENDING
  • SQLITE_LOCK_RESERVED
  • SQLITE_LOCK_SHARED
  • SQLITE_LOCKED
  • SQLITE_LOCKED_SHAREDCACHE
  • SQLITE_MAX_ATTACHED
  • SQLITE_MAX_COLUMN
  • SQLITE_MAX_COMPOUND_SELECT
  • SQLITE_MAX_EXPR_DEPTH
  • SQLITE_MAX_FUNCTION_ARG
  • SQLITE_MAX_LENGTH
  • SQLITE_MAX_LIKE_PATTERN_LENGTH
  • SQLITE_MAX_PAGE_COUNT
  • SQLITE_MAX_SCHEMA_RETRY
  • SQLITE_MAX_SQL_LENGTH
  • SQLITE_MAX_TRIGGER_DEPTH
  • SQLITE_MAX_VARIABLE_NUMBER
  • SQLITE_MEMDEBUG
  • SQLITE_MISMATCH
  • SQLITE_MISUSE
  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_LRU
  • SQLITE_MUTEX_STATIC_LRU2
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_OPEN
  • SQLITE_MUTEX_STATIC_PMEM
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_NOLFS
  • SQLITE_NOMEM
  • SQLITE_NOTADB
  • SQLITE_NOTFOUND
  • SQLITE_NULL
  • SQLITE_OK
  • SQLITE_OMIT_ALTERTABLE
  • SQLITE_OMIT_ANALYZE
  • SQLITE_OMIT_ATTACH
  • SQLITE_OMIT_AUTHORIZATION
  • SQLITE_OMIT_AUTOINCREMENT
  • SQLITE_OMIT_AUTOINIT
  • SQLITE_OMIT_AUTOMATIC_INDEX
  • SQLITE_OMIT_AUTORESET
  • SQLITE_OMIT_AUTOVACUUM
  • SQLITE_OMIT_BETWEEN_OPTIMIZATION
  • SQLITE_OMIT_BLOB_LITERAL
  • SQLITE_OMIT_BTREECOUNT
  • SQLITE_OMIT_BUILTIN_TEST
  • SQLITE_OMIT_CAST
  • SQLITE_OMIT_CHECK
  • SQLITE_OMIT_COMPILEOPTION_DIAGS
  • SQLITE_OMIT_COMPLETE
  • SQLITE_OMIT_COMPOUND_SELECT
  • SQLITE_OMIT_DATETIME_FUNCS
  • SQLITE_OMIT_DECLTYPE
  • SQLITE_OMIT_DEPRECATED
  • SQLITE_OMIT_DISKIO
  • SQLITE_OMIT_EXPLAIN
  • SQLITE_OMIT_FLAG_PRAGMAS
  • SQLITE_OMIT_FLOATING_POINT
  • SQLITE_OMIT_FOREIGN_KEY
  • SQLITE_OMIT_GET_TABLE
  • SQLITE_OMIT_INCRBLOB
  • SQLITE_OMIT_INTEGRITY_CHECK
  • SQLITE_OMIT_LIKE_OPTIMIZATION
  • SQLITE_OMIT_LOAD_EXTENSION
  • SQLITE_OMIT_LOCALTIME
  • SQLITE_OMIT_LOOKASIDE
  • SQLITE_OMIT_MEMORYDB
  • SQLITE_OMIT_MERGE_SORT
  • SQLITE_OMIT_OR_OPTIMIZATION
  • SQLITE_OMIT_PAGER_PRAGMAS
  • SQLITE_OMIT_PRAGMA
  • SQLITE_OMIT_PROGRESS_CALLBACK
  • SQLITE_OMIT_QUICKBALANCE
  • SQLITE_OMIT_REINDEX
  • SQLITE_OMIT_SCHEMA_PRAGMAS
  • SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
  • SQLITE_OMIT_SHARED_CACHE
  • SQLITE_OMIT_SUBQUERY
  • SQLITE_OMIT_TCL_VARIABLE
  • SQLITE_OMIT_TEMPDB
  • SQLITE_OMIT_TRACE
  • SQLITE_OMIT_TRIGGER
  • SQLITE_OMIT_TRUNCATE_OPTIMIZATION
  • SQLITE_OMIT_UTF16
  • SQLITE_OMIT_VACUUM
  • SQLITE_OMIT_VIEW
  • SQLITE_OMIT_VIRTUALTABLE
  • SQLITE_OMIT_WAL
  • SQLITE_OMIT_WSD
  • SQLITE_OMIT_XFER_OPT
  • SQLITE_OPEN_AUTOPROXY
  • SQLITE_OPEN_CREATE
  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE
  • SQLITE_OPEN_FULLMUTEX
  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
  • SQLITE_OPEN_NOMUTEX
  • SQLITE_OPEN_PRIVATECACHE
  • SQLITE_OPEN_READONLY
  • SQLITE_OPEN_READWRITE
  • SQLITE_OPEN_SHAREDCACHE
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_URI
  • SQLITE_OPEN_WAL
  • SQLITE_OS_OTHER
  • SQLITE_PERM
  • SQLITE_PRAGMA
  • SQLITE_PROTOCOL
  • SQLITE_RANGE
  • SQLITE_READ
  • SQLITE_READONLY
  • SQLITE_READONLY_CANTLOCK
  • SQLITE_READONLY_RECOVERY
  • SQLITE_REINDEX
  • SQLITE_REPLACE
  • SQLITE_ROLLBACK
  • SQLITE_ROW
  • SQLITE_SAVEPOINT
  • SQLITE_SCHEMA
  • SQLITE_SECURE_DELETE
  • SQLITE_SELECT
  • SQLITE_SET_LOCKPROXYFILE
  • SQLITE_SHM_EXCLUSIVE
  • SQLITE_SHM_LOCK
  • SQLITE_SHM_NLOCK
  • SQLITE_SHM_SHARED
  • SQLITE_SHM_UNLOCK
  • SQLITE_SOUNDEX
  • SQLITE_SOURCE_ID
  • sqlite_source_id() SQL function
  • SQLITE_STATIC
  • SQLITE_STATUS_MALLOC_COUNT
  • SQLITE_STATUS_MALLOC_SIZE
  • SQLITE_STATUS_MEMORY_USED
  • SQLITE_STATUS_PAGECACHE_OVERFLOW
  • SQLITE_STATUS_PAGECACHE_SIZE
  • SQLITE_STATUS_PAGECACHE_USED
  • SQLITE_STATUS_PARSER_STACK
  • SQLITE_STATUS_SCRATCH_OVERFLOW
  • SQLITE_STATUS_SCRATCH_SIZE
  • SQLITE_STATUS_SCRATCH_USED
  • SQLITE_STMTSTATUS counter
  • SQLITE_STMTSTATUS_AUTOINDEX
  • SQLITE_STMTSTATUS_FULLSCAN_STEP
  • SQLITE_STMTSTATUS_SORT
  • SQLITE_SYNC_DATAONLY
  • SQLITE_SYNC_FULL
  • SQLITE_SYNC_NORMAL
  • SQLITE_TEMP_STORE
  • SQLITE_TESTCTRL_ALWAYS
  • SQLITE_TESTCTRL_ASSERT
  • SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS
  • SQLITE_TESTCTRL_BITVEC_TEST
  • SQLITE_TESTCTRL_FAULT_INSTALL
  • SQLITE_TESTCTRL_FIRST
  • SQLITE_TESTCTRL_ISKEYWORD
  • SQLITE_TESTCTRL_LAST
  • SQLITE_TESTCTRL_LOCALTIME_FAULT
  • SQLITE_TESTCTRL_OPTIMIZATIONS
  • SQLITE_TESTCTRL_PENDING_BYTE
  • SQLITE_TESTCTRL_PGHDRSZ
  • SQLITE_TESTCTRL_PRNG_RESET
  • SQLITE_TESTCTRL_PRNG_RESTORE
  • SQLITE_TESTCTRL_PRNG_SAVE
  • SQLITE_TESTCTRL_RESERVE
  • SQLITE_TESTCTRL_SCRATCHMALLOC
  • SQLITE_TEXT
  • SQLITE_THREADSAFE
  • SQLITE_TOOBIG
  • SQLITE_TRANSACTION
  • SQLITE_TRANSIENT
  • sqlite_uint64
  • SQLITE_UPDATE
  • SQLITE_USE_URI
  • SQLITE_UTF16
  • SQLITE_UTF16_ALIGNED
  • SQLITE_UTF16BE
  • SQLITE_UTF16LE
  • SQLITE_UTF8
  • SQLITE_VERSION
  • sqlite_version() SQL function
  • SQLITE_VERSION_NUMBER
  • SQLITE_VTAB_CONSTRAINT_SUPPORT
  • SQLITE_ZERO_MALLOC
  • status parameters
  • storage class
  • strategies
  • strftime() SQL function
  • substr() SQL function
  • sum() aggregate function
  • synchronous pragma
  • syntax diagrams
  • table-constraint syntax diagram
  • table_info pragma
  • Tcl extension
  • TCL Interface
  • TCL test suite
  • TCL variable substitution
  • TEA tarball
  • temp_store pragma
  • temp_store_directory pragma
  • temporary databases
  • temporary disk files
  • temporary tables
  • test coverage
  • test harness
  • test suite
  • testcase macros
  • testing
  • TH3
  • the amalgamation
  • the ext3 barrier problem
  • the xCachesize() page cache method
  • the xCreate() page cache methods
  • the xDestroy() page cache method
  • the xFetch() page cache methods
  • the xInit() page cache method
  • the xPagecount() page cache methods
  • the xRekey() page cache methods
  • the xShutdown() page cache method
  • the xUnpin() page cache method
  • Things That Can Go Wrong
  • threading mode
  • three test harnesses
  • time() SQL function
  • tokenizer
  • total() aggregate function
  • total_changes() SQL function
  • trim() SQL function
  • truncate optimization
  • type affinity
  • type-name syntax diagram
  • typeof() SQL function
  • undefined BEFORE trigger behavior
  • Uniform Resource Identifier
  • unprotected sqlite3_value
  • UPDATE
  • update-stmt syntax diagram
  • update-stmt-limited syntax diagram
  • upper() SQL function
  • URI
  • URI filename
  • URI filename examples
  • URI filenames in sqlite3_open()
  • usable size
  • user_version pragma
  • Using the SQLite Online Backup API
  • Using the SQLite Unlock Notification Feature
  • VACUUM
  • vacuum-stmt syntax diagram
  • variable-length integer
  • varint
  • vdbe_listing pragma
  • vdbe_trace pragma
  • Version 3.0.0
  • Version 3.0.1
  • Version 3.0.2
  • Version 3.0.3
  • Version 3.0.4
  • Version 3.0.5
  • Version 3.0.6
  • Version 3.0.7
  • Version 3.0.8
  • Version 3.1.0
  • Version 3.1.1
  • Version 3.1.2
  • Version 3.1.3
  • Version 3.1.4
  • Version 3.1.5
  • Version 3.1.6
  • Version 3.2.0
  • Version 3.2.1
  • Version 3.2.2
  • Version 3.2.3
  • Version 3.2.4
  • Version 3.2.5
  • Version 3.2.6
  • Version 3.2.7
  • Version 3.2.8
  • Version 3.3.0
  • Version 3.3.1
  • Version 3.3.10
  • Version 3.3.11
  • Version 3.3.12
  • Version 3.3.13
  • Version 3.3.14
  • Version 3.3.15
  • Version 3.3.16
  • Version 3.3.17
  • Version 3.3.2
  • Version 3.3.3
  • Version 3.3.4
  • Version 3.3.5
  • Version 3.3.6
  • Version 3.3.7
  • Version 3.3.8
  • Version 3.3.9
  • Version 3.4.0
  • Version 3.4.1
  • Version 3.4.2
  • Version 3.5.0
  • Version 3.5.1
  • Version 3.5.2
  • Version 3.5.3
  • Version 3.5.4
  • Version 3.5.5
  • Version 3.5.6
  • Version 3.5.7
  • Version 3.5.8
  • Version 3.5.9
  • Version 3.6.0
  • Version 3.6.1
  • Version 3.6.10
  • Version 3.6.11
  • Version 3.6.12
  • Version 3.6.13
  • Version 3.6.14
  • Version 3.6.14.1
  • Version 3.6.14.2
  • Version 3.6.15
  • Version 3.6.16
  • Version 3.6.16.1
  • Version 3.6.17
  • Version 3.6.18
  • Version 3.6.19
  • Version 3.6.2
  • Version 3.6.20
  • Version 3.6.21
  • Version 3.6.22
  • Version 3.6.23
  • Version 3.6.23.1
  • Version 3.6.3
  • Version 3.6.4
  • Version 3.6.5
  • Version 3.6.6
  • Version 3.6.6.1
  • Version 3.6.6.2
  • Version 3.6.7
  • Version 3.6.8
  • Version 3.6.9
  • Version 3.7.0
  • Version 3.7.0.1
  • Version 3.7.1
  • Version 3.7.2
  • Version 3.7.3
  • Version 3.7.4
  • Version 3.7.5
  • Version 3.7.6
  • Version 3.7.6.1
  • Version 3.7.6.2
  • Version 3.7.6.3
  • Version 3.7.7
  • Version 3.7.7.1
  • Version 3.7.8
  • Version 3.7.9
  • version-valid-for number
  • VFS
  • VFSes
  • view
  • virtual machine instructions
  • virtual table
  • virtual table cursor
  • virtual table module
  • WAL
  • WAL backwards compatibility
  • WAL checksum algorithm
  • WAL concurrency
  • WAL format
  • WAL mode
  • WAL read algorithm
  • WAL without shared memory
  • wal-index
  • WAL-index format
  • wal_autocheckpoint pragma
  • wal_checkpoint pragma
  • WHERE clause
  • writable_schema pragma
  • write-ahead log
  • writer starvation
  • xBegin
  • xBestIndex
  • xColumn
  • xCommit
  • xConnect
  • xCreate
  • xDestroy
  • xDisconnect
  • xEof
  • xFilter
  • xFindFunction
  • xNext
  • xRelease
  • xRename
  • xRollback
  • xRollbackTo
  • xRowid
  • xSavepoint
  • xUpdate
  • YYSTACKDEPTH
  • YYTRACKMAXSTACKDEPTH
  • zero-malloc memory allocator
  • zeroblob() SQL function


Query Language Understood by SQLite

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

SQLite understands most of the standard SQL language. But it does omit some features while at the same time adding a few features of its own. This document attempts to describe precisely what parts of the SQL language SQLite does and does not support. A list of SQL keywords is also provided. The SQL language syntax is described by syntax diagrams.

The following syntax documentation topics are available:

  • aggregate functions
  • ALTER TABLE
  • ANALYZE
  • ATTACH DATABASE
  • BEGIN TRANSACTION
  • comment
  • COMMIT TRANSACTION
  • core functions
  • CREATE INDEX
  • CREATE TABLE
  • CREATE TRIGGER
  • CREATE VIEW
  • CREATE VIRTUAL TABLE
  • date and time functions
  • DELETE
  • DETACH DATABASE
  • DROP INDEX
  • DROP TABLE
  • DROP TRIGGER
  • DROP VIEW
  • END TRANSACTION
  • EXPLAIN
  • expression
  • INDEXED BY
  • INSERT
  • keywords
  • ON CONFLICT clause
  • PRAGMA
  • REINDEX
  • RELEASE SAVEPOINT
  • REPLACE
  • ROLLBACK TRANSACTION
  • SAVEPOINT
  • SELECT
  • UPDATE
  • VACUUM

The routines sqlite3_prepare_v2(), sqlite3_prepare(),
sqlite3_prepare16(), sqlite3_prepare16_v2(),
sqlite3_exec(), and sqlite3_get_table() accept
an SQL statement list (sql-stmt-list) which is a semicolon-separated
list of statements.

sql-stmt-list:

syntax diagram sql-stmt-list

Each SQL statement in the statement list is an instance of the following:

sql-stmt:

syntax diagram sql-stmt


SQLite Query Language: Aggregate Functions

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

Aggregate Functions

The aggregate functions shown below are available by default. Additional aggregate functions written in C may be added using the sqlite3_create_function() API.

In any aggregate function that takes a single argument, that argument can be preceded by the keyword DISTINCT. In such cases, duplicate elements are filtered before being passed into the aggregate function. For example, the function "count(distinct X)" will return the number of distinct values of column X instead of the total number of non-null values in column X.

avg(X) | The avg() function returns the average value of all non-NULL X within a group. String and BLOB values that do not look like numbers are interpreted as 0. The result of avg() is always a floating point value as long as at there is at least one non-NULL input even if all inputs are integers. The result of avg() is NULL if and only if there are no non-NULL inputs.
count(X)

count(*) 		The count(X) function returns a count of the number of times that X is not NULL in a group. The count(*) function (with no arguments) returns the total number of rows in the group.
group_concat(X)

group_concat(X,Y) 		The group_concat() function returns a string which is the concatenation of all non-NULL values of X. If parameter Y is present then it is used as the separator between instances of X. A comma (",") is used as the separator if Y is omitted. The order of the concatenated elements is arbitrary.
max(X) | The max() aggregate function returns the maximum value of all values in the group. The maximum value is the value that would be returned last in an ORDER BY on the same column. Aggregate max() returns NULL if and only if there are no non-NULL values in the group.
min(X) | The min() aggregate function returns the minimum non-NULL value of all values in the group. The minimum value is the first non-NULL value that would appear in an ORDER BY of the column. Aggregate min() returns NULL if and only if there are no non-NULL values in the group.
sum(X)

total(X) 		The sum() and total() aggregate functions return sum of all non-NULL values in the group. If there are no non-NULL input rows then sum() returns NULL but total() returns 0.0. NULL is not normally a helpful result for the sum of no rows but the SQL standard requires it and most other SQL database engines implement sum() that way so SQLite does it in the same way in order to be compatible. The non-standard total() function is provided as a convenient way to work around this design problem in the SQL language.

The result of total() is always a floating point value. The result of sum() is an integer value if all non-NULL inputs are integers. If any input to sum() is neither an integer or a NULL then sum() returns a floating point value which might be an approximation to the true sum.

Sum() will throw an "integer overflow" exception if all inputs are integers or NULL and an integer overflow occurs at any point during the computation. Total() never throws an integer overflow.


SQLite Query Language: ALTER TABLE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

ALTER TABLE

alter-table-stmt:

syntax diagram alter-table-stmt

SQLite supports a limited subset of ALTER TABLE. The ALTER TABLE command in SQLite allows the user to rename a table or to add a new column to an existing table. It is not possible to rename a column, remove a column, or add or remove constraints from a table.

The RENAME TO syntax is used to rename the table identified by [database-name.]table-name to new-table-name. This command cannot be used to move a table between attached databases, only to rename a table within the same database.

If the table being renamed has triggers or indices, then these remain attached to the table after it has been renamed. However, if there are any view definitions, or statements executed by triggers that refer to the table being renamed, these are not automatically modified to use the new table name. If this is required, the triggers or view definitions must be dropped and recreated to use the new table name by hand.

If foreign key constraints are enabled when a table is renamed, then any REFERENCES clauses in any table (either the table being renamed or some other table) that refer to the table being renamed are modified to refer to the renamed table by its new name.

The ADD COLUMN syntax is used to add a new column to an existing table. The new column is always appended to the end of the list of existing columns. The column-def rule defines the characteristics of the new column. The new column may take any of the forms permissible in a CREATE TABLE statement, with the following restrictions:

  • The column may not have a PRIMARY KEY or UNIQUE constraint.
  • The column may not have a default value of CURRENT_TIME, CURRENT_DATE, CURRENT_TIMESTAMP, or an expression in parentheses.
  • If a NOT NULL constraint is specified, then the column must have a default value other than NULL.
  • If foreign key constraints are enabled and a column with a REFERENCES clause is added, the column must have a default value of NULL.

Note also that when adding a CHECK constraint, the CHECK constraint is not tested against preexisting rows of the table. This can result in a table that contains data that is in violation of the CHECK constraint. Future versions of SQLite might change to validate CHECK constraints as they are added.

The execution time of the ALTER TABLE command is independent of the amount of data in the table. The ALTER TABLE command runs as quickly on a table with 10 million rows as it does on a table with 1 row.

After ADD COLUMN has been run on a database, that database will not be readable by SQLite version 3.1.3 and earlier.


SQLite Query Language: ANALYZE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

ANALYZE

analyze-stmt:

syntax diagram analyze-stmt

The ANALYZE command gathers statistics about tables and indices and stores the collected information in a special tables in the database where the query optimizer can use them to help make better query planning choices. If no arguments are given, all attached databases are analyzed. If a database name is given as the argument, then all tables and indices in that one database are analyzed. If the argument is a table name, then only that table and the indices associated with that table are analyzed. If the argument is an index name, then only that one index is analyzed.

The default implementation stores all statistics in a single table named sqlite_stat1. If SQLite is compiled with the SQLITE_ENABLE_STAT3 option, then additional histogram data is collected and stored in sqlite_stat3. Future enhancements may create additional tables with the same name pattern except with the "1" or "3" changed to larger digits.

The ALTER TABLE command does not work on the sqlite_stat1 or sqlite_stat3 tables, but all the content of those tables can be queried using SELECT and can be deleted, augmented, or modified using the DELETE, INSERT, and UPDATE commands. The DROP TABLE command works on sqlite_stat1 and sqlite_stat3 as of SQLite version 3.7.9. Appropriate care should be used when changing the content of the statistics tables as invalid content can cause SQLite to select inefficient query plans. Generally speaking, one should not modify the content of the statistics tables by any mechanism other than invoking the ANALYZE command.

Statistics gathered by ANALYZE are not automatically updated as the content of the database changes. If the content of the database changes significantly, or if the database schema changes, then one should consider rerunning the ANALYZE command in order to update the statistics.

The query planner might not notice manual changes to the sqlite_stat1 and/or sqlite3_stat2 tables. An application can force the query planner to reread the statistics tables by running ANALYZE sqlite_master.


SQLite Query Language: ATTACH DATABASE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

ATTACH DATABASE

attach-stmt:

syntax diagram attach-stmt

The ATTACH DATABASE statement adds another database file to the current database connection. The filename for the database to be attached is the value of the expression that occurs before the AS keyword. The filename of the database follows the same semantics as the filename argument to sqlite3_open() and sqlite3_open_v2(); the special name ":memory:" results in an in-memory database and an empty string results in a new temporary database. The filename argument can be a URI filename if URI filename processing is enable on the database connection. The name that occurs after the AS keyword is the name of the database used internally by SQLite. The database-names 'main' and 'temp' refer to the main database and the database used for temporary tables. The main and temp databases cannot be attached or detached.

Tables in an attached database can be referred to using the syntax database-name.table-name. If the name of the table is unique across all attached databases and the main and temp databases, then the database-name prefix is not required. If two or more tables in different databases have the same name and the database-name prefix is not used on a table reference, then the table chosen is the one in the database that was least recently attached.

Transactions involving multiple attached databases are atomic, assuming that the main database is not ":memory:" and the journal_mode is not WAL. If the main database is ":memory:" or if the journal_mode is WAL, then transactions continue to be atomic within each individual database file. But if the host computer crashes in the middle of a COMMIT where two or more database files are updated, some of those files might get the changes where others might not.

There is a limit, set using sqlite3_limit() and SQLITE_LIMIT_ATTACHED, to the number of databases that can be simultaneously attached to a single database connection.


SQLite Query Language: comment

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

comment

comment-syntax:

syntax diagram comment-syntax

Comments are not SQL commands, but can occur within the text of SQL queries passed to sqlite3_prepare_v2() and related interfaces. Comments are treated as whitespace by the parser. Comments can begin anywhere whitespace can be found, including inside expressions that span multiple lines.

SQL comments begin with two consecutive "-" characters (ASCII 0x2d) and extend up to and including the next newline character (ASCII 0x0a) or until the end of input, whichever comes first.

C-style comments begin with "/*" and extend up to and including the next "*/" character pair or until the end of input, whichever comes first. C-style comments can span multiple lines.

Comments can appear anywhere whitespace can occur, including inside expressions and in the middle of other SQL statements. Comments do not nest.


SQLite Query Language: ON CONFLICT clause

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

ON CONFLICT clause

conflict-clause:

syntax diagram conflict-clause

The ON CONFLICT clause is not a separate SQL command. It is a non-standard clause that can appear in many other SQL commands. It is given its own section in this document because it is not part of standard SQL and therefore might not be familiar.

The syntax for the ON CONFLICT clause is as shown above for the CREATE TABLE command. For the INSERT and UPDATE commands, the keywords "ON CONFLICT" are replaced by "OR" so that the syntax reads more naturally. For example, instead of "INSERT ON CONFLICT IGNORE" we have "INSERT OR IGNORE". The keywords change but the meaning of the clause is the same either way.

The ON CONFLICT clause applies to UNIQUE and NOT NULL constraints (and to PRIMARY KEY constraints which for the purposes of this section are the same thing as UNIQUE constraints). The ON CONFLICT algorithm does not apply to FOREIGN KEY constraints. There are five conflict resolution algorithm choices: ROLLBACK, ABORT, FAIL, IGNORE, and REPLACE. The default conflict resolution algorithm is ABORT. This is what they mean:

ROLLBACK

When an applicable constraint violation occurs, the ROLLBACK resolution algorithm aborts the current SQL statement with an SQLITE_CONSTRAINT error and rolls back the current transaction. If no transaction is active (other than the implied transaction that is created on every command) then the ROLLBACK resolution algorithm works the same as the ABORT algorithm.

ABORT

When an applicable constraint violation occurs, the ABORT resolution algorithm aborts the current SQL statement with an SQLITE_CONSTRAIT error and backs out any changes made by the current SQL statement; but changes caused by prior SQL statements within the same transaction are preserved and the transaction remains active. This is the default behavior and the behavior proscribed the SQL standard.

FAIL

When an applicable constraint violation occurs, the FAIL resolution algorithm aborts the current SQL statement with an SQLITE_CONSTRAINT error. But the FAIL resolution does not back out prior changes of the SQL statement that failed nor does it end the transaction. For example, if an UPDATE statement encountered a constraint violation on the 100th row that it attempts to update, then the first 99 row changes are preserved but changes to rows 100 and beyond never occur.

IGNORE

When an applicable constraint violation occurs, the IGNORE resolution algorithm skips the one row that contains the constraint violation and continues processing subsequent rows of the SQL statement as if nothing went wrong. Other rows before and after the row that contained the constraint violation are inserted or updated normally. No error is returned when the IGNORE conflict resolution algorithm is used.

REPLACE

When a UNIQUE constraint violation occurs, the REPLACE algorithm deletes pre-existing rows that are causing the constraint violation prior to inserting or updating the current row and the command continues executing normally. If a NOT NULL constraint violation occurs, the REPLACE conflict resolution replaces the NULL value with he default value for that column, or if the column has no default value, then the ABORT algorithm is used. If a CHECK constraint violation occurs, the REPLACE conflict resolution algorithm always works like ABORT.

When the REPLACE conflict resolution strategy deletes rows in order to satisfy a constraint, delete triggers fire if and only if recursive triggers are enabled.

The update hook is not invoked for rows that are deleted by the REPLACE conflict resolution strategy. Nor does REPLACE increment the change counter. The exceptional behaviors defined in this paragraph might change in a future release.

The algorithm specified in the OR clause of an INSERT or UPDATE overrides any algorithm specified in a CREATE TABLE. If no algorithm is specified anywhere, the ABORT algorithm is used.


SQLite Query Language: Core Functions

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

Core Functions

The core functions shown below are available by default. Date & Time functions and aggregate functions are documented separately. An application may define additional functions written in C and added to the database engine using the sqlite3_create_function() API.

abs(X) | The abs(X) function returns the absolute value of the numeric argument X. Abs(X) returns NULL if X is NULL. Abs(X) return 0.0 if X is a string or blob that cannot be converted to a numeric value. If X is the integer -9223372036854775807 then abs(X) throws an integer overflow error since there is no equivalent positive 64-bit two complement value.
changes() | The changes() function returns the number of database rows that were changed or inserted or deleted by the most recently completed INSERT, DELETE, or UPDATE statement, exclusive of statements in lower-level triggers. The changes() SQL function is a wrapper around the sqlite3_changes() C/C++ function and hence follows the same rules for counting changes.
coalesce(X,Y,...) | The coalesce() function returns a copy of its first non-NULL argument, or NULL if all arguments are NULL. Coalesce() must be at least 2 arguments.
glob(X,Y) | The glob(X,Y) function is equivalent to the expression "Y GLOB X". Note that the X and Y arguments are reversed in the glob() function relative to the infix GLOB operator. If the sqlite3_create_function() interface is used to override the glob(X,Y) function with an alternative implementation then the GLOB operator will invoke the alternative implementation.
ifnull(X,Y) | The ifnull() function returns a copy of its first non-NULL argument, or NULL if both arguments are NULL. Ifnull() must have exactly 2 arguments. The ifnull() function is equivalent to coalesce() with two arguments.
hex(X) | The hex() function interprets its argument as a BLOB and returns a string which is the upper-case hexadecimal rendering of the content of that blob.
last_insert_rowid() | The last_insert_rowid() function returns the ROWID of the last row insert from the database connection which invoked the function. The last_insert_rowid() SQL function is a wrapper around the sqlite3_last_insert_rowid() C/C++ interface function.
length(X) | For a string value X, the length(X) function returns the number of characters (not bytes) in X prior to the first NUL character. Since SQLite strings do not normally contain NUL characters, the length(X) function will usually return the total number of characters in the string X. For a blob value X, length(X) returns the number of bytes in the blob. If X is NULL then length(X) is NULL. If X is numeric then length(X) returns the length of a string representation of X.
like(X,Y)

like(X,Y,Z) 		The like() function is used to implement the "Y LIKE X [ESCAPE Z]" expression. If the optional ESCAPE clause is present, then the like() function is invoked with three arguments. Otherwise, it is invoked with two arguments only. Note that the X and Y parameters are reversed in the like() function relative to the infix LIKE operator. The sqlite3_create_function() interface can be used to override the like() function and thereby change the operation of the LIKE operator. When overriding the like() function, it may be important to override both the two and three argument versions of the like() function. Otherwise, different code may be called to implement the LIKE operator depending on whether or not an ESCAPE clause was specified.
load_extension(X)

load_extension(X,Y) 		The load_extension(X,Y) function loads SQLite extensions out of the shared library file named X using the entry point Y. The result of load_extension() is always a NULL. If Y is omitted then the default entry point of sqlite3_extension_init is used. The load_extension() function raises an exception if the extension fails to load or initialize correctly.

The load_extension() function will fail if the extension attempts to modify or delete an SQL function or collating sequence. The extension can add new functions or collating sequences, but cannot modify or delete existing functions or collating sequences because those functions and/or collating sequences might be used elsewhere in the currently running SQL statement. To load an extension that changes or deletes functions or collating sequences, use the sqlite3_load_extension() C-language API.

lower(X) | The lower(X) function returns a copy of string X with all ASCII characters converted to lower case. The default built-in lower() function works for ASCII characters only. To do case conversions on non-ASCII characters, load the ICU extension.
ltrim(X)

ltrim(X,Y) 		The ltrim(X,Y) function returns a string formed by removing any and all characters that appear in Y from the left side of X. If the Y argument is omitted, ltrim(X) removes spaces from the left side of X.
max(X,Y,...) | The multi-argument max() function returns the argument with the maximum value, or return NULL if any argument is NULL. The multi-argument max() function searches its arguments from left to right for an argument that defines a collating function and uses that collating function for all string comparisons. If none of the arguments to max() define a collating function, then the BINARY collating function is used. Note that max() is a simple function when it has 2 or more arguments but operates as an aggregate function if given only a single argument.
min(X,Y,...) | The multi-argument min() function returns the argument with the minimum value. The multi-argument min() function searches its arguments from left to right for an argument that defines a collating function and uses that collating function for all string comparisons. If none of the arguments to min() define a collating function, then the BINARY collating function is used. Note that min() is a simple function when it has 2 or more arguments but operates as an aggregate function if given only a single argument.
nullif(X,Y) | The nullif(X,Y) function returns its first argument if the arguments are different and NULL if the arguments are the same. The nullif(X,Y) function searches its arguments from left to right for an argument that defines a collating function and uses that collating function for all string comparisons. If neither argument to nullif() defines a collating function then the BINARY is used.
quote(X) | The quote(X) function returns the text of an SQL literal which is the value of its argument suitable for inclusion into an SQL statement. Strings are surrounded by single-quotes with escapes on interior quotes as needed. BLOBs are encoded as hexadecimal literals. Strings with embedded NUL characters cannot be represented as string literals in SQL and hence the returned string literal is truncated prior to the first NUL.
random() | The random() function returns a pseudo-random integer between -9223372036854775808 and +9223372036854775807.
randomblob(N) The randomblob(N) function return an N-byte blob containing pseudo-random bytes. If N is less than 1 then a 1-byte random blob is returned.

Hint: applications can generate globally unique identifiers using this function together with hex() and/or lower() like this:

hex(randomblob(16))

lower(hex(randomblob(16)))
replace(X,Y,Z) | The replace(X,Y,Z) function returns a string formed by substituting string Z for every occurrence of string Y in string X. The BINARY collating sequence is used for comparisons. If Y is an empty string then return X unchanged. If Z is not initially a string, it is cast to a UTF-8 string prior to processing.
round(X)

round(X,Y) 		The round(X,Y) function returns a floating-point value X rounded to Y digits to the right of the decimal point. If the Y argument is omitted, it is assumed to be 0.
rtrim(X)

rtrim(X,Y) 		The rtrim(X,Y) function returns a string formed by removing any and all characters that appear in Y from the right side of X. If the Y argument is omitted, rtrim(X) removes spaces from the right side of X.
soundex(X) | The soundex(X) function returns a string that is the soundex encoding of the string X. The string "?000" is returned if the argument is NULL or contains no ASCII alphabetic characters. This function is omitted from SQLite by default. It is only available if the SQLITE_SOUNDEX compile-time option is used when SQLite is built.
sqlite_compileoption_get(N) | The sqlite_compileoption_get() SQL function is a wrapper around the sqlite3_compileoption_get() C/C++ function. This routine returns the N-th compile-time option used to build SQLite or NULL if N is out of range. See also the compile_options pragma.
sqlite_compileoption_used(X) | The sqlite_compileoption_used() SQL function is a wrapper around the sqlite3_compileoption_used() C/C++ function. When the argument X to sqlite_compileoption_used(X) is a string which is the name of a compile-time option, this routine returns true (1) or false (0) depending on whether or not that option was used during the build.
sqlite_source_id() | The sqlite_source_id() function returns a string that identifies the specific version of the source code that was used to build the SQLite library. The string returned by sqlite_source_id() begins with the date and time that the source code was checked in and is follows by an SHA1 hash that uniquely identifies the source tree. This function is an SQL wrapper around the sqlite3_sourceid() C interface.
sqlite_version() | The sqlite_version() function returns the version string for the SQLite library that is running. This function is an SQL wrapper around the sqlite3_libversion() C-interface.
substr(X,Y,Z)

substr(X,Y) 		The substr(X,Y,Z) function returns a substring of input string X that begins with the Y-th character and which is Z characters long. If Z is omitted then substr(X,Y) returns all characters through the end of the string X beginning with the Y-th. The left-most character of X is number 1. If Y is negative then the first character of the substring is found by counting from the right rather than the left. If Z is negative then the abs(Z) characters preceding the Y-th character are returned. If X is a string then characters indices refer to actual UTF-8 characters. If X is a BLOB then the indices refer to bytes.
total_changes() | The total_changes() function returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the current database connection was opened. This function is a wrapper around the sqlite3_total_changes() C/C++ interface.
trim(X)

trim(X,Y) 		The trim(X,Y) function returns a string formed by removing any and all characters that appear in Y from both ends of X. If the Y argument is omitted, trim(X) removes spaces from both ends of X.
typeof(X) | The typeof(X) function returns a string that indicates the datatype of the expression X: "null", "integer", "real", "text", or "blob".
upper(X) | The upper(X) function returns a copy of input string X in which all lower-case ASCII characters are converted to their upper-case equivalent.
zeroblob(N) | The zeroblob(N) function returns a BLOB consisting of N bytes of 0x00. SQLite manages these zeroblobs very efficiently. Zeroblobs can be used to reserve space for a BLOB that is later written using incremental BLOB I/O. This SQL function is implemented using the sqlite3_result_zeroblob() routine from the C/C++ interface.


SQLite Query Language: CREATE INDEX

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

CREATE INDEX

create-index-stmt:

syntax diagram create-index-stmt

indexed-column:

syntax diagram indexed-column

The CREATE INDEX command consists of the keywords "CREATE INDEX" followed by the name of the new index, the keyword "ON", the name of a previously created table that is to be indexed, and a parenthesized list of names of columns in the table that are used for the index key.

Each column name can be followed by one of the "ASC" or "DESC" keywords to indicate sort order. The sort order may or may not be ignored depending on the database file format. The "legacy" file format ignores index sort order. The descending index file format takes index sort order into account. Only copies of SQLite newer than version 3.3.0 (released on 2006-01-10) are able to understand the newer descending index file format and so for compatibility with older versions of SQLite, the legacy file format is generated by default. Use the legacy_file_format pragma to modify this behavior and generate databases that use the newer file format. Future versions of SQLite may begin to generate the newer file format by default.

The COLLATE clause optionally following each column name defines a collating sequence used for text entries in that column. The default collating sequence is the collating sequence defined for that column in the CREATE TABLE statement. Or if no collating sequence is otherwise defined, the built-in BINARY collating sequence is used.

There are no arbitrary limits on the number of indices that can be attached to a single table. The number of columns in an index is limited to the value set by sqlite3_limit(SQLITE_LIMIT_COLUMN,...).

If the UNIQUE keyword appears between CREATE and INDEX then duplicate index entries are not allowed. Any attempt to insert a duplicate entry will result in an error. For the purposes of unique indices, all NULL values are considered to different from all other NULL values and are thus unique. This is one of the two possible interpretations of the SQL-92 standard (the language in the standard is ambiguous) and is the interpretation followed by PostgreSQL, MySQL, Firebird, and Oracle. Informix and Microsoft SQL Server follow the other interpretation of the standard.

If the optional IF NOT EXISTS clause is present and another index with the same name already exists, then this command becomes a no-op.

Indexes are removed with the DROP INDEX command.


SQLite Query Language: CREATE TABLE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

CREATE TABLE

create-table-stmt:

syntax diagram create-table-stmt

column-def:

syntax diagram column-def

type-name:

syntax diagram type-name

column-constraint:

syntax diagram column-constraint

table-constraint:

syntax diagram table-constraint

foreign-key-clause:

syntax diagram foreign-key-clause

The "CREATE TABLE" command is used to create a new table in an SQLite database. A CREATE TABLE command specifies the following attributes of the new table:

  • The name of the new table.

  • The database in which the new table is created. Tables may be created in the main database, the temp database, or in any attached database.

  • The name of each column in the table.

  • The declared type of each column in the table.

  • A default value or expression for each column in the table.

  • A default collation sequence to use with each column.

  • Optionally, a PRIMARY KEY for the table. Both single column and composite (multiple column) primary keys are supported.

  • A set of SQL constraints for each table. SQLite supports UNIQUE, NOT NULL, CHECK and FOREIGN KEY constraints.

Every CREATE TABLE statement must specify a name for the new table. Table names that begin with "sqlite_" are reserved for internal use. It is an error to attempt to create a table with a name that starts with "sqlite_".

If a <database-name> is specified, it must be either "main", "temp", or the name of an attached database. In this case the new table is created in the named database. If the "TEMP" or "TEMPORARY" keyword occurs between the "CREATE" and "TABLE" then the new table is created in the temp database. It is an error to specify both a <database-name> and the TEMP or TEMPORARY keyword, unless the <database-name> is "temp". If no database name is specified and the TEMP keyword is not present then the table is created in the main database.

It is usually an error to attempt to create a new table in a database that already contains a table, index or view of the same name. However, if the "IF NOT EXISTS" clause is specified as part of the CREATE TABLE statement and a table or view of the same name already exists, the CREATE TABLE command simply has no effect (and no error message is returned). An error is still returned if the table cannot be created because of an existing index, even if the "IF NOT EXISTS" clause is specified.

It is not an error to create a table that has the same name as an existing trigger.

Tables are removed using the DROP TABLE statement.

CREATE TABLE ... AS SELECT Statements

A "CREATE TABLE ... AS SELECT" statement creates and populates a database table based on the results of a SELECT statement. The table has the same number of columns as the rows returned by the SELECT statement. The name of each column is the same as the name of the corresponding column in the result set of the SELECT statement. The declared type of each column is determined by the expression affinity of the corresponding expression in the result set of the SELECT statement, as follows:

Expression Affinity | Column Declared Type
TEXT | "TEXT"
NUMERIC | "NUM"
INTEGER | "INT"
REAL | "REAL"
NONE | "" (empty string)

A table created using CREATE TABLE AS has no PRIMARY KEY and no constraints of any kind. The default value of each column is NULL. The default collation sequence for each column of the new table is BINARY.

Tables created using CREATE TABLE AS are initially populated with the rows of data returned by the SELECT statement. Rows are assigned contiguously ascending rowid values, starting with 1, in the order that they are returned by the SELECT statement.

Column Definitions

Unless it is a CREATE TABLE ... AS SELECT statement, a CREATE TABLE includes one or more column definitions, optionally followed by a list of table constraints. Each column definition consists of the name of the column, optionally followed by the declared type of the column, then one or more optional column constraints. Included in the definition of "column constraints" for the purposes of the previous statement are the COLLATE and DEFAULT clauses, even though these are not really constraints in the sense that they do not restrict the data that the table may contain. The other constraints - NOT NULL, CHECK, UNIQUE, PRIMARY KEY and FOREIGN KEY constraints - impose restrictions on the tables data, and are are described under SQL Data Constraints below.

Unlike most SQL databases, SQLite does not restrict the type of data that may be inserted into a column based on the columns declared type. Instead, SQLite uses dynamic typing. The declared type of a column is used to determine the affinity of the column only.

The DEFAULT clause specifies a default value to use for the column if no value is explicitly provided by the user when doing an INSERT. If there is no explicit DEFAULT clause attached to a column definition, then the default value of the column is NULL. An explicit DEFAULT clause may specify that the default value is NULL, a string constant, a blob constant, a signed-number, or any constant expression enclosed in parentheses. An explicit default value may also be one of the special case-independent keywords CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP. For the purposes of the DEFAULT clause, an expression is considered constant provided that it does not contain any sub-queries or string constants enclosed in double quotes.

Each time a row is inserted into the table by an INSERT statement that does not provide explicit values for all table columns the values stored in the new row are determined by their default values, as follows:

  • If the default value of the column is a constant NULL, text, blob or signed-number value, then that value is used directly in the new row.

  • If the default value of a column is an expression in parentheses, then the expression is evaluated once for each row inserted and the results used in the new row.

  • If the default value of a column is CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP, then the value used in the new row is a text representation of the current UTC date and/or time. For CURRENT_TIME, the format of the value is "HH:MM:SS". For CURRENT_DATE, "YYYY-MM-DD". The format for CURRENT_TIMESTAMP is "YYYY-MM-DD HH:MM:SS".

The COLLATE clause specifies the name of a collating sequence to use as the default collation sequence for the column. If no COLLATE clause is specified, the default collation sequence is BINARY.

The number of columns in a table is limited by the SQLITE_MAX_COLUMN compile-time parameter. A single row of a table cannot store more than SQLITE_MAX_LENGTH bytes of data. Both of these limits can be lowered at runtime using the sqlite3_limit() C/C++ interface.

SQL Data Constraints

Each table in SQLite may have at most one PRIMARY KEY. If the keywords PRIMARY KEY are added to a column definition, then the primary key for the table consists of that single column. Or, if a PRIMARY KEY clause is specified as a table-constraint, then the primary key of the table consists of the list of columns specified as part of the PRIMARY KEY clause. If there is more than one PRIMARY KEY clause in a single CREATE TABLE statement, it is an error.

If a table has a single column primary key, and the declared type of that column is "INTEGER", then the column is known as an INTEGER PRIMARY KEY. See below for a description of the special properties and behaviors associated with an INTEGER PRIMARY KEY.

Each row in a table with a primary key must feature a unique combination of values in its primary key columns. For the purposes of determining the uniqueness of primary key values, NULL values are considered distinct from all other values, including other NULLs. If an INSERT or UPDATE statement attempts to modify the table content so that two or more rows feature identical primary key values, it is a constraint violation. According to the SQL standard, PRIMARY KEY should always imply NOT NULL. Unfortunately, due to a long-standing coding oversight, this is not the case in SQLite. Unless the column is an INTEGER PRIMARY KEY SQLite allows NULL values in a PRIMARY KEY column. We could change SQLite to conform to the standard (and we might do so in the future), but by the time the oversight was discovered, SQLite was in such wide use that we feared breaking legacy code if we fixed the problem. So for now we have chosen to continue allowing NULLs in PRIMARY KEY columns. Developers should be aware, however, that we may change SQLite to conform to the SQL standard in future and should design new programs accordingly.

A UNIQUE constraint is similar to a PRIMARY KEY constraint, except that a single table may have any number of UNIQUE constraints. For each UNIQUE constraint on the table, each row must feature a unique combination of values in the columns identified by the UNIQUE constraint. As with PRIMARY KEY constraints, for the purposes of UNIQUE constraints NULL values are considered distinct from all other values (including other NULLs). If an INSERT or UPDATE statement attempts to modify the table content so that two or more rows feature identical values in a set of columns that are subject to a UNIQUE constraint, it is a constraint violation.

INTEGER PRIMARY KEY columns aside, both UNIQUE and PRIMARY KEY constraints are implemented by creating an index in the database (in the same way as a "CREATE UNIQUE INDEX" statement would). Such an index is used like any other index in the database to optimize queries. As a result, there often no advantage (but significant overhead) in creating an index on a set of columns that are already collectively subject to a UNIQUE or PRIMARY KEY constraint.

A CHECK constraint may be attached to a column definition or specified as a table constraint. In practice it makes no difference. Each time a new row is inserted into the table or an existing row is updated, the expression associated with each CHECK constraint is evaluated and cast to a NUMERIC value in the same way as a CAST expression. If the result is zero (integer value 0 or real value 0.0), then a constraint violation has occurred. If the CHECK expression evaluates to NULL, or any other non-zero value, it is not a constraint violation. The expression of a CHECK constraint may not contain a subquery.

CHECK constraints have been supported since version 3.3.0. Prior to version 3.3.0, CHECK constraints were parsed but not enforced.

A NOT NULL constraint may only be attached to a column definition, not specified as a table constraint. Not surprisingly, a NOT NULL constraint dictates that the associated column may not contain a NULL value. Attempting to set the column value to NULL when inserting a new row or updating an existing one causes a constraint violation.

Exactly how a constraint violation is dealt with is determined by the constraint conflict resolution algorithm. Each PRIMARY KEY, UNIQUE, NOT NULL and CHECK constraint has a default conflict resolution algorithm. PRIMARY KEY, UNIQUE and NOT NULL constraints may be explicitly assigned a default conflict resolution algorithm by including a conflict-clause in their definitions. Or, if a constraint definition does not include a conflict-clause or it is a CHECK constraint, the default conflict resolution algorithm is ABORT. Different constraints within the same table may have different default conflict resolution algorithms. See the section titled ON CONFLICT for additional information.

ROWIDs and the INTEGER PRIMARY KEY

Every row of every SQLite table has a 64-bit signed integer key that uniquely identifies the row within its table. This integer is usually called the "rowid". The rowid value can be accessed using one of the special case-independent names "rowid", "oid", or "_rowid_" in place of a column name. If a table contains a user defined column named "rowid", "oid" or "_rowid_", then that name always refers the explicitly declared column and cannot be used to retrieve the integer rowid value.

The data for each table in SQLite is stored as a B-Tree structure containing an entry for each table row, using the rowid value as the key. This means that retrieving or sorting records by rowid is fast. Searching for a record with a specific rowid, or for all records with rowids within a specified range is around twice as fast as a similar search made by specifying any other PRIMARY KEY or indexed value.

With one exception, if a table has a primary key that consists of a single column, and the declared type of that column is "INTEGER" in any mixture of upper and lower case, then the column becomes an alias for the rowid. Such a column is usually referred to as an "integer primary key". A PRIMARY KEY column only becomes an integer primary key if the declared type name is exactly "INTEGER". Other integer type names like "INT" or "BIGINT" or "SHORT INTEGER" or "UNSIGNED INTEGER" causes the primary key column to behave as an ordinary table column with integer affinity and a unique index, not as an alias for the rowid.

The exception mentioned above is that if the declaration of a column with declared type "INTEGER" includes an "PRIMARY KEY DESC" clause, it does not become an alias for the rowid and is not classified as an integer primary key. This quirk is not by design. It is due to a bug in early versions of SQLite. But fixing the bug could result in very serious backwards incompatibilities. The SQLite developers feel that goofy behavior in a corner case is far better than a compatibility break, so the original behavior is retained. This means that the following three table declarations all cause the column "x" to be an alias for the rowid (an integer primary key):

  • CREATE TABLE t(x INTEGER PRIMARY KEY ASC, y, z);
  • CREATE TABLE t(x INTEGER, y, z, PRIMARY KEY(x ASC));
  • CREATE TABLE t(x INTEGER, y, z, PRIMARY KEY(x DESC));

But the following declaration does not result in "x" being an alias for the rowid:

  • CREATE TABLE t(x INTEGER PRIMARY KEY DESC, y, z);

Rowid values may be modified using an UPDATE statement in the same way as any other column value can, either using one of the built-in aliases ("rowid", "oid" or "_rowid_") or by using an alias created by an integer primary key. Similarly, an INSERT statement may provide a value to use as the rowid for each row inserted. Unlike normal SQLite columns, an integer primary key or rowid column must contain integer values. Integer primary key or rowid columns are not able to hold floating point values, strings, BLOBs, or NULLs.

If an UPDATE statement attempts to set an integer primary key or rowid column to a NULL or blob value, or to a string or real value that cannot be losslessly converted to an integer, a "datatype mismatch" error occurs and the statement is aborted. If an INSERT statement attempts to insert a blob value, or a string or real value that cannot be losslessly converted to an integer into an integer primary key or rowid column, a "datatype mismatch" error occurs and the statement is aborted.

If an INSERT statement attempts to insert a NULL value into a rowid or integer primary key column, the system chooses an integer value to use as the rowid automatically. A detailed description of how this is done is provided separately.

The parent key of a foreign key constraint is not allowed to use the rowid. The parent key must used named columns only.


SQLite Query Language: CREATE TRIGGER

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

CREATE TRIGGER

create-trigger-stmt:

syntax diagram create-trigger-stmt

The CREATE TRIGGER statement is used to add triggers to the database schema. Triggers are database operations that are automatically performed when a specified database event occurs.

A trigger may be specified to fire whenever a DELETE, INSERT, or UPDATE of a particular database table occurs, or whenever an UPDATE occurs on on one or more specified columns of a table.

At this time SQLite supports only FOR EACH ROW triggers, not FOR EACH STATEMENT triggers. Hence explicitly specifying FOR EACH ROW is optional. FOR EACH ROW implies that the SQL statements specified in the trigger may be executed (depending on the WHEN clause) for each database row being inserted, updated or deleted by the statement causing the trigger to fire.

Both the WHEN clause and the trigger actions may access elements of the row being inserted, deleted or updated using references of the form "NEW.column-name" and "OLD.column-name", where column-name is the name of a column from the table that the trigger is associated with. OLD and NEW references may only be used in triggers on events for which they are relevant, as follows:

INSERT | NEW references are valid
UPDATE | NEW and OLD references are valid
DELETE | OLD references are valid

If a WHEN clause is supplied, the SQL statements specified are only executed for rows for which the WHEN clause is true. If no WHEN clause is supplied, the SQL statements are executed for all rows.

The BEFORE or AFTER keyword determines when the trigger actions will be executed relative to the insertion, modification or removal of the associated row.

An ON CONFLICT clause may be specified as part of an UPDATE or INSERT action within the body of the trigger. However if an ON CONFLICT clause is specified as part of the statement causing the trigger to fire, then conflict handling policy of the outer statement is used instead.

Triggers are automatically dropped when the table that they are associated with (the table-name table) is dropped. However if the trigger actions reference other tables, the trigger is not dropped or modified if those other tables are dropped or modified.

Triggers are removed using the DROP TRIGGER statement.

Syntax Restrictions On UPDATE, DELETE, and INSERT Statements Within Triggers

The UPDATE, DELETE, and INSERT statements within triggers do not support the full syntax for UPDATE, DELETE, and INSERT statements. The following restrictions apply:

  • The name of the table to be modified in an UPDATE, DELETE, or INSERT statement must be an unqualified table name. In other words, one must use just "tablename" not "database.tablename" when specifying the table. The table to be modified must exist in the same database as the table or view to which the trigger is attached.

  • The "INSERT INTO table DEFAULT VALUES" form of the INSERT statement is not supported.

  • The INDEXED BY and NOT INDEXED clauses are not supported for UPDATE and DELETE statements.

  • The ORDER BY and LIMIT clauses on UPDATE and DELETE statements are not supported. ORDER BY and LIMIT are not normally supported for UPDATE or DELETE in any context but can be enabled for top-level statements using the SQLITE_ENABLE_UPDATE_DELETE_LIMIT compile-time option. However, that compile-time option only applies to top-level UPDATE and DELETE statements, not UPDATE and DELETE statements within triggers.

INSTEAD OF trigger

Triggers may be created on views, as well as ordinary tables, by specifying INSTEAD OF in the CREATE TRIGGER statement. If one or more ON INSERT, ON DELETE or ON UPDATE triggers are defined on a view, then it is not an error to execute an INSERT, DELETE or UPDATE statement on the view, respectively. Instead, executing an INSERT, DELETE or UPDATE on the view causes the associated triggers to fire. The real tables underlying the view are not modified (except possibly explicitly, by a trigger program).

Note that the sqlite3_changes() and sqlite3_total_changes() interfaces do not count INSTEAD OF trigger firings, but the count_changes pragma does count INSTEAD OF trigger firing.

Examples

Assuming that customer records are stored in the "customers" table, and that order records are stored in the "orders" table, the following trigger ensures that all associated orders are redirected when a customer changes his or her address:

CREATE TRIGGER update_customer_address UPDATE OF address ON customers
  BEGIN
    UPDATE orders SET address = new.address WHERE customer_name = old.name;
  END;

With this trigger installed, executing the statement:

UPDATE customers SET address = '1 Main St.' WHERE name = 'Jack Jones';

causes the following to be automatically executed:

UPDATE orders SET address = '1 Main St.' WHERE customer_name = 'Jack Jones';

Cautions On The Use Of BEFORE triggers

If a BEFORE UPDATE or BEFORE DELETE trigger modifies or deletes a row that was to have been updated or deleted, then the result of the subsequent update or delete operation is undefined. Furthermore, if a BEFORE trigger modifies or deletes a row, then it is undefined whether or not AFTER triggers that would have otherwise run on those rows will in fact run.

The value of NEW.rowid is undefined in a BEFORE INSERT trigger in which the rowid is not explicitly set to an integer.

Because of the behaviors described above, programmers are encouraged to prefer AFTER triggers over BEFORE triggers.

The RAISE() function

A special SQL function RAISE() may be used within a trigger-program, with the following syntax

raise-function:

syntax diagram raise-function

When one of the first three forms is called during trigger-program execution, the specified ON CONFLICT processing is performed (either ABORT, FAIL or ROLLBACK) and the current query terminates. An error code of SQLITE_CONSTRAINT is returned to the application, along with the specified error message.

When RAISE(IGNORE) is called, the remainder of the current trigger program, the statement that caused the trigger program to execute and any subsequent trigger programs that would of been executed are abandoned. No database changes are rolled back. If the statement that caused the trigger program to execute is itself part of a trigger program, then that trigger program resumes execution at the beginning of the next step.


SQLite Query Language: CREATE VIEW

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

CREATE VIEW

create-view-stmt:

syntax diagram create-view-stmt

The CREATE VIEW command assigns a name to a pre-packaged SELECT statement. Once the view is created, it can be used in the FROM clause of another SELECT in place of a table name.

If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE" and "VIEW" then the view that is created is only visible to the process that opened the database and is automatically deleted when the database is closed.

If a <database-name> is specified, then the view is created in the named database. It is an error to specify both a <database-name> and the TEMP keyword on a VIEW, unless the <database-name> is "temp". If no database name is specified, and the TEMP keyword is not present, the VIEW is created in the main database.

You cannot DELETE, INSERT, or UPDATE a view. Views are read-only in SQLite. However, in many cases you can use an INSTEAD OF trigger on the view to accomplish the same thing. Views are removed with the DROP VIEW command.


SQLite Query Language: CREATE VIRTUAL TABLE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

CREATE VIRTUAL TABLE

create-virtual-table-stmt:

syntax diagram create-virtual-table-stmt

A virtual table is an interface to an external storage or computation engine that appears to be a table but does not actually store information in the database file.

In general, you can do anything with a virtual table that can be done with an ordinary table, except that you cannot create indices or triggers on a virtual table. Some virtual table implementations might impose additional restrictions. For example, many virtual tables are read-only.

The <module-name> is the name of an object that implements the virtual table. The <module-name> must be registered with the SQLite database connection using sqlite3_create_module() or sqlite3_create_module_v2() prior to issuing the CREATE VIRTUAL TABLE statement. The module takes zero or more comma-separated arguments. The arguments can be just about any text as long as it has balanced parentheses. The argument syntax is sufficiently general that the arguments can be made to appear as column definitions in a traditional CREATE TABLE statement. SQLite passes the module arguments directly to the xCreate and xConnect methods of the module implementation without any interpretation. It is the responsibility of the module implementation to parse and interpret its own arguments.

A virtual table is destroyed using the ordinary DROP TABLE statement. There is no DROP VIRTUAL TABLE statement.


SQLite Query Language: Date And Time Functions

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

Date And Time Functions

SQLite supports five date and time functions as follows:

  1. date(timestring, modifier, modifier, ...)
  2. time(timestring, modifier, modifier, ...)
  3. datetime(timestring, modifier, modifier, ...)
  4. julianday(timestring, modifier, modifier, ...)
  5. strftime(format, timestring, modifier, modifier, ...)

All five date and time functions take a time string as an argument. The time string is followed by zero or more modifiers. The strftime() function also takes a format string as its first argument.

The date and time functions use a subset of IS0-8601 date and time formats. The date() function returns the date in this format: YYYY-MM-DD. The time() function returns the time as HH:MM:SS. The datetime() function returns "YYYY-MM-DD HH:MM:SS". The julianday() function returns the Julian day - the number of days since noon in Greenwich on November 24, 4714 B.C. (Proleptic Gregorian calendar). The strftime() routine returns the date formatted according to the format string specified as the first argument. The format string supports the most common substitutions found in the strftime() function from the standard C library plus two new substitutions, %f and %J. The following is a complete list of valid strftime() substitutions:

%d | day of month: 00
%f | fractional seconds: SS.SSS
%H | hour: 00-24
%j | day of year: 001-366
%J | Julian day number
%m | month: 01-12
%M | minute: 00-59
%s | seconds since 1970-01-01
%S | seconds: 00-59
%w | day of week 0-6 with Sunday==0
%W | week of year: 00-53
%Y | year: 0000-9999
%% %

Notice that all other date and time functions can be expressed in terms of strftime():

Function | Equivalent strftime()
date(...) | strftime('%Y-%m-%d', ...)
time(...) | strftime('%H:%M:%S', ...)
datetime(...) | strftime('%Y-%m-%d %H:%M:%S', ...)
julianday(...) | strftime('%J', ...)

The only reasons for providing functions other than strftime() is for convenience and for efficiency.

Time Strings

A time string can be in any of the following formats:

  1. YYYY-MM-DD
  2. YYYY-MM-DD HH:MM
  3. YYYY-MM-DD HH:MM:SS
  4. YYYY-MM-DD HH:MM:SS.SSS
  5. YYYY-MM-DD T HH:MM
  6. YYYY-MM-DD T HH:MM:SS
  7. YYYY-MM-DD T HH:MM:SS.SSS
  8. HH:MM
  9. HH:MM:SS
  10. HH:MM:SS.SSS
  11. now
  12. DDDDDDDDDD

In formats 5 through 7, the "T" is a literal character separating the date and the time, as required by ISO-8601. Formats 8 through 10 that specify only a time assume a date of 2000-01-01. Format 11, the string 'now', is converted into the current date and time as obtained from the xCurrentTime method of the sqlite3_vfs object in use. Universal Coordinated Time (UTC) is used. Format 12 is the Julian day number expressed as a floating point value.

Modifiers

The time string can be followed by zero or more modifiers that alter date and/or time. Each modifier is a transformation that is applied to the time value to its left. Modifiers are applied from left to right; order is important. The available modifiers are as follows.

  1. NNN days
  2. NNN hours
  3. NNN minutes
  4. NNN.NNNN seconds
  5. NNN months
  6. NNN years
  7. start of month
  8. start of year
  9. start of day
  10. weekday N
  11. unixepoch
  12. localtime
  13. utc

The first six modifiers (1 through 6) simply add the specified amount of time to the date and time specified by the preceding timestring and modifiers. Note that "±NNN months" works by rendering the original date into the YYYY-MM-DD format, adding the ±NNN to the MM month value, then normalizing the result. Thus, for example, the data 2001-03-31 modified by '+1 month' initially yields 2001-04-31, but April only has 30 days so the date is normalized to 2001-05-01. A similar effect occurs when the original date is February 29 of a leapyear and the modifier is ±N years where N is not a multiple of four.

The "start of" modifiers (7 through 9) shift the date backwards to the beginning of the current month, year or day.

The "weekday" modifier advances the date forward to the next date where the weekday number is N. Sunday is 0, Monday is 1, and so forth.

The "unixepoch" modifier (11) only works if it immediately follows a timestring in the DDDDDDDDDD format. This modifier causes the DDDDDDDDDD to be interpreted not as a Julian day number as it normally would be, but as Unix Time - the number of seconds since 1970. If the "unixepoch" modifier does not follow a timestring of the form DDDDDDDDDD which expresses the number of seconds since 1970 or if other modifiers separate the "unixepoch" modifier from prior DDDDDDDDDD then the behavior is undefined. Due to precision limitations imposed by the implementations use of 64-bit integers, the "unixepoch" modifier only works for dates between 0000-01-01 00:00:00 and 5352-11-01 10:52:47 (unix times of -62167219200 through 10675199167).

The "localtime" modifier (12) assumes the time string to its left is in Universal Coordinated Time (UTC) and adjusts the time string so that it displays localtime. If "localtime" follows a time that is not UTC, then the behavior is undefined. The "utc" is the opposite of "localtime". "utc" assumes that the string to its left is in the local timezone and adjusts that string to be in UTC. If the prior string is not in localtime, then the result of "utc" is undefined.

Examples

Compute the current date.

SELECT date('now');

Compute the last day of the current month.

SELECT date('now','start of month','+1 month','-1 day');

Compute the date and time given a unix timestamp 1092941466.

SELECT datetime(1092941466, 'unixepoch');

Compute the date and time given a unix timestamp 1092941466, and compensate for your local timezone.

SELECT datetime(1092941466, 'unixepoch', 'localtime');

Compute the current unix timestamp.

SELECT strftime('%s','now');

Compute the number of days since the signing of the US Declaration of Independence.

SELECT julianday('now') - julianday('1776-07-04');

Compute the number of seconds since a particular moment in 2004:

SELECT strftime('%s','now') - strftime('%s','2004-01-01 02:34:56');

Compute the date of the first Tuesday in October for the current year.

SELECT date('now','start of year','+9 months','weekday 2');

Compute the time since the unix epoch in seconds (like strftime('%s','now') except includes fractional part):

SELECT (julianday('now') - 2440587.5)*86400.0;

Caveats And Bugs

The computation of local time depends heavily on the whim of politicians and is thus difficult to get correct for all locales. In this implementation, the standard C library function localtime_r() is used to assist in the calculation of local time. The localtime_r() C function normally only works for years between 1970 and 2037. For dates outside this range, SQLite attempts to map the year into an equivalent year within this range, do the calculation, then map the year back.

These functions only work for dates between 0000-01-01 00:00:00 and 9999-12-31 23:59:59 (julidan day numbers 1721059.5 through 5373484.5). For dates outside that range, the results of these functions are undefined.

Non-Vista Windows platforms only support one set of DST rules. Vista only supports two. Therefore, on these platforms, historical DST calculations will be incorrect. For example, in the US, in 2007 the DST rules changed. Non-Vista Windows platforms apply the new 2007 DST rules to all previous years as well. Vista does somewhat better getting results correct back to 1986, when the rules were also changed.

All internal computations assume the Gregorian calendar system. It is also assumed that every day is exactly 86400 seconds in duration.


SQLite Query Language: DELETE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DELETE

delete-stmt:

syntax diagram delete-stmt

qualified-table-name:

syntax diagram qualified-table-name

The DELETE command removes records from the table identified by the qualified-table-name.

If the WHERE clause is not present, all records in the table are deleted. If a WHERE clause is supplied, then only those rows for which the result of evaluating the WHERE clause as a boolean expression is true are deleted.

Restrictions on DELETE Statements Within CREATE TRIGGER

The following restrictions apply to DELETE statements that occur within the body of a CREATE TRIGGER statement:

  • The table-name specified as part of a DELETE statement within a trigger body must be unqualified. In other words, the database-name. prefix on the table name is not allowed within triggers. If the table to which the trigger is attached is not in the temp database, then DELETE statements within the trigger body must operate on tables within the same database as it. If the table to which the trigger is attached is in the TEMP database, then the unqualified name of the table being deleted is resolved in the same way as it is for a top-level statement (by searching first the TEMP database, then the main database, then any other databases in the order they were attached).

  • The INDEXED BY and NOT INDEXED clauses are not allowed on DELETE statements within triggers.

  • The LIMIT and ORDER BY clauses (described below) are unsupported for DELETE statements within triggers.

Optional LIMIT and ORDER BY clauses

If SQLite is compiled with the SQLITE_ENABLE_UPDATE_DELETE_LIMIT compile-time option, then the syntax of the DELETE statement is extended by the addition of optional ORDER BY and LIMIT clauses:

delete-stmt-limited:

syntax diagram delete-stmt-limited

If a DELETE statement has a LIMIT clause, the maximum number of rows that will be deleted is found by evaluating the accompanying expression and casting it to an integer value. If the result of the evaluating the LIMIT clause cannot be losslessly converted to an integer value, it is an error. A negative LIMIT value is interpreted as "no limit". If the DELETE statement also has an OFFSET clause, then it is similarly evaluated and cast to an integer value. Again, it is an error if the value cannot be losslessly converted to an integer. If there is no OFFSET clause, or the calculated integer value is negative, the effective OFFSET value is zero.

If the DELETE statement has an ORDER BY clause, then all rows that would be deleted in the absence of the LIMIT clause are sorted according to the ORDER BY. The first M rows, where M is the value found by evaluating the OFFSET clause expression, are skipped, and the following N, where N is the value of the LIMIT expression, are deleted. If there are less than N rows remaining after taking the OFFSET clause into account, or if the LIMIT clause evaluated to a negative value, then all remaining rows are deleted.

If the DELETE statement has no ORDER BY clause, then all rows that would be deleted in the absence of the LIMIT clause are assembled in an arbitrary order before applying the LIMIT and OFFSET clauses to determine the subset that are actually deleted.

The ORDER BY clause on a DELETE statement is used only to determine which rows fall within the LIMIT. The order in which rows are deleted is arbitrary and is not influenced by the ORDER BY clause.

The Truncate Optimization

When the WHERE is omitted from a DELETE statement and the table being deleted has no triggers, SQLite uses an optimization to erase the entire table content without having to visit each row of the table individually. This "truncate" optimization makes the delete run much faster. Prior to SQLite version 3.6.5, the truncate optimization also meant that the sqlite3_changes() and sqlite3_total_changes() interfaces and the count_changes pragma will not actually return the number of deleted rows. That problem has been fixed as of version 3.6.5.

The truncate optimization can be permanently disabled for all queries by recompiling SQLite with the SQLITE_OMIT_TRUNCATE_OPTIMIZATION compile-time switch.

The truncate optimization can also be disabled at runtime using the sqlite3_set_authorizer() interface. If an authorizer callback returns SQLITE_IGNORE for an SQLITE_DELETE action code, then the DELETE operation will proceed but the truncate optimization will be bypassed and rows will be deleted one by one.


SQLite Query Language: DETACH DATABASE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DETACH DATABASE

detach-stmt:

syntax diagram detach-stmt

This statement detaches an additional database connection previously attached using the ATTACH statement. It is possible to have the same database file attached multiple times using different names, and detaching one connection to a file will leave the others intact.

This statement will fail if SQLite is in the middle of a transaction.


SQLite Query Language: DROP INDEX

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DROP INDEX

drop-index-stmt:

syntax diagram drop-index-stmt

The DROP INDEX statement removes an index added with the CREATE INDEX statement. The index is completely removed from the disk. The only way to recover the index is to reenter the appropriate CREATE INDEX command.


SQLite Query Language: DROP TABLE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DROP TABLE

drop-table-stmt:

syntax diagram drop-table-stmt

The DROP TABLE statement removes a table added with the CREATE TABLE statement. The name specified is the table name. The dropped table is completely removed from the database schema and the disk file. The table can not be recovered. All indices and triggers associated with the table are also deleted.

The optional IF EXISTS clause suppresses the error that would normally result if the table does not exist.

If foreign key constraints are enabled, a DROP TABLE command performs an implicit DELETE FROM <tbl> command before removing the table from the database schema. Any triggers attached to the table are dropped from the database schema before the implicit DELETE FROM <tbl> is executed, so this cannot cause any triggers to fire. By contrast, an implicit DELETE FROM <tbl> does cause any configured foreign key actions to take place. If the implicit DELETE FROM <tbl> executed as part of a DROP TABLE command violates any immediate foreign key constraints, an error is returned and the table is not dropped. If the implicit DELETE FROM <tbl> causes any deferred foreign key constraints to be violated, and the violations still exist when the transaction is committed, an error is returned at the time of commit.


SQLite Query Language: DROP TRIGGER

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DROP TRIGGER

drop-trigger-stmt:

syntax diagram drop-trigger-stmt

The DROP TRIGGER statement removes a trigger created by the CREATE TRIGGER statement. Once removed, the trigger definition is no longer present in the sqlite_master (or sqlite_temp_master) table and is not fired by any subsequent INSERT, UPDATE or DELETE statements.

Note that triggers are automatically dropped when the associated table is dropped.


SQLite Query Language: DROP VIEW

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

DROP VIEW

drop-view-stmt:

syntax diagram drop-view-stmt

The DROP VIEW statement removes a view created by the CREATE VIEW statement. The view definition is removed from the database schema, but no actual data in the underlying base tables is modified.

The view to drop is identified by the view-name and optional database-name specified as part of the DROP VIEW statement. This reference is resolved using the standard procedure for object resolution.

If the specified view cannot be found and the IF EXISTS clause is not present, it is an error. If the specified view cannot be found and an IF EXISTS clause is present in the DROP VIEW statement, then the statement is a no-op.


SQLite Query Language: EXPLAIN

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

EXPLAIN

sql-stmt:

syntax diagram sql-stmt

An SQL statement can be preceded by the keyword "EXPLAIN" or by the phrase "EXPLAIN QUERY PLAN". Either modification causes the SQL statement to behave as a query and to return information about how the SQL statement would have operated if the EXPLAIN keyword or phrase had been omitted.

The output from EXPLAIN and EXPLAIN QUERY PLAN is intended for interactive analysis and troubleshooting only. The details of the output format are subject to change from one release of SQLite to the next. Applications should not use EXPLAIN or EXPLAIN QUERY PLAN since their exact behavior is variable and only partially documented.

When the EXPLAIN keyword appears by itself it causes the statement to behave as a query that returns the sequence of virtual machine instructions it would have used to execute the command had the EXPLAIN keyword not been present. When the EXPLAIN QUERY PLAN phrase appears, the statement returns high-level information regarding the query plan that would have been used. The EXPLAIN QUERY PLAN command is described in more detail here.


SQLite Query Language: expression

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

expression

expr:

syntax diagram expr

literal-value:

syntax diagram literal-value

signed-number:

syntax diagram signed-number

raise-function:

syntax diagram raise-function

This section is different from the others. Most other sections of this document talks about a particular SQL command. This section does not talk about a standalone command but about "expressions" which are subcomponents of most other commands.

Operators

SQLite understands the following binary operators, in order from highest to lowest precedence:

||
*    /    %
+    -
<<   >>   &    |
<    <=   >    >=
=    ==   !=   <>   IS   IS NOT   IN   LIKE   GLOB   MATCH   REGEXP
AND
OR

Supported unary prefix operators are these:

-    +    ~    NOT

The COLLATE operator is a unary postfix operator that assigns a collating sequence to an expression. The COLLATE operator has a higher precedence (binds more tightly) than any prefix unary operator or any binary operator. The collating sequence set by the COLLATE operator overrides the collating sequence determined by the COLLATE clause in a table column definition. See the detailed discussion on collating sequences in the Datatype In SQLite3 document for additional information.

The unary operator + is a no-op. It can be applied to strings, numbers, blobs or NULL and it always returns a result with the same value as the operand.

Note that there are two variations of the equals and not equals operators. Equals can be either = or ==. The non-equals operator can be either != or <>. The || operator is "concatenate" - it joins together the two strings of its operands. The operator % outputs the value of its left operand modulo its right operand.

The result of any binary operator is either a numeric value or NULL, except for the || concatenation operator which always evaluates to either NULL or a text value.

The IS and IS NOT operators work like = and != except when one or both of the operands are NULL. In this case, if both operands are NULL, then the IS operator evaluates to 1 (true) and the IS NOT operator evaluates to 0 (false). If one operand is NULL and the other is not, then the IS operator evaluates to 0 (false) and the IS NOT operator is 1 (true). It is not possible for an IS or IS NOT expression to evaluate to NULL. Operators IS and IS NOT have the same precedence as =.

Literal Values

A literal value is a constant of some kind. Literal values may be integers, floating point numbers, strings, BLOBs, or NULLs.

The syntax for integer and floating point literals (collectively "numeric literals") is shown by the following diagram:

numeric-literal:

syntax diagram numeric-literal

If a numeric literal has a decimal point or an exponentiation clause, then it is a floating point literal. Otherwise is it is an integer literal. The "E" character that begins the exponentiation clause of a floating point literal can be either upper or lower case. The "." character is always used as the decimal point even if the locale setting specifies "," for this role - the use of "," for the decimal point would result in syntactic ambiguity.

A string constant is formed by enclosing the string in single quotes ('). A single quote within the string can be encoded by putting two single quotes in a row - as in Pascal. C-style escapes using the backslash character are not supported because they are not standard SQL. BLOB literals are string literals containing hexadecimal data and preceded by a single "x" or "X" character. For example:

X'53514C697465'

A literal value can also be the token "NULL".

Parameters

A "variable" or "parameter" token specifies a placeholder in the expression for a value that is filled in at runtime using the sqlite3_bind() family of C/C++ interfaces. Parameters can take several forms:

?NNN | A question mark followed by a number NNN holds a spot for the NNN-th parameter. NNN must be between 1 and SQLITE_MAX_VARIABLE_NUMBER.
? A question mark that is not followed by a number creates a parameter with a number one greater than the largest parameter number already assigned. If this means the parameter number is greater than SQLITE_MAX_VARIABLE_NUMBER, it is an error.
:AAAA | A colon followed by an identifier name holds a spot for a named parameter with the name :AAAA. Named parameters are also numbered. The number assigned is one greater than the largest parameter number already assigned. If this means the parameter would be assigned a number greater than SQLITE_MAX_VARIABLE_NUMBER, it is an error. To avoid confusion, it is best to avoid mixing named and numbered parameters.
@AAAA | An "at" sign works exactly like a colon, except that the name of the parameter created is @AAAA.
$AAAA | A dollar-sign followed by an identifier name also holds a spot for a named parameter with the name $AAAA. The identifier name in this case can include one or more occurrences of "::" and a suffix enclosed in "(...)" containing any text at all. This syntax is the form of a variable name in the Tcl programming language. The presence of this syntax results from the fact that SQLite is really a Tcl extension that has escaped into the wild.

Parameters that are not assigned values using sqlite3_bind() are treated as NULL.

The maximum parameter number is set at compile-time by the SQLITE_MAX_VARIABLE_NUMBER macro. An individual database connections D can reduce its maximum parameter number below the compile-time maximum using the sqlite3_limit(D, SQLITE_LIMIT_VARIABLE_NUMBER,...) interface.

The LIKE and GLOB operators

The LIKE operator does a pattern matching comparison. The operand to the right of the LIKE operator contains the pattern and the left hand operand contains the string to match against the pattern. A percent symbol ("%") in the LIKE pattern matches any sequence of zero or more characters in the string. An underscore ("_") in the LIKE pattern matches any single character in the string. Any other character matches itself or its lower/upper case equivalent (i.e. case-insensitive matching). (A bug: SQLite only understands upper/lower case for ASCII characters by default. The LIKE operator is case sensitive by default for unicode characters that are beyond the ASCII range. For example, the expression 'a' LIKE 'A' is TRUE but 'æ' LIKE 'Æ' is FALSE.)

If the optional ESCAPE clause is present, then the expression following the ESCAPE keyword must evaluate to a string consisting of a single character. This character may be used in the LIKE pattern to include literal percent or underscore characters. The escape character followed by a percent symbol (%), underscore (_), or a second instance of the escape character itself matches a literal percent symbol, underscore, or a single escape character, respectively.

The infix LIKE operator is implemented by calling the application-defined SQL functions like(Y,X) or like(Y,X,Z).

The LIKE operator can be made case sensitive using the case_sensitive_like pragma.

The GLOB operator is similar to LIKE but uses the Unix file globbing syntax for its wildcards. Also, GLOB is case sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by the NOT keyword to invert the sense of the test. The infix GLOB operator is implemented by calling the function glob(Y,X) and can be modified by overriding that function.

The REGEXP operator is a special syntax for the regexp() user function. No regexp() user function is defined by default and so use of the REGEXP operator will normally result in an error message. If a application-defined SQL function named "regexp" is added at run-time, that function will be called in order to implement the REGEXP operator.

The MATCH operator is a special syntax for the match() application-defined function. The default match() function implementation raises an exception and is not really useful for anything. But extensions can override the match() function with more helpful logic.

The BETWEEN operator

The BETWEEN operator is logically equivalent to a pair of comparisons. "x BETWEEN y AND z" is equivalent to "x>=y AND x<=z" except that with BETWEEN, the x expression is only evaluated once. The precedence of the BETWEEN operator is the same as the precedence as operators == and != and LIKE and groups left to right.

The CASE expression

A CASE expression serves a role similar to IF-THEN-ELSE in other programming languages.

The optional expression that occurs in between the CASE keyword and the first WHEN keyword is called the "base" expression. There are two basic forms of the CASE expression: those with a base expression and those without.

In a CASE without a base expression, each WHEN expression is evaluated and the result treated as a boolean, starting with the leftmost and continuing to the right. The result of the CASE expression is the evaluation of the THEN expression that corresponds to the first WHEN expression that evaluates to true. Or, if none of the WHEN expressions evaluate to true, the result of evaluating the ELSE expression, if any. If there is no ELSE expression and none of the WHEN expressions are true, then the overall result is NULL.

A NULL result is considered untrue when evaluating WHEN terms.

In a CASE with a base expression, the base expression is evaluated just once and the result is compared against the evaluation of each WHEN expression from left to right. The result of the CASE expression is the evaluation of the THEN expression that corresponds to the first WHEN expression for which the comparison is true. Or, if none of the WHEN expressions evaluate to a value equal to the base expression, the result of evaluating the ELSE expression, if any. If there is no ELSE expression and none of the WHEN expressions produce a result equal to the base expression, the overall result is NULL.

When comparing a base expression against a WHEN expression, the same collating sequence, affinity, and NULL-handling rules apply as if the base expression and WHEN expression are respectively the left- and right-hand operands of an = operator.

If the base expression is NULL then the result of the CASE is always the result of evaluating the ELSE expression if it exists, or NULL if it does not.

Both forms of the CASE expression use lazy, or short-circuit, evaluation.

The only difference between the following two CASE expressions is that the x expression is evaluated exactly once in the first example but might be evaluated multiple times in the second:

  • CASE x WHEN w1 THEN r1 WHEN w2 THEN r2 ELSE r3 END

  • CASE WHEN x=w1 THEN r1 WHEN x=w2 THEN r2 ELSE r3 END

The IN and NOT IN operators

The IN and NOT IN operators take a single scalar operand on the left and a vector operand on the right formed by an explicit list of zero or more scalars or by a single subquery. When the right operand of an IN or NOT IN operator is a subquery, the subquery must have a single result column. When the right operand is an empty set, the result of IN is false and the result of NOT IN is true, regardless of the left operand and even if the left operand is NULL. The result of an IN or NOT IN operator is determined by the following matrix:

Left operand is NULL | Right operand contains NULL | Right operand is an empty set | Left operand found within right operand | Result of IN operator | Result of NOT IN operator
no | no | no | no | false | true
does not matter | no | yes | no | false | true
no | does not matter | no | yes | true | false
no | yes | no | no | NULL | NULL
yes | does not matter | no | does not matter | NULL | NULL

Note that SQLite allows the parenthesized list of scalar values on the right-hand side of an IN or NOT IN operator to be an empty list but most other SQL database database engines and the SQL92 standard require the list to contain at least one element.

The EXISTS operator

The EXISTS operator always evaluates to one of the integer values 0 and 1. If executing the SELECT statement specified as the right-hand operand of the EXISTS operator would return one or more rows, then the EXISTS operator evaluates to 1. If executing the SELECT would return no rows at all, then the EXISTS operator evaluates to 0.

The number of columns in each row returned by the SELECT statement (if any) and the specific values returned have no effect on the results of the EXISTS operator. In particular, rows containing NULL values are not handled any differently from rows without NULL values.

Scalar Subqueries

A SELECT statement enclosed in parentheses may appear as a scalar quantity. A SELECT used as a scalar quantity must return a result set with a single column. The result of the expression is the value of the only column in the first row returned by the SELECT statement. If the SELECT yields more than one result row, all rows after the first are ignored. If the SELECT yields no rows, then the value of the expression is NULL. The LIMIT of a scalar subquery is always 1. Any other LIMIT value given in the SQL text is ignored.

All types of SELECT statement, including aggregate and compound SELECT queries (queries with keywords like UNION or EXCEPT) are allowed as scalar subqueries.

Table Column Names

A column name can be any of the names defined in the CREATE TABLE statement or one of the following special identifiers: "ROWID", "OID", or "_ROWID_". These special identifiers all describe the unique integer key (the rowid) associated with every row of every table. The special identifiers only refer to the row key if the CREATE TABLE statement does not define a real column with the same name. The rowid can be used anywhere a regular column can be used.

A SELECT statement used as either a scalar subquery or as the right-hand operand of an IN, NOT IN or EXISTS expression may contain references to columns in the outer query. Such a subquery is known as a correlated subquery. A correlated subquery is reevaluated each time its result is required. An uncorrelated subquery is evaluated only once and the result reused as necessary.

CAST expressions

A CAST expression is used to convert the value of <expr> to a different storage class in a similar way to the conversion that takes place when a column affinity is applied to a value. Application of a CAST expression is different to application of a column affinity, as with a CAST expression the storage class conversion is forced even if it is lossy and irrreversible.

If the value of <expr> is NULL, then the result of the CAST expression is also NULL. Otherwise, the storage class of the result value is determined by applying the rules for determining column affinity to the <type-name> specified as part of the CAST expression.

Affinity of <type-name> | Conversion Processing
NONE | Casting a value to a <type-name> with no affinity causes the value to be converted into a BLOB. Casting to a BLOB consists of first casting the value to TEXT in the encoding of the database connection, then interpreting the resulting byte sequence as a BLOB instead of as TEXT.
TEXT To cast a BLOB value to TEXT, the sequence of bytes that make up the BLOB is interpreted as text encoded using the database encoding.

Casting an INTEGER or REAL value into TEXT renders the value as if via sqlite3_snprintf() except that the resulting TEXT uses the encoding of the database connection.

REAL When casting a BLOB value to a REAL, the value is first converted to TEXT.

When casting a TEXT value to REAL, the longest possible prefix of the value that can be interpreted as a real number is extracted from the TEXT value and the remainder ignored. Any leading spaces in the TEXT value are ignored when converging from TEXT to REAL. If there is no prefix that can be interpreted as a real number, the result of the conversion is 0.0.

INTEGER When casting a BLOB value to INTEGER, the value is first converted to TEXT.

When casting a TEXT value to INTEGER, the longest possible prefix of the value that can be interpreted as an integer number is extracted from the TEXT value and the remainder ignored. Any leading spaces in the TEXT value when converting from TEXT to INTEGER are ignored. If there is no prefix that can be interpreted as an integer number, the result of the conversion is 0.

A cast of a REAL value into an INTEGER will truncate the fractional part of the REAL. If a REAL is too large to be represented as an INTEGER then the result of the cast is the largest negative integer: -9223372036854775808.

NUMERIC Casting a TEXT or BLOB value into NUMERIC first does a forced conversion into REAL but then further converts the result into INTEGER if and only if the conversion from REAL to INTEGER is lossless and reversible. This is the only context in SQLite where the NUMERIC and INTEGER affinities behave differently.

Casting a REAL or INTEGER value to NUMERIC is a no-op, even if a real value could be losslessly converted to an integer.

Note that the result from casting any non-BLOB value into a BLOB and the result from casting any BLOB value into a non-BLOB value may be different depending on whether the database encoding is UTF-8, UTF-16be, or UTF-16le.

Boolean Expressions

The SQL language features several contexts where an expression is evaluated and the result converted to a boolean (true or false) value. These contexts are:

  • the WHERE clause of a SELECT, UPDATE or DELETE statement,
  • the ON or USING clause of a join in a SELECT statement,
  • the HAVING clause of a SELECT statement,
  • the WHEN clause of an SQL trigger, and
  • the WHEN clause or clauses of some CASE expressions.

To convert the results of an SQL expression to a boolean value, SQLite first casts the result to a NUMERIC value in the same way as a CAST expression. A NULL or zero value (integer value 0 or real value 0.0) is considered to be false. All other values are considered true.

For example, the values NULL, 0.0, 0, 'english' and '0' are all considered to be false. Values 1, 1.0, 0.1, -0.1 and '1english' are considered to be true.

Functions

Both simple and aggregate functions are supported. (For presentation purposes, simple functions are further subdivided into core functions and date-time functions.) A simple function can be used in any expression. Simple functions return a result immediately based on their inputs. Aggregate functions may only be used in a SELECT statement. Aggregate functions compute their result across all rows of the result set.


SQLite Query Language: INDEXED BY

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

INDEXED BY

The INDEXED BY phrase is an SQL extension found only in SQLite which can be used to verify that the correct indices are being used on a DELETE, SELECT, or UPDATE statement. The INDEXED BY phrase always follows the name of a table that SQLite will be reading. The INDEXED BY phrase can be seen in the following syntax diagrams:

qualified-table-name:

syntax diagram qualified-table-name

single-source:

syntax diagram single-source

The "INDEXED BY index-name" clause specifies that the named index must be used in order to look up values on the preceding table. If index-name does not exist or cannot be used for the query, then the preparation of the SQL statement fails. The "NOT INDEXED" clause specifies that no index shall be used when accessing the preceding table, including implied indices create by UNIQUE and PRIMARY KEY constraints. However, the INTEGER PRIMARY KEY can still be used to look up entries even when "NOT INDEXED" is specified.

Some SQL database engines provide non-standard "hint" mechanisms which can be used to give the query optimizer clues about what indices it should use for a particular statement. The INDEX BY clause of SQLite is not a hinting mechanism and it should not be used as such. The INDEXED BY clause does not give the optimizer hints about which index to use; it gives the optimizer a requirement of which index to use. If the query optimizer is unable to use the index specified by the INDEX BY clause, then the query will fail with an error.

The INDEXED BY clause is not intended for use in tuning the performance of a query. The intent of the INDEXED BY clause is to raise a run-time error if a schema change, such as dropping or creating an index, causes the query plan for a time-sensitive query to change. The INDEXED BY clause is designed to help detect undesirable query plan changes during regression testing. Developers are admonished to omit all use of INDEXED BY during application design, implementation, testing, and tuning. If INDEXED BY is to be used at all, it should be inserted at the very end of the development process when "locking down" a design.

See Also:

The sqlite3_stmt_status() C/C++ interface together with the SQLITE_STMTSTATUS_FULLSCAN_STEP and SQLITE_STMTSTATUS_SORT verbs can be used to detect at run-time when an SQL statement is not making effective use of indices. Many applications may prefer to use the sqlite3_stmt_status() interface to detect index misuse rather than the INDEXED BY phrase described here.


SQLite Query Language: INSERT

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

INSERT

insert-stmt:

syntax diagram insert-stmt

The INSERT statement comes in three basic forms.

  • The first form (with the "VALUES" keyword) creates a single new row in an existing table. If no column-list is specified then the number of values must be the same as the number of columns in the table. In this case the result of evaluating the left-most expression in the VALUES list is inserted into the left-most column of the new row, and so on. If a column-list is specified, then the number of values must match the number of specified columns. Each of the named columns of the new row is populated with the results of evaluating the corresponding VALUES expression. Table columns that do not appear in the column list are populated with the default column value (specified as part of the CREATE TABLE statement), or with NULL if no default value is specified.

  • The second form of the INSERT statement contains a SELECT statement instead of a VALUES clause. A new entry is inserted into the table for each row of data returned by executing the SELECT statement. If a column-list is specified, the number of columns in the result of the SELECT must be the same as the number of items in the column-list. Otherwise, if no column-list is specified, the number of columns in the result of the SELECT must be the same as the number of columns in the table. Any SELECT statement, including compound SELECTs and SELECT statements with ORDER BY and/or LIMIT clauses, may be used in an INSERT statement of this form.

  • The third form of an INSERT statement is with DEFAULT VALUES. The INSERT ... DEFAULT VALUES statement inserts a single new row into the named table. Each column of the new row is populated with its default value, or with a NULL if no default value is specified as part of the column definition in the CREATE TABLE statement.

The optional conflict-clause allows the specification of an alternative constraint conflict resolution algorithm to use during this one INSERT command. See the section titled ON CONFLICT for additional information. For compatibility with MySQL, the parser allows the use of the single keyword REPLACE as an alias for "INSERT OR REPLACE".

The optional "database-name." prefix on the table-name is support for top-level INSERT statements only. The table name must be unqualified for INSERT statements that occur within CREATE TRIGGER statements. Similarly, the "DEFAULT VALUES" form of the INSERT statement is supported for top-level INSERT statements only and not for INSERT statements within triggers.


SQLite Query Language: SQLite Keywords

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

SQLite Keywords

The SQL standard specifies a huge number of keywords which may not be used as the names of tables, indices, columns, databases, user-defined functions, collations, virtual table modules, or any other named object. The list of keywords is so long that few people can remember them all. For most SQL code, your safest bet is to never use any English language word as the name of a user-defined object.

If you want to use a keyword as a name, you need to quote it. There are three ways of quoting keywords in SQLite:

'keyword' | A keyword in single quotes is a string literal.
"keyword" | A keyword in double-quotes is an identifier.
[keyword] | A keyword enclosed in square brackets is an identifier. This is not standard SQL. This quoting mechanism is used by MS Access and SQL Server and is included in SQLite for compatibility.
`keyword` | A keyword enclosed in grave accents (ASCII code 96) is an identifier. This is not standard SQL. This quoting mechanism is used by MySQL and is included in SQLite for compatibility.

For resilience when confronted with historical SQL statements, SQLite will sometimes bend the quoting rules above:

  • If a keyword in single quotes (ex: 'key' or 'glob') is used in a context where an identifier is allowed but where a string literal is not allowed, then the token is understood to be an identifier instead of a string literal.

  • If a keyword in double quotes (ex: "key" or "glob") is used in a context where it cannot be resolved to an identifier but where a string literal is allowed, then the token is understood to be a string literal instead of an identifier.

Programmers are cautioned not to use the two exceptions described in the previous bullets. We emphasize that they exist only so that old and ill-formed SQL statements will run correctly. Future versions of SQLite might change to raise errors instead of accepting the malformed statements covered by the exceptions above.

SQLite adds new keywords from time to time when it takes on new features. So to prevent your code from being broken by future enhancements, you should normally quote any identifier that is an English language word, even if you do not have to.

The list below shows all possible keywords used by any build of SQLite regardless of compile-time options. Most reasonable configurations use most or all of these keywords, but some keywords may be omitted when SQL language features are disabled. Regardless of the compile-time configuration, any identifier that is not on the following 121 element list is not a keyword to the SQL parser in SQLite:

ABORT
ACTION
ADD
AFTER
ALL
ALTER
ANALYZE
AND
AS
ASC
ATTACH
AUTOINCREMENT
BEFORE
BEGIN
BETWEEN
BY
CASCADE
CASE
CAST
CHECK
COLLATE
COLUMN
COMMIT
CONFLICT
CONSTRAINT
CREATE
CROSS
CURRENT_DATE
CURRENT_TIME
CURRENT_TIMESTAMP
DATABASE
DEFAULT
DEFERRABLE
DEFERRED
DELETE
DESC
DETACH
DISTINCT
DROP
EACH
ELSE
END
ESCAPE
EXCEPT
EXCLUSIVE
EXISTS
EXPLAIN
FAIL
FOR
FOREIGN
FROM
FULL
GLOB
GROUP
HAVING
IF
IGNORE
IMMEDIATE
IN
INDEX
INDEXED
INITIALLY
INNER
INSERT
INSTEAD
INTERSECT
INTO
IS
ISNULL
JOIN
KEY
LEFT
LIKE
LIMIT
MATCH
NATURAL
NO
NOT
NOTNULL
NULL
OF
OFFSET
ON
OR
ORDER
OUTER
PLAN
PRAGMA
PRIMARY
QUERY
RAISE
REFERENCES
REGEXP
REINDEX
RELEASE
RENAME
REPLACE
RESTRICT
RIGHT
ROLLBACK
ROW
SAVEPOINT
SELECT
SET
TABLE
TEMP
TEMPORARY
THEN
TO
TRANSACTION
TRIGGER
UNION
UNIQUE
UPDATE
USING
VACUUM
VALUES
VIEW
VIRTUAL
WHEN
WHERE


SQLite Query Language: Database Object Name Resolution

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

Database Object Name Resolution

In SQLite, a database object (a table, index, trigger or view) is identified by the name of the object and the name of the database that it resides in. Database objects may reside in the main database, the temp database, or in an attached database.

The syntax of the DROP TABLE, DROP INDEX, DROP VIEW, DROP TRIGGER, REINDEX, ALTER TABLE and many other commands all permit the user to specify a database object either by its name alone, or by a combination of its name and the name of its database. If no database is specified as part of the object reference, then SQLite searches the main, temp and all attached databases for an object with a matching name. The temp database is searched first, followed by the main database, followed all attached databases in the order that they were attached. The reference resolves to the first match found. For example:

      /* Add a table named 't1' to the temp, main and an attached database */
      ATTACH 'file.db' AS aux;
      CREATE TABLE t1(x, y);
      CREATE TEMP TABLE t1(x, y);
      CREATE TABLE aux.t1(x, y);

      DROP TABLE t1;         /* Drop table in temp database */
      DROP TABLE t1;         /* Drop table in main database */
      DROP TABLE t1;         /* Drop table in aux database */

If a database name is specified as part of an object reference, it must be either "main", or "temp" or the name of an attached database. Like other SQL identifiers, database names are case-insensitive. If a database name is specified, then only the named database is searched for the named object.

Most object references may only resolve to a specific type of object (for example a reference that is part of a DROP TABLE statement may only resolve to a table object, not an index, trigger or view). However in some contexts (e.g. REINDEX) an object reference may be resolve to more than one type of object. When searching database schemas for a named object, objects of types that cannot be used in the context of the reference are always ignored.


SQLite Query Language: REINDEX

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

REINDEX

reindex-stmt:

syntax diagram reindex-stmt

The REINDEX command is used to delete and recreate indices from scratch. This is useful when the definition of a collation sequence has changed.

If the REINDEX keyword is not followed by a collation-sequence or database object identifier, then all indices in all attached databases are rebuilt.

If the REINDEX keyword is followed by a collation-sequence name, then all indices in all attached databases that use the named collation sequences are recreated.

Or, if the argument attached to the REINDEX identifies a specific database table, then all indices attached to the database table are rebuilt. If it identifies a specific database index, then just that index is recreated.

If no database-name is specified and there exists both a table or index and a collation sequence of the specified name, SQLite interprets this as a request to rebuild the indices that use the named collation sequence. This ambiguity in the syntax may be avoided by always specifying a database-name when reindexing a specific table or index.


SQLite Query Language: REPLACE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

REPLACE

The REPLACE command is an alias for the "INSERT OR REPLACE" variant of the INSERT command. This alias is provided for compatibility other SQL database engines. See the INSERT command documentation for additional information.


SQLite Query Language: SAVEPOINT

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

SAVEPOINT

savepoint-stmt:

syntax diagram savepoint-stmt

release-stmt:

syntax diagram release-stmt

rollback-stmt:

syntax diagram rollback-stmt

SAVEPOINTs are a method of creating transactions, similar to BEGIN and COMMIT, except that the SAVEPOINT and RELEASE commands are named and may be nested.

The SAVEPOINT command starts a new transaction with a name. The transaction names need not be unique. A SAVEPOINT can be started either within or outside of a BEGIN...COMMIT. When a SAVEPOINT is the outer-most savepoint and it is not within a BEGIN...COMMIT then the behavior is the same as BEGIN DEFERRED TRANSACTION.

The ROLLBACK TO command reverts the state of the database back to what it was just after the corresponding SAVEPOINT. Note that unlike that plain ROLLBACK command (without the TO keyword) the ROLLBACK TO command does not cancel the transaction. Instead of cancelling the transaction, the ROLLBACK TO command restarts the transaction again at the beginning. All intervening SAVEPOINTs are canceled, however.

The RELEASE command is like a COMMIT for a SAVEPOINT. The RELEASE command causes all savepoints back to and including the most recent savepoint with a matching name to be removed from the transaction stack. The RELEASE of an inner transaction does not cause any changes to be written to the database file; it merely removes savepoints from the transaction stack such that it is no longer possible to ROLLBACK TO those savepoints. If a RELEASE command releases the outermost savepoint, so that the transaction stack becomes empty, then RELEASE is the same as COMMIT. The COMMIT command may be used to release all savepoints and commit the transaction even if the transaction was originally started by a SAVEPOINT command instead of a BEGIN command.

If the savepoint-name in a RELEASE command does not match any savepoint currently in the transaction stack, then no savepoints are released, the database is unchanged, and the RELEASE command returns an error.

Note that an inner transaction might commit (using the RELEASE command) but then later have its work undone by a ROLLBACK in an outer transaction. A power failure or program crash or OS crash will cause the outer-most transaction to rollback, undoing all changes that have occurred within that outer transaction, even changes that have supposedly been "committed" by the RELEASE command. Content is not actually committed on the disk until the outermost transaction commits.

There are several ways of thinking about the RELEASE command:

  • Some people view RELEASE as the equivalent of COMMIT for a SAVEPOINT. This is an acceptable point of view as long as one remembers that the changes committed by an inner transaction might later be undone by a rollback in an outer transaction.

  • Another view of RELEASE is that it merges a named transaction into its parent transaction, so that the named transaction and its parent become the same transaction. After RELEASE, the named transaction and its parent will commit or rollback together, whatever their fate may be.

  • One can also think of savepoints as "marks" in the transaction timeline. In this view, the SAVEPOINT command creates a new mark, the ROLLBACK TO command rewinds the timeline back to a point just after the named mark, and the RELEASE command erases marks from the timeline without actually making any changes to the database.

Transaction Nesting Rules

The last transaction started will be the first transaction committed or rolled back.

The BEGIN command only works if the transaction stack is empty, or in other words if there are no pending transactions. If the transaction stack is not empty when the BEGIN command is invoked, then the command fails with an error.

The COMMIT command commits all outstanding transactions and leaves the transaction stack empty.

The RELEASE command starts with the most recent addition to the transaction stack and releases savepoints backwards in time until it releases a savepoint with a matching savepoint-name. Prior savepoints, even savepoints with matching savepoint-names, are unchanged. If the RELEASE command causes the transaction stack to become empty (if the RELEASE command releases the outermost transaction from the stack) then the transaction commits.

The ROLLBACK command without a TO clause rolls backs all transactions and leaves the transaction stack empty.

The ROLLBACK command with a TO clause rolls back transactions going backwards in time back to the most recent SAVEPOINT with a matching name. The SAVEPOINT with the matching name remains on the transaction stack, but all database changes that occurred after that SAVEPOINT was created are rolled back. If the savepoint-name in a ROLLBACK TO command does not match any SAVEPOINT on the stack, then the ROLLBACK command fails with an error and leaves the state of the database unchanged.


SQLite Query Language: SELECT

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

SELECT

select-stmt:

syntax diagram select-stmt

select-core:

syntax diagram select-core

result-column:

syntax diagram result-column

join-source:

syntax diagram join-source

single-source:

syntax diagram single-source

join-op:

syntax diagram join-op

join-constraint:

syntax diagram join-constraint

ordering-term:

syntax diagram ordering-term

compound-operator:

syntax diagram compound-operator

The SELECT statement is used to query the database. The result of a SELECT is zero or more rows of data where each row has a fixed number of columns.

The SELECT statement is the most complicated command in the SQL language. To make the description easier to follow, some of the passages below describe the way the data returned by a SELECT statement is determined as a series of steps. It is important to keep in mind that this is purely illustrative - in practice neither SQLite nor any other SQL engine is required to follow this or any other specific process.

Simple Select Processing

The syntax for a simple SELECT statement is depicted in the select-core syntax diagram. Generating the results of a simple SELECT statement is presented as a four step process in the description below:

  1. FROM clause processing: The input data for the simple SELECT is determined. The input data is either implicitly a single row with 0 columns (if there is no FROM clause) or is determined by analyzing the join-source specification that follows an explicit FROM clause.

  2. WHERE clause processing: The input data is filtered using the WHERE clause expression.

  3. GROUP BY, HAVING and result-column expression processing: The set of result rows is computed by aggregating the data according to any GROUP BY clause and calculating the result-set expressions for the rows of the filtered input dataset.

  4. DISTINCT/ALL keyword processing: If the query is a "SELECT DISTINCT" query, duplicate rows are removed from the set of result rows.

There are two types of simple SELECT statement - aggregate and non-aggregate queries. A simple SELECT statement is an aggregate query if it contains either a GROUP BY clause or one or more aggregate functions in the result-set. Otherwise, if a simple SELECT contains no aggregate functions or a GROUP BY clause, it is a non-aggregate query.

1. Determination of input data (FROM clause processing).

The input data used by a simple SELECT query is a set of N rows each M columns wide.

If the FROM clause is omitted from a simple SELECT statement, then the input data is implicitly a single row zero columns wide (i.e. N=1 and M=0).

If a FROM clause is specified, the data on which a simple SELECT query operates comes from the one or more tables or subqueries (SELECT statements in parenthesis) specified following the FROM keyword. A sub-select specified in the join-source following the FROM clause in a simple SELECT statement is handled as if it was a table containing the data returned by executing the sub-select statement. Each column of the sub-select dataset inherits the collation sequence and affinity of the corresponding expression in the sub-select statement.

If there is only a single table in the join-source following the FROM clause, then the input data used by the SELECT statement is the contents of the named table. If there is more than one table specified as part of the join-source following the FROM keyword, then the contents of each named table are joined into a single dataset for the simple SELECT statement to operate on. Exactly how the data is combined depends on the specific join-op and join-constraint used to connect the tables or subqueries together.

All joins in SQLite are based on the cartesian product of the left and right-hand datasets. The columns of the cartesian product dataset are, in order, all the columns of the left-hand dataset followed by all the columns of the right-hand dataset. There is a row in the cartesian product dataset formed by combining each unique combination of a row from the left-hand and right-hand datasets. In other words, if the left-hand dataset consists of Nlhs rows of Mlhs columns, and the right-hand dataset of Nrhs rows of Mrhs columns, then the cartesian product is a dataset of Nlhs.Nrhs rows, each containing Mlhs+Mrhs columns.

If the join-op is "CROSS JOIN", "INNER JOIN", "JOIN" or a comma (",") and there is no ON or USING clause, then the result of the join is simply the cartesian product of the left and right-hand datasets. There is no difference between the "INNER JOIN", "JOIN" and "," join operators. The "CROSS JOIN" join operator produces the same data as the "INNER JOIN", "JOIN" and "," operators, but is handled slightly differently by the query optimizer. Otherwise, it is the cartesian product modified according to one or more of the following bullet points:

  • If there is an ON clause specified, then the ON expression is evaluated for each row of the cartesian product as a boolean expression. All rows for which the expression evaluates to false are excluded from the dataset.

  • If there is a USING clause specified as part of the join-constraint, then each of the column names specified must exist in the datasets to both the left and right of the join-op. For each pair of namesake columns, the expression "lhs.X = rhs.X" is evaluated for each row of the cartesian product as a boolean expression. All rows for which one or more of the expressions evaluates to false are excluded from the result set. When comparing values as a result of a USING clause, the normal rules for handling affinities, collation sequences and NULL values in comparisons apply. The column from the dataset on the left-hand side of the join operator is considered to be on the left-hand side of the comparison operator (=) for the purposes of collation sequence and affinity precedence.

    For each pair of columns identified by a USING clause, the column from the right-hand dataset is omitted from the joined dataset. This is the only difference between a USING clause and its equivalent ON constraint.

  • If the NATURAL keyword is added to any of the join-ops, then an implicit USING clause is added to the join-constraints. The implicit USING clause contains each of the column names that appear in both the left and right-hand input datasets. If the left and right-hand input datasets feature no common column names, then the NATURAL keyword has no effect on the results of the join. A USING or ON clause may not be added to a join that specifies the NATURAL keyword.

  • If the join-op is a "LEFT JOIN" or "LEFT OUTER JOIN", then after the ON or USING filtering clauses have been applied, an extra row is added to the output for each row in the original left-hand input dataset that corresponds to no rows at all in the composite dataset (if any). The added rows contain NULL values in the columns that would normally contain values copied from the right-hand input dataset.

When more than two tables are joined together as part of a FROM clause, the join operations are processed in order from left to right. In other words, the FROM clause (A join-op-1 B join-op-2 C) is computed as ((A join-op-1 B) join-op-2 C).

2. WHERE clause filtering.

If a WHERE clause is specified, the WHERE expression is evaluated for each row in the input data as a boolean expression. All rows for which the WHERE clause expression evaluates to false are excluded from the dataset before continuing.

3. Generation of the set of result rows.

Once the input data from the FROM clause has been filtered by the WHERE clause expression (if any), the set of result rows for the simple SELECT are calculated. Exactly how this is done depends on whether the simple SELECT is an aggregate or non-aggregate query, and whether or not a GROUP BY clause was specified.

The list of expressions between the SELECT and FROM keywords is known as the result expression list. If a result expression is the special expression "*" then all columns in the input data are substituted for that one expression. If the expression is the alias of a table or subquery in the FROM clause followed by ".*" then all columns from the named table or subquery are substituted for the single expression. It is an error to use a "*" or "alias.*" expression in any context other than than a result expression list. It is also an error to use a "*" or "alias.*" expression in a simple SELECT query that does not have a FROM clause.

The number of columns in the rows returned by a simple SELECT statement is equal to the number of expressions in the result expression list after substitution of * and alias.* expressions. Each result row is calculated by evaluating the expressions in the result expression list with respect to a single row of input data or, for aggregate queries, with respect to a group of rows.

  • If the SELECT statement is a non-aggregate query, then each expression in the result expression list is evaluated for each row in the dataset filtered by the WHERE clause.

  • If the SELECT statement is an aggregate query without a GROUP BY clause, then each aggregate expression in the result-set is evaluated once across the entire dataset. Each non-aggregate expression in the result-set is evaluated once for an arbitrarily selected row of the dataset. The same arbitrarily selected row is used for each non-aggregate expression. Or, if the dataset contains zero rows, then each non-aggregate expression is evaluated against a row consisting entirely of NULL values.

    The single row of result-set data created by evaluating the aggregate and non-aggregate expressions in the result-set forms the result of an aggregate query without a GROUP BY clause. An aggregate query without a GROUP BY clause always returns exactly one row of data, even if there are zero rows of input data.

  • If the SELECT statement is an aggregate query with a GROUP BY clause, then each of the expressions specified as part of the GROUP BY clause is evaluated for each row of the dataset. Each row is then assigned to a "group" based on the results; rows for which the results of evaluating the GROUP BY expressions are the same are assigned to the same group. For the purposes of grouping rows, NULL values are considered equal. The usual rules for selecting a collation sequence with which to compare text values apply when evaluating expressions in a GROUP BY clause. The expressions in the GROUP BY clause do not have to be expressions that appear in the result. The expressions in a GROUP BY clause may not be aggregate expressions.

    If a HAVING clause is specified, it is evaluated once for each group of rows as a boolean expression. If the result of evaluating the HAVING clause is false, the group is discarded. If the HAVING clause is an aggregate expression, it is evaluated across all rows in the group. If a HAVING clause is a non-aggregate expression, it is evaluated with respect to an arbitrarily selected row from the group. The HAVING expression may refer to values, even aggregate functions, that are not in the result.

    Each expression in the result-set is then evaluated once for each group of rows. If the expression is an aggregate expression, it is evaluated across all rows in the group. Otherwise, it is evaluated against a single arbitrarily chosen row from within the group. If there is more than one non-aggregate expression in the result-set, then all such expressions are evaluated for the same row.

    Each group of input dataset rows contributes a single row to the set of result rows. Subject to filtering associated with the DISTINCT keyword, the number of rows returned by an aggregate query with a GROUP BY clause is the same as the number of groups of rows produced by applying the GROUP BY and HAVING clauses to the filtered input dataset.

4. Removal of duplicate rows (DISTINCT processing).

One of the ALL or DISTINCT keywords may follow the SELECT keyword in a simple SELECT statement. If the simple SELECT is a SELECT ALL, then the entire set of result rows are returned by the SELECT. If neither ALL or DISTINCT are present, then the behaviour is as if ALL were specified. If the simple SELECT is a SELECT DISTINCT, then duplicate rows are removed from the set of result rows before it is returned. For the purposes of detecting duplicate rows, two NULL values are considered to be equal. The normal rules for selecting a collation sequence to compare text values with apply.

Compound Select Statements

Two or more simple SELECT statements may be connected together to form a compound SELECT using the UNION, UNION ALL, INTERSECT or EXCEPT operator. In a compound SELECT, all the constituent SELECTs must return the same number of result columns. As the components of a compound SELECT must be simple SELECT statements, they may not contain ORDER BY or LIMIT clauses. ORDER BY and LIMIT clauses may only occur at the end of the entire compound SELECT.

A compound SELECT created using UNION ALL operator returns all the rows from the SELECT to the left of the UNION ALL operator, and all the rows from the SELECT to the right of it. The UNION operator works the same way as UNION ALL, except that duplicate rows are removed from the final result set. The INTERSECT operator returns the intersection of the results of the left and right SELECTs. The EXCEPT operator returns the subset of rows returned by the left SELECT that are not also returned by the right-hand SELECT. Duplicate rows are removed from the results of INTERSECT and EXCEPT operators before the result set is returned.

For the purposes of determining duplicate rows for the results of compound SELECT operators, NULL values are considered equal to other NULL values and distinct from all non-NULL values. The collation sequence used to compare two text values is determined as if the columns of the left and right-hand SELECT statements were the left and right-hand operands of the equals (=) operator, except that greater precedence is not assigned to a collation sequence specified with the postfix COLLATE operator. No affinity transformations are applied to any values when comparing rows as part of a compound SELECT.

When three or more simple SELECTs are connected into a compound SELECT, they group from left to right. In other words, if "A", "B" and "C" are all simple SELECT statements, (A op B op C) is processed as ((A op B) op C).

ORDER BY and LIMIT/OFFSET Clauses

If a SELECT statement that returns more than one row does not have an ORDER BY clause, the order in which the rows are returned is undefined. Or, if a SELECT statement does have an ORDER BY clause, then the list of expressions attached to the ORDER BY determine the order in which rows are returned to the user. Rows are first sorted based on the results of evaluating the left-most expression in the ORDER BY list, then ties are broken by evaluating the second left-most expression and so on. The order in which two rows for which all ORDER BY expressions evaluate to equal values are returned is undefined. Each ORDER BY expression may be optionally followed by one of the keywords ASC (smaller values are returned first) or DESC (larger values are returned first). If neither ASC or DESC are specified, rows are sorted in ascending (smaller values first) order by default.

Each ORDER BY expression is processed as follows:

  1. If the ORDER BY expression is a constant integer K then the expression is considered an alias for the K-th column of the result set (columns are numbered from left to right starting with 1).

  2. If the ORDER BY expression is an identifier that corresponds to the alias of one of the output columns, then the expression is considered an alias for that column.

  3. Otherwise, if the ORDER BY expression is any other expression, it is evaluated and the returned value used to order the output rows. If the SELECT statement is a simple SELECT, then an ORDER BY may contain any arbitrary expressions. However, if the SELECT is a compound SELECT, then ORDER BY expressions that are not aliases to output columns must be exactly the same as an expression used as an output column.

For the purposes of sorting rows, values are compared in the same way as for comparison expressions. The collation sequence used to compare two text values is determined as follows:

  1. If the ORDER BY expression is assigned a collation sequence using the postfix COLLATE operator, then the specified collation sequence is used.

  2. Otherwise, if the ORDER BY expression is an alias to an expression that has been assigned a collation sequence using the postfix COLLATE operator, then the collation sequence assigned to the aliased expression is used.

  3. Otherwise, if the ORDER BY expression is a column or an alias of an expression that is a column, then the default collation sequence for the column is used.

  4. Otherwise, the BINARY collation sequence is used.

In a compound SELECT statement, all ORDER BY expressions are handled as aliases for one of the result columns of the compound SELECT. If an ORDER BY expression is not an integer alias, then SQLite searches the left-most SELECT in the compound for a result column that matches either the second or third rules above. If a match is found, the search stops and the expression is handled as an alias for the result column that it has been matched against. Otherwise, the next SELECT to the right is tried, and so on. If no matching expression can be found in the result columns of any constituent SELECT, it is an error. Each term of the ORDER BY clause is processed separately and may be matched against result columns from different SELECT statements in the compound.

The LIMIT clause is used to place an upper bound on the number of rows returned by a SELECT statement. Any scalar expression may be used in the LIMIT clause, so long as it evaluates to an integer or a value that can be losslessly converted to an integer. If the expression evaluates to a NULL value or any other value that cannot be losslessly converted to an integer, an error is returned. If the LIMIT expression evaluates to a negative value, then there is no upper bound on the number of rows returned. Otherwise, the SELECT returns the first N rows of its result set only, where N is the value that the LIMIT expression evaluates to. Or, if the SELECT statement would return less than N rows without a LIMIT clause, then the entire result set is returned.

The expression attached to the optional OFFSET clause that may follow a LIMIT clause must also evaluate to an integer, or a value that can be losslessly converted to an integer. If an expression has an OFFSET clause, then the first M rows are omitted from the result set returned by the SELECT statement and the next N rows are returned, where M and N are the values that the OFFSET and LIMIT clauses evaluate to, respectively. Or, if the SELECT would return less than M+N rows if it did not have a LIMIT clause, then the first M rows are skipped and the remaining rows (if any) are returned. If the OFFSET clause evaluates to a negative value, the results are the same as if it had evaluated to zero.

Instead of a separate OFFSET clause, the LIMIT clause may specify two scalar expressions separated by a comma. In this case, the first expression is used as the OFFSET expression and the second as the LIMIT expression. This is counter-intuitive, as when using the OFFSET clause the second of the two expressions is the OFFSET and the first the LIMIT. This is intentional - it maximizes compatibility with other SQL database systems.


SQLite Query Language: BEGIN TRANSACTION

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

BEGIN TRANSACTION

begin-stmt:

syntax diagram begin-stmt

commit-stmt:

syntax diagram commit-stmt

rollback-stmt:

syntax diagram rollback-stmt

No changes can be made to the database except within a transaction. Any command that changes the database (basically, any SQL command other than SELECT) will automatically start a transaction if one is not already in effect. Automatically started transactions are committed when the last query finishes.

Transactions can be started manually using the BEGIN command. Such transactions usually persist until the next COMMIT or ROLLBACK command. But a transaction will also ROLLBACK if the database is closed or if an error occurs and the ROLLBACK conflict resolution algorithm is specified. See the documentation on the ON CONFLICT clause for additional information about the ROLLBACK conflict resolution algorithm.

END TRANSACTION is an alias for COMMIT.

Transactions created using BEGIN...COMMIT do not nest. For nested transactions, use the SAVEPOINT and RELEASE commands. The "TO SAVEPOINT name" clause of the ROLLBACK command shown in the syntax diagram above is only applicable to SAVEPOINT transactions. An attempt to invoke the BEGIN command within a transaction will fail with an error, regardless of whether the transaction was started by SAVEPOINT or a prior BEGIN. The COMMIT command and the ROLLBACK command without the TO clause work the same on SAVEPOINT transactions as they do with transactions started by BEGIN.

Transactions can be deferred, immediate, or exclusive. The default transaction behavior is deferred. Deferred means that no locks are acquired on the database until the database is first accessed. Thus with a deferred transaction, the BEGIN statement itself does nothing to the filesystem. Locks are not acquired until the first read or write operation. The first read operation against a database creates a SHARED lock and the first write operation creates a RESERVED lock. Because the acquisition of locks is deferred until they are needed, it is possible that another thread or process could create a separate transaction and write to the database after the BEGIN on the current thread has executed. If the transaction is immediate, then RESERVED locks are acquired on all databases as soon as the BEGIN command is executed, without waiting for the database to be used. After a BEGIN IMMEDIATE, no other database connection will be able to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue to read from the database, however. An exclusive transaction causes EXCLUSIVE locks to be acquired on all databases. After a BEGIN EXCLUSIVE, no other database connection except for read_uncommitted connections will be able to read the database and no other connection without exception will be able to write the database until the transaction is complete.

An implicit transaction (a transaction that is started automatically, not a transaction started by BEGIN) is committed automatically when the last active statement finishes. A statement finishes when its prepared statement is reset or finalized. An open sqlite3_blob used for incremental BLOB I/O counts as an unfinished statement. The sqlite3_blob finishes when it is closed.

The explicit COMMIT command runs immediately, even if there are pending SELECT statements. However, if there are pending write operations, the COMMIT command will fail with an error code SQLITE_BUSY.

An attempt to execute COMMIT might also result in an SQLITE_BUSY return code if an another thread or process has a shared lock on the database that prevented the database from being updated. When COMMIT fails in this way, the transaction remains active and the COMMIT can be retried later after the reader has had a chance to clear.

The ROLLBACK will fail with an error code SQLITE_BUSY if there are any pending queries. Both read-only and read/write queries will cause a ROLLBACK to fail. A ROLLBACK must fail if there are pending read operations (unlike COMMIT which can succeed) because bad things will happen if the in-memory image of the database is changed out from under an active query.

If PRAGMA journal_mode is set to OFF (thus disabling the rollback journal file) then the behavior of the ROLLBACK command is undefined.

Response To Errors Within A Transaction

If certain kinds of errors occur within a transaction, the transaction may or may not be rolled back automatically. The errors that cause the behavior include:

  • SQLITE_FULL: database or disk full
  • SQLITE_IOERR: disk I/O error
  • SQLITE_BUSY: database in use by another process
  • SQLITE_NOMEM: out or memory
  • SQLITE_INTERRUPT: processing interrupted by application request

For all of these errors, SQLite attempts to undo just the one statement it was working on and leave changes from prior statements within the same transaction intact and continue with the transaction. However, depending on the statement being evaluated and the point at which the error occurs, it might be necessary for SQLite to rollback and cancel the entire transaction. An application can tell which course of action SQLite took by using the sqlite3_get_autocommit() C-language interface.

It is recommended that applications respond to the errors listed above by explicitly issuing a ROLLBACK command. If the transaction has already been rolled back automatically by the error response, then the ROLLBACK command will fail with an error, but no harm is caused by this.

Future versions of SQLite may extend the list of errors which might cause automatic transaction rollback. Future versions of SQLite might change the error response. In particular, we may choose to simplify the interface in future versions of SQLite by causing the errors above to force an unconditional rollback.


SQLite Query Language: UPDATE

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

UPDATE

update-stmt:

syntax diagram update-stmt

qualified-table-name:

syntax diagram qualified-table-name

An UPDATE statement is used to modify a subset of the values stored in zero or more rows of the database table identified by the qualified-table-name specified as part of the UPDATE statement.

If the UPDATE statement does not have a WHERE clause, all rows in the table are modified by the UPDATE. Otherwise, the UPDATE affects only those rows for which the result of evaluating the WHERE clause expression as a boolean expression is true. It is not an error if the WHERE clause does not evaluate to true for any row in the table - this just means that the UPDATE statement affects zero rows.

The modifications made to each row affected by an UPDATE statement are determined by the list of assignments following the SET keyword. Each assignment specifies a column name to the left of the equals sign and a scalar expression to the right. For each affected row, the named columns are set to the values found by evaluating the corresponding scalar expressions. If a single column-name appears more than once in the list of assignment expressions, all but the rightmost occurrence is ignored. Columns that do not appear in the list of assignments are left unmodified. The scalar expressions may refer to columns of the row being updated. In this case all scalar expressions are evaluated before any assignments are made.

The optional conflict-clause allows the user to nominate a specific constraint conflict resolution algorithm to use during this one UPDATE command. Refer to the section entitled ON CONFLICT for additional information.

Restrictions on UPDATE Statements Within CREATE TRIGGER

The following additional syntax restrictions apply to UPDATE statements that occur within the body of a CREATE TRIGGER statement.

  • The table-name specified as part of an UPDATE statement within a trigger body must be unqualified. In other words, the database-name. prefix on the table name of the UPDATE is not allowed within triggers. Unless the table to which the trigger is attached is in the TEMP database, the table being updated by the trigger program must reside in the same database as it. If the table to which the trigger is attached is in the TEMP database, then the unqualified name of the table being updated is resolved in the same way as it is for a top-level statement (by searching first the TEMP database, then the main database, then any other databases in the order they were attached).

  • The INDEXED BY and NOT INDEXED clauses are not allowed on UPDATE statements within triggers.

  • The LIMIT and ORDER BY clauses for UPDATE are unsupported within triggers, regardless of the compilation options used to build SQLite.

Optional LIMIT and ORDER BY Clauses

If SQLite is built with the SQLITE_ENABLE_UPDATE_DELETE_LIMIT compile-time option then the syntax of the UPDATE statement is extended with optional ORDER BY and LIMIT clauses as follows:

update-stmt-limited:

syntax diagram update-stmt-limited

If an UPDATE statement has a LIMIT clause, the maximum number of rows that will be updated is found by evaluating the accompanying expression and casting it to an integer value. A negative value is interpreted as "no limit".

If the LIMIT expression evaluates to non-negative value N and the UPDATE statement has an ORDER BY clause, then all rows that would be updated in the absence of the LIMIT clause are sorted according to the ORDER BY and the first N updated. If the UPDATE statement also has an OFFSET clause, then it is similarly evaluated and cast to an integer value. If the OFFSET expression evaluates to a non-negative value M, then the first M rows are skipped and the following N rows updated instead.

If the UPDATE statement has no ORDER BY clause, then all rows that would be updated in the absence of the LIMIT clause are assembled in an arbitrary order before applying the LIMIT and OFFSET clauses to determine which are actually updated.

The ORDER BY clause on an UPDATE statement is used only to determine which rows fall within the LIMIT. The order in which rows are modified is arbitrary and is not influenced by the ORDER BY clause.


SQLite Query Language: VACUUM

Choose any three.
About Sitemap Documentation Download License News Support

SQL As Understood By SQLite

[Top]

VACUUM

vacuum-stmt:

syntax diagram vacuum-stmt

The VACUUM command rebuilds the entire database. There are several reasons an application might do this:

  • Unless SQLite is running in "auto_vacuum=FULL" mode, when a large amount of data is deleted from the database file it leaves behind empty space, or "free" database pages. This means the database file might be larger than strictly necessary. Running VACUUM to rebuild the database reclaims this space and reduces the size of the database file.

  • Frequent inserts, updates, and deletes can cause the database file to become fragmented - where data for a single table or index is scattered around the database file. Running VACUUM ensures that each table and index is largely stored contiguously within the database file. In some cases, VACUUM may also reduce the number of partially filled pages in the database, reducing the size of the database file further.

  • Normally, the database page_size and whether or not the database supports auto_vacuum must be configured before the database file is actually created. However, when not in write-ahead log mode, the page_size and/or auto_vacuum properties of an existing database may be changed by using the page_size and/or pragma auto_vacuum pragmas and then immediately VACUUMing the database. When in write-ahead log mode, only the auto_vacuum support property can be changed using VACUUM.

VACUUM only works on the main database. It is not possible to VACUUM an attached database file.

The VACUUM command works by copying the contents of the database into a temporary database file and then overwriting the original with the contents of the temporary file. When overwriting the original, a rollback journal or write-ahead log WAL file is used just as it would be for any other database transaction. This means that when VACUUMing a database, as much as twice the size of the original database file is required in free disk space.

The VACUUM command may change the ROWIDs of entries in any tables that do not have an explicit INTEGER PRIMARY KEY.

A VACUUM will fail if there is an open transaction, or if there are one or more active SQL statements when it is run.

As of SQLite version 3.1, an alternative to using the VACUUM command to reclaim space after data has been deleted is auto-vacuum mode, enabled using the auto_vacuum pragma. When auto_vacuum is enabled for a database free pages may be reclaimed after deleting data, causing the file to shrink, without rebuilding the entire database using VACUUM. However, using auto_vacuum can lead to extra database file fragmentation. And auto_vacuum does not compact partially filled pages of the database as VACUUM does.


Implementation Limits For SQLite

Choose any three.
About Sitemap Documentation Download License News Support

Limits In SQLite

"Limits" in the context of this article means sizes or quantities that can not be exceeded. We are concerned with things like the maximum number of bytes in a BLOB or the maximum number of columns in a table.

SQLite was originally designed with a policy of avoiding arbitrary limits. Of course, every program that runs on a machine with finite memory and disk space has limits of some kind. But in SQLite, those limits were not well defined. The policy was that if it would fit in memory and you could count it with a 32-bit integer, then it should work.

Unfortunately, the no-limits policy has been shown to create problems. Because the upper bounds were not well defined, they were not tested, and bugs (including possible security exploits) were often found when pushing SQLite to extremes. For this reason, newer versions of SQLite have well-defined limits and those limits are tested as part of the test suite.

This article defines what the limits of SQLite are and how they can be customized for specific applications. The default settings for limits are normally quite large and adequate for almost every application. Some applications may want to increase a limit here or there, but we expect such needs to be rare. More commonly, an application might want to recompile SQLite with much lower limits to avoid excess resource utilization in the event of bug in higher-level SQL statement generators or to help thwart attackers who inject malicious SQL statements.

Some limits can be changed at run-time on a per-connection basis using the sqlite3_limit() interface with one of the limit categories defined for that interface. Run-time limits are designed for applications that have multiple databases, some of which are for internal use only and others which can be influenced or controlled by potentially hostile external agents. For example, a web browser application might use an internal database to track historical page views but have one or more separate databases that are created and controlled by javascript applications that are downloaded from the internet. The sqlite3_limit() interface allows internal databases managed by trusted code to be unconstrained while simultaneously placing tight limitations on databases created or controlled by untrusted external code in order to help prevent a denial of service attack.

  1. Maximum length of a string or BLOB

    The maximum number of bytes in a string or BLOB in SQLite is defined by the preprocessor macro SQLITE_MAX_LENGTH. The default value of this macro is 1 billion (1 thousand million or 1,000,000,000). You can raise or lower this value at compile-time using a command-line option like this:

    -DSQLITE_MAX_LENGTH=123456789

    The current implementation will only support a string or BLOB length up to 231-1 or 2147483647. And some built-in functions such as hex() might fail well before that point. In security-sensitive applications it is best not to try to increase the maximum string and blob length. In fact, you might do well to lower the maximum string and blob length to something more in the range of a few million if that is possible.

    During part of SQLite's INSERT and SELECT processing, the complete content of each row in the database is encoded as a single BLOB. So the SQLITE_MAX_LENGTH parameter also determines the maximum number of bytes in a row.

    The maximum string or BLOB length can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_LENGTH,size) interface.

  2. Maximum Number Of Columns

    The SQLITE_MAX_COLUMN compile-time parameter is used to set an upper bound on:

    • The number of columns in a table
    • The number of columns in an index
    • The number of columns in a view
    • The number of terms in the SET clause of an UPDATE statement
    • The number of columns in the result set of a SELECT statement
    • The number of terms in a GROUP BY or ORDER BY clause
    • The number of values in an INSERT statement

    The default setting for SQLITE_MAX_COLUMN is 2000. You can change it at compile time to values as large as 32767. On the other hand, many experienced database designers will argue that a well-normalized database will never need more than 100 columns in a table.

    In most applications, the number of columns is small - a few dozen. There are places in the SQLite code generator that use algorithms that are O(N²) where N is the number of columns. So if you redefine SQLITE_MAX_COLUMN to be a really huge number and you generate SQL that uses a large number of columns, you may find that sqlite3_prepare_v2() runs slowly.

    The maximum number of columns can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_COLUMN,size) interface.

  3. Maximum Length Of An SQL Statement

    The maximum number of bytes in the text of an SQL statement is limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000. You can redefine this limit to be as large as the smaller of SQLITE_MAX_LENGTH and 1073741824.

    If an SQL statement is limited to be a million bytes in length, then obviously you will not be able to insert multi-million byte strings by embedding them as literals inside of INSERT statements. But you should not do that anyway. Use host parameters for your data. Prepare short SQL statements like this:

    INSERT INTO tab1 VALUES(?,?,?);

    Then use the sqlite3_bind_XXXX() functions to bind your large string values to the SQL statement. The use of binding obviates the need to escape quote characters in the string, reducing the risk of SQL injection attacks. It is also runs faster since the large string does not need to be parsed or copied as much.

    The maximum length of an SQL statement can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_SQL_LENGTH,size) interface.

  4. Maximum Number Of Tables In A Join

    SQLite does not support joins containing more than 64 tables. This limit arises from the fact that the SQLite code generator uses bitmaps with one bit per join-table in the query optimizer.

    SQLite uses a very efficient O(N²) greedy algorithm for determining the order of tables in a join and so a large join can be prepared quickly. Hence, there is no mechanism to raise or lower the limit on the number of tables in a join.

  5. Maximum Depth Of An Expression Tree

    SQLite parses expressions into a tree for processing. During code generation, SQLite walks this tree recursively. The depth of expression trees is therefore limited in order to avoid using too much stack space.

    The SQLITE_MAX_EXPR_DEPTH parameter determines the maximum expression tree depth. If the value is 0, then no limit is enforced. The current implementation has a default value of 1000.

    The maximum depth of an expression tree can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_EXPR_DEPTH,size) interface if the SQLITE_MAX_EXPR_DEPTH is initially positive. In other words, the maximum expression depth can be lowered at run-time if there is already a compile-time limit on the expression depth. If SQLITE_MAX_EXPR_DEPTH is set to 0 at compile time (if the depth of expressions is unlimited) then the sqlite3_limit(db,SQLITE_LIMIT_EXPR_DEPTH,size) is a no-op.

  6. Maximum Number Of Arguments On A Function

    The SQLITE_MAX_FUNCTION_ARG parameter determines the maximum number of parameters that can be passed to an SQL function. The default value of this limit is 100. SQLite should work with functions that have thousands of parameters. However, we suspect that anybody who tries to invoke a function with more than a few parameters is really trying to find security exploits in systems that use SQLite, not do useful work, and so for that reason we have set this parameter relatively low.

    The number of arguments to a function is sometimes stored in a signed character. So there is a hard upper bound on SQLITE_MAX_FUNCTION_ARG of 127.

    The maximum number of arguments in a function can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_FUNCTION_ARG,size) interface.

  7. Maximum Number Of Terms In A Compound SELECT Statement

    A compound SELECT statement is two or more SELECT statements connected by operators UNION, UNION ALL, EXCEPT, or INTERSECT. We call each individual SELECT statement within a compound SELECT a "term".

    The code generator in SQLite processes compound SELECT statements using a recursive algorithm. In order to limit the size of the stack, we therefore limit the number of terms in a compound SELECT. The maximum number of terms is SQLITE_MAX_COMPOUND_SELECT which defaults to 500. We think this is a generous allotment since in practice we almost never see the number of terms in a compound select exceed single digits.

    The maximum number of compound SELECT terms can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_COMPOUND_SELECT,size) interface.

  8. Maximum Length Of A LIKE Or GLOB Pattern

    The pattern matching algorithm used in the default LIKE and GLOB implementation of SQLite can exhibit O(N²) performance (where N is the number of characters in the pattern) for certain pathological cases. To avoid denial-of-service attacks from miscreants who are able to specify their own LIKE or GLOB patterns, the length of the LIKE or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes. The default value of this limit is 50000. A modern workstation can evaluate even a pathological LIKE or GLOB pattern of 50000 bytes relatively quickly. The denial of service problem only comes into play when the pattern length gets into millions of bytes. Nevertheless, since most useful LIKE or GLOB patterns are at most a few dozen bytes in length, paranoid application developers may want to reduce this parameter to something in the range of a few hundred if they know that external users are able to generate arbitrary patterns.

    The maximum length of a LIKE or GLOB pattern can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_LIKE_PATTERN_LENGTH,size) interface.

  9. Maximum Number Of Host Parameters In A Single SQL Statement

    A host parameter is a place-holder in an SQL statement that is filled in using one of the sqlite3_bind_XXXX() interfaces. Many SQL programmers are familiar with using a question mark ("?") as a host parameter. SQLite also supports named host parameters prefaced by ":", "$", or "@" and numbered host parameters of the form "?123".

    Each host parameter in an SQLite statement is assigned a number. The numbers normally begin with 1 and increase by one with each new parameter. However, when the "?123" form is used, the host parameter number is the number that follows the question mark.

    SQLite allocates space to hold all host parameters between 1 and the largest host parameter number used. Hence, an SQL statement that contains a host parameter like ?1000000000 would require gigabytes of storage. This could easily overwhelm the resources of the host machine. To prevent excessive memory allocations, the maximum value of a host parameter number is SQLITE_MAX_VARIABLE_NUMBER, which defaults to 999.

    The maximum host parameter number can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_VARIABLE_NUMBER,size) interface.

  10. Maximum Depth Of Trigger Recursion

    SQLite limits the depth of recursion of triggers in order to prevent a statement involving recursive triggers from using an unbounded amount of memory.

    Prior to SQLite version 3.6.18, triggers were not recursive and so this limit was meaningless. Beginning with version 3.6.18, recursive triggers were supported but had to be explicitly enabled using the PRAGMA recursive_triggers statement. Beginning with version 3.7.0, recursive triggers are enabled by default but can be manually disabled using PRAGMA recursive_triggers. The SQLITE_MAX_TRIGGER_DEPTH is only meaningful if recursive triggers are enabled.

    The default maximum trigger recursion depth is 1000.

  11. Maximum Number Of Attached Databases

    The ATTACH statement is an SQLite extension that allows two or more databases to be associated to the same database connection and to operate as if they were a single database. The number of simultaneously attached databases is limited to SQLITE_MAX_ATTACHED which is set to 10 by default. The code generator in SQLite uses bitmaps to keep track of attached databases. That means that the number of attached databases cannot be increased above 62.

    The maximum number of attached databases can be lowered at run-time using the sqlite3_limit(db,SQLITE_LIMIT_ATTACHED,size) interface.

  12. Maximum Number Of Pages In A Database File

    SQLite is able to limit the size of a database file to prevent the database file from growing too large and consuming too much disk space. The SQLITE_MAX_PAGE_COUNT parameter, which is normally set to 1073741823, is the maximum number of pages allowed in a single database file. An attempt to insert new data that would cause the database file to grow larger than this will return SQLITE_FULL.

    The largest possible setting for SQLITE_MAX_PAGE_COUNT is 2147483646. When used with the maximum page size of 65536, this gives a maximum SQLite database size of about 140 terabytes.

    The max_page_count PRAGMA can be used to raise or lower this limit at run-time.

  13. Maximum Number Of Rows In A Table

    The theoretical maximum number of rows in a table is 264 (18446744073709551616 or about 1.8e+19). This limit is unreachable since the maximum database size of 14 terabytes will be reached first. A 14 terabytes database can hold no more than approximately 1e+13 rows, and then only if there are no indices and if each row contains very little data.


File Locking And Concurrency In SQLite Version 3

Choose any three.
About Sitemap Documentation Download License News Support

1.0 File Locking And Concurrency In SQLite Version 3

SQLite Version 3.0.0 introduced a new locking and journaling mechanism designed to improve concurrency over SQLite version 2 and to reduce the writer starvation problem. The new mechanism also allows atomic commits of transactions involving multiple database files. This document describes the new locking mechanism. The intended audience is programmers who want to understand and/or modify the pager code and reviewers working to verify the design of SQLite version 3.

This document was originally created in early 2004 when SQLite version 2 was still in widespread use and was written to introduce the new concepts of SQLite version 3 to readers who were already familiar with SQLite version 2. But these days, most readers of this document have probably never seen SQLite version 2 and are only familiar with SQLite version 3. Nevertheless, this document continues to serve as an authoritative reference to how database file locking works in SQLite version 3.

2.0 Overview

Locking and concurrency control are handled by the pager module. The pager module is responsible for making SQLite "ACID" (Atomic, Consistent, Isolated, and Durable). The pager module makes sure changes happen all at once, that either all changes occur or none of them do, that two or more processes do not try to access the database in incompatible ways at the same time, and that once changes have been written they persist until explicitly deleted. The pager also provides a memory cache of some of the contents of the disk file.

The pager is unconcerned with the details of B-Trees, text encodings, indices, and so forth. From the point of view of the pager the database consists of a single file of uniform-sized blocks. Each block is called a "page" and is usually 1024 bytes in size. The pages are numbered beginning with 1. So the first 1024 bytes of the database are called "page 1" and the second 1024 bytes are call "page 2" and so forth. All other encoding details are handled by higher layers of the library. The pager communicates with the operating system using one of several modules (Examples: os_unix.c, os_win.c) that provides a uniform abstraction for operating system services.

The pager module effectively controls access for separate threads, or separate processes, or both. Throughout this document whenever the word "process" is written you may substitute the word "thread" without changing the truth of the statement.

3.0 Locking

From the point of view of a single process, a database file can be in one of five locking states:

UNLOCKED | No locks are held on the database. The database may be neither read nor written. Any internally cached data is considered suspect and subject to verification against the database file before being used. Other processes can read or write the database as their own locking states permit. This is the default state.
SHARED | The database may be read but not written. Any number of processes can hold SHARED locks at the same time, hence there can be many simultaneous readers. But no other thread or process is allowed to write to the database file while one or more SHARED locks are active.
RESERVED | A RESERVED lock means that the process is planning on writing to the database file at some point in the future but that it is currently just reading from the file. Only a single RESERVED lock may be active at one time, though multiple SHARED locks can coexist with a single RESERVED lock. RESERVED differs from PENDING in that new SHARED locks can be acquired while there is a RESERVED lock.
PENDING | A PENDING lock means that the process holding the lock wants to write to the database as soon as possible and is just waiting on all current SHARED locks to clear so that it can get an EXCLUSIVE lock. No new SHARED locks are permitted against the database if a PENDING lock is active, though existing SHARED locks are allowed to continue.
EXCLUSIVE | An EXCLUSIVE lock is needed in order to write to the database file. Only one EXCLUSIVE lock is allowed on the file and no other locks of any kind are allowed to coexist with an EXCLUSIVE lock. In order to maximize concurrency, SQLite works to minimize the amount of time that EXCLUSIVE locks are held.

The operating system interface layer understands and tracks all five locking states described above. The pager module only tracks four of the five locking states. A PENDING lock is always just a temporary stepping stone on the path to an EXCLUSIVE lock and so the pager module does not track PENDING locks.

4.0 The Rollback Journal

When a process wants to change a database file (and it is not in WAL mode), it first records the original unchanged database content in a rollback journal. The rollback journal is an ordinary disk file that is always located in the same directory or folder as the database file and has the same name as the database file with the addition of a -journal suffix. The rollback journal also records the initial size of the database so that if the database file grows it can be truncated back to its original size on a rollback.

If SQLite is working with multiple databases at the same time (using the ATTACH command) then each database has its own rollback journal. But there is also a separate aggregate journal called the master journal. The master journal does not contain page data used for rolling back changes. Instead the master journal contains the names of the individual database rollback journals for each of the ATTACHed databases. Each of the individual database rollback journals also contain the name of the master journal. If there are no ATTACHed databases (or if none of the ATTACHed database is participating in the current transaction) no master journal is created and the normal rollback journal contains an empty string in the place normally reserved for recording the name of the master journal.

A individual rollback journal is said to be hot if it needs to be rolled back in order to restore the integrity of its database. A hot journal is created when a process is in the middle of a database update and a program or operating system crash or power failure prevents the update from completing. Hot journals are an exception condition. Hot journals exist to recover from crashes and power failures. If everything is working correctly (that is, if there are no crashes or power failures) you will never get a hot journal.

If no master journal is involved, then a journal is hot if it exists and has a non-zero header and its corresponding database file does not have a RESERVED lock. If a master journal is named in the file journal, then the file journal is hot if its master journal exists and there is no RESERVED lock on the corresponding database file. It is important to understand when a journal is hot so the preceding rules will be repeated in bullets:

  • A journal is hot if...
    • It exists, and
    • Its size is greater than 512 bytes, and
    • The journal header is non-zero and well-formed, and
    • Its master journal exists or the master journal name is an empty string, and
    • There is no RESERVED lock on the corresponding database file.

4.1 Dealing with hot journals

Before reading from a database file, SQLite always checks to see if that database file has a hot journal. If the file does have a hot journal, then the journal is rolled back before the file is read. In this way, we ensure that the database file is in a consistent state before it is read.

When a process wants to read from a database file, it followed the following sequence of steps:

  1. Open the database file and obtain a SHARED lock. If the SHARED lock cannot be obtained, fail immediately and return SQLITE_BUSY.
  2. Check to see if the database file has a hot journal. If the file does not have a hot journal, we are done. Return immediately. If there is a hot journal, that journal must be rolled back by the subsequent steps of this algorithm.
  3. Acquire a PENDING lock then an EXCLUSIVE lock on the database file. (Note: Do not acquire a RESERVED lock because that would make other processes think the journal was no longer hot.) If we fail to acquire these locks it means another process is already trying to do the rollback. In that case, drop all locks, close the database, and return SQLITE_BUSY.
  4. Read the journal file and roll back the changes.
  5. Wait for the rolled back changes to be written onto persistent storage. This protects the integrity of the database in case another power failure or crash occurs.
  6. Delete the journal file (or truncate the journal to zero bytes in length if PRAGMA journal_mode=TRUNCATE is set, or zero the journal header if PRAGMA journal_mode=PERSIST is set).
  7. Delete the master journal file if it is safe to do so. This step is optional. It is here only to prevent stale master journals from cluttering up the disk drive. See the discussion below for details.
  8. Drop the EXCLUSIVE and PENDING locks but retain the SHARED lock.

After the algorithm above completes successfully, it is safe to read from the database file. Once all reading has completed, the SHARED lock is dropped.

4.2 Deleting stale master journals

A stale master journal is a master journal that is no longer being used for anything. There is no requirement that stale master journals be deleted. The only reason for doing so is to free up disk space.

A master journal is stale if no individual file journals are pointing to it. To figure out if a master journal is stale, we first read the master journal to obtain the names of all of its file journals. Then we check each of those file journals. If any of the file journals named in the master journal exists and points back to the master journal, then the master journal is not stale. If all file journals are either missing or refer to other master journals or no master journal at all, then the master journal we are testing is stale and can be safely deleted.

5.0 Writing to a database file

To write to a database, a process must first acquire a SHARED lock as described above (possibly rolling back incomplete changes if there is a hot journal). After a SHARED lock is obtained, a RESERVED lock must be acquired. The RESERVED lock signals that the process intends to write to the database at some point in the future. Only one process at a time can hold a RESERVED lock. But other processes can continue to read the database while the RESERVED lock is held.

If the process that wants to write is unable to obtain a RESERVED lock, it must mean that another process already has a RESERVED lock. In that case, the write attempt fails and returns SQLITE_BUSY.

After obtaining a RESERVED lock, the process that wants to write creates a rollback journal. The header of the journal is initialized with the original size of the database file. Space in the journal header is also reserved for a master journal name, though the master journal name is initially empty.

Before making changes to any page of the database, the process writes the original content of that page into the rollback journal. Changes to pages are held in memory at first and are not written to the disk. The original database file remains unaltered, which means that other processes can continue to read the database.

Eventually, the writing process will want to update the database file, either because its memory cache has filled up or because it is ready to commit its changes. Before this happens, the writer must make sure no other process is reading the database and that the rollback journal data is safely on the disk surface so that it can be used to rollback incomplete changes in the event of a power failure. The steps are as follows:

  1. Make sure all rollback journal data has actually been written to the surface of the disk (and is not just being held in the operating system's or disk controllers cache) so that if a power failure occurs the data will still be there after power is restored.
  2. Obtain a PENDING lock and then an EXCLUSIVE lock on the database file. If other processes still have SHARED locks, the writer might have to wait until those SHARED locks clear before it is able to obtain an EXCLUSIVE lock.
  3. Write all page modifications currently held in memory out to the original database disk file.

If the reason for writing to the database file is because the memory cache was full, then the writer will not commit right away. Instead, the writer might continue to make changes to other pages. Before subsequent changes are written to the database file, the rollback journal must be flushed to disk again. Note also that the EXCLUSIVE lock that the writer obtained in order to write to the database initially must be held until all changes are committed. That means that no other processes are able to access the database from the time the memory cache first spills to disk until the transaction commits.

When a writer is ready to commit its changes, it executes the following steps:

  4. Obtain an EXCLUSIVE lock on the database file and make sure all memory changes have been written to the database file using the algorithm of steps 1-3 above.
  5. Flush all database file changes to the disk. Wait for those changes to actually be written onto the disk surface.
  6. Delete the journal file. (Or if the PRAGMA journal_mode is TRUNCATE or PERSIST, truncate the journal file or zero the header of the journal file, respectively.) This is the instant when the changes are committed. Prior to deleting the journal file, if a power failure or crash occurs, the next process to open the database will see that it has a hot journal and will roll the changes back. After the journal is deleted, there will no longer be a hot journal and the changes will persist.
  7. Drop the EXCLUSIVE and PENDING locks from the database file.

As soon as the PENDING lock is released from the database file, other processes can begin reading the database again. In the current implementation, the RESERVED lock is also released, but that is not essential. Future versions of SQLite might provide a "CHECKPOINT" SQL command that will commit all changes made so far within a transaction but retain the RESERVED lock so that additional changes can be made without given any other process an opportunity to write.

If a transaction involves multiple databases, then a more complex commit sequence is used, as follows:

  4. Make sure all individual database files have an EXCLUSIVE lock and a valid journal.
  5. Create a master-journal. The name of the master-journal is arbitrary. (The current implementation appends random suffixes to the name of the main database file until it finds a name that does not previously exist.) Fill the master journal with the names of all the individual journals and flush its contents to disk.
  6. Write the name of the master journal into all individual journals (in space set aside for that purpose in the headers of the individual journals) and flush the contents of the individual journals to disk and wait for those changes to reach the disk surface.
  7. Flush all database file changes to the disk. Wait for those changes to actually be written onto the disk surface.
  8. Delete the master journal file. This is the instant when the changes are committed. Prior to deleting the master journal file, if a power failure or crash occurs, the individual file journals will be considered hot and will be rolled back by the next process that attempts to read them. After the master journal has been deleted, the file journals will no longer be considered hot and the changes will persist.
  9. Delete all individual journal files.
  10. Drop the EXCLUSIVE and PENDING locks from all database files.

5.1 Writer starvation

In SQLite version 2, if many processes are reading from the database, it might be the case that there is never a time when there are no active readers. And if there is always at least one read lock on the database, no process would ever be able to make changes to the database because it would be impossible to acquire a write lock. This situation is called writer starvation.

SQLite version 3 seeks to avoid writer starvation through the use of the PENDING lock. The PENDING lock allows existing readers to continue but prevents new readers from connecting to the database. So when a process wants to write a busy database, it can set a PENDING lock which will prevent new readers from coming in. Assuming existing readers do eventually complete, all SHARED locks will eventually clear and the writer will be given a chance to make its changes.

6.0 How To Corrupt Your Database Files

The pager module is very robust but it can be subverted. This section attempts to identify and explain the risks. (See also the Things That Can Go Wrong section of the article on Atomic Commit.

Clearly, a hardware or operating system fault that introduces incorrect data into the middle of the database file or journal will cause problems. Likewise, if a rogue process opens a database file or journal and writes malformed data into the middle of it, then the database will become corrupt. There is not much that can be done about these kinds of problems so they are given no further attention.

SQLite uses POSIX advisory locks to implement locking on Unix. On Windows it uses the LockFile(), LockFileEx(), and UnlockFile() system calls. SQLite assumes that these system calls all work as advertised. If that is not the case, then database corruption can result. One should note that POSIX advisory locking is known to be buggy or even unimplemented on many NFS implementations (including recent versions of Mac OS X) and that there are reports of locking problems for network filesystems under Windows. Your best defense is to not use SQLite for files on a network filesystem.

SQLite uses the fsync() system call to flush data to the disk under Unix and it uses the FlushFileBuffers() to do the same under Windows. Once again, SQLite assumes that these operating system services function as advertised. But it has been reported that fsync() and FlushFileBuffers() do not always work correctly, especially with inexpensive IDE disks. Apparently some manufactures of IDE disks have controller chips that report that data has reached the disk surface when in fact the data is still in volatile cache memory in the disk drive electronics. There are also reports that Windows sometimes chooses to ignore FlushFileBuffers() for unspecified reasons. The author cannot verify any of these reports. But if they are true, it means that database corruption is a possibility following an unexpected power loss. These are hardware and/or operating system bugs that SQLite is unable to defend against.

If a Linux ext3 filesystem is mounted without the "barrier=1" option in the /etc/fstab and the disk drive write cache is enabled then filesystem corruption can occur following a power loss or OS crash. Whether or not corruption can occur depends on the details of the disk control hardware; corruption is more likely with inexpensive consumer-grade disks and less of a problem for enterprise-class storage devices with advanced features such as non-volatile write caches. Various ext3 experts confirm this behavior. We are told that most Linux distributions do not use barrier=1 and do not disable the write cache so most Linux distributions are vulnerable to this problem. Note that this is an operating system and hardware issue and that there is nothing that SQLite can do to work around it. Other database engines have also run into this same problem.

If a crash or power failure occurs and results in a hot journal but that journal is deleted, the next process to open the database will not know that it contains changes that need to be rolled back. The rollback will not occur and the database will be left in an inconsistent state. Rollback journals might be deleted for any number of reasons:

  • An administrator might be cleaning up after an OS crash or power failure, see the journal file, think it is junk, and delete it.
  • Someone (or some process) might rename the database file but fail to also rename its associated journal.
  • If the database file has aliases (hard or soft links) and the file is opened by a different alias than the one used to create the journal, then the journal will not be found. To avoid this problem, you should not create links to SQLite database files.
  • Filesystem corruption following a power failure might cause the journal to be renamed or deleted.

The last (fourth) bullet above merits additional comment. When SQLite creates a journal file on Unix, it opens the directory that contains that file and calls fsync() on the directory, in an effort to push the directory information to disk. But suppose some other process is adding or removing unrelated files to the directory that contains the database and journal at the moment of a power failure. The supposedly unrelated actions of this other process might result in the journal file being dropped from the directory and moved into "lost+found". This is an unlikely scenario, but it could happen. The best defenses are to use a journaling filesystem or to keep the database and journal in a directory by themselves.

For a commit involving multiple databases and a master journal, if the various databases were on different disk volumes and a power failure occurs during the commit, then when the machine comes back up the disks might be remounted with different names. Or some disks might not be mounted at all. When this happens the individual file journals and the master journal might not be able to find each other. The worst outcome from this scenario is that the commit ceases to be atomic. Some databases might be rolled back and others might not. All databases will continue to be self-consistent. To defend against this problem, keep all databases on the same disk volume and/or remount disks using exactly the same names after a power failure.

7.0 Transaction Control At The SQL Level

The changes to locking and concurrency control in SQLite version 3 also introduce some subtle changes in the way transactions work at the SQL language level. By default, SQLite version 3 operates in autocommit mode. In autocommit mode, all changes to the database are committed as soon as all operations associated with the current database connection complete.

The SQL command "BEGIN TRANSACTION" (the TRANSACTION keyword is optional) is used to take SQLite out of autocommit mode. Note that the BEGIN command does not acquire any locks on the database. After a BEGIN command, a SHARED lock will be acquired when the first SELECT statement is executed. A RESERVED lock will be acquired when the first INSERT, UPDATE, or DELETE statement is executed. No EXCLUSIVE lock is acquired until either the memory cache fills up and must be spilled to disk or until the transaction commits. In this way, the system delays blocking read access to the file file until the last possible moment.

The SQL command "COMMIT" does not actually commit the changes to disk. It just turns autocommit back on. Then, at the conclusion of the command, the regular autocommit logic takes over and causes the actual commit to disk to occur. The SQL command "ROLLBACK" also operates by turning autocommit back on, but it also sets a flag that tells the autocommit logic to rollback rather than commit.

If the SQL COMMIT command turns autocommit on and the autocommit logic then tries to commit change but fails because some other process is holding a SHARED lock, then autocommit is turned back off automatically. This allows the user to retry the COMMIT at a later time after the SHARED lock has had an opportunity to clear.

If multiple commands are being executed against the same SQLite database connection at the same time, the autocommit is deferred until the very last command completes. For example, if a SELECT statement is being executed, the execution of the command will pause as each row of the result is returned. During this pause other INSERT, UPDATE, or DELETE commands can be executed against other tables in the database. But none of these changes will commit until the original SELECT statement finishes.


Dynamic Memory Allocation In SQLite

SQLite uses dynamic memory allocation to obtain memory for storing various objects (ex: database connections and prepared statements) and to build a memory cache of the database file and to hold the results of queries. Much effort has gone into making the dynamic memory allocation subsystem of SQLite reliable, predictable, robust, and efficient.

This document provides an overview of dynamic memory allocation within SQLite. The target audience is software engineers who are tuning their use of SQLite for peak performance in demanding environments. Nothing in this document is required knowledge for using SQLite. The default settings and configuration for SQLite will work well in most applications. However, the information contained in this document may be useful to engineers who are tuning SQLite to comply with special requirements or to run under unusual circumstances.

1.0 Features

The SQLite core and its memory allocation subsystem provides the following capabilities:

  • Robust against allocation failures. If a memory allocation ever fails (that is to say, if malloc() or realloc() ever return NULL) then SQLite will recover gracefully. SQLite will first attempt to free memory from unpinned cache pages then retry the allocation request. Failing that, SQLite will either stop what it is doing and return the SQLITE_NOMEM error code back up to the application or it will make do without the requested memory.

  • No memory leaks. The application is responsible for destroying any objects it allocates. (For example, the application must use sqlite3_finalize() on every prepared statement and sqlite3_close() on every database connection.) But as long as the application cooperates, SQLite will never leak memory. This is true even in the face of memory allocation failures or other system errors.

  • Memory usage limits. The sqlite3_soft_heap_limit64() mechanism allows the application to set a memory usage limit that SQLite strives to stay below. SQLite will attempt to reuse memory from its caches rather than allocation new memory as it approaches the soft limit.

  • Zero-malloc option The application can provide SQLite with several buffers of bulk memory at startup and SQLite will then use those provided buffers for all of its memory allocation needs and never call system malloc() or free().

  • Application-supplied memory allocators. The application can provide SQLite with pointers to alternative memory allocators at start-time. The alternative memory allocator will be used in place of system malloc() and free().

  • Proof against breakdown and fragmentation. SQLite can be configured so that, subject to certain usage constraints detailed below, it is guaranteed to never fail a memory allocation or fragment the heap. This property is important to long-running, high-reliability embedded systems where a memory allocation error could contribute to an overall system failure.

  • Memory usage statistics. Applications can see how much memory they are using and detect when memory usage is approaching or exceeding design boundaries.

  • Minimal calls to the allocator. The system malloc() and free() implementations are inefficient on many systems. SQLite strives to reduce overall processing time by minimizing its use of malloc() and free().

  • Open access. Pluggable SQLite extensions or even the application itself can access to the same underlying memory allocation routines used by SQLite through the sqlite3_malloc(), sqlite3_realloc(), and sqlite3_free() interfaces.

2.0 Testing

Over 75% of the code in the SQLite source tree is devoted purely to testing and verification. Reliability is important to SQLite. Among the tasks of the test infrastructure is to ensure that SQLite does not misuse dynamically allocated memory, that SQLite does not leak memory, and that SQLite responds correctly to a dynamic memory allocation failure.

The test infrastructure verifies that SQLite does not misuse dynamically allocated memory by using a specially instrumented memory allocator. The instrumented memory allocator is enabled at compile-time using the SQLITE_MEMDEBUG option. The instrumented memory allocator is much slower than the default memory allocator and so its use is not recommended in production. But when enabled during testing, the instrumented memory allocator performs the following checks:

  • Bounds checking. The instrumented memory allocator places sentinel values at both ends of each memory allocation to verify that nothing within SQLite writes outside the bounds of the allocation.

  • Use of memory after freeing. When each block of memory is freed, every byte is overwritten with a nonsense bit pattern. This helps to ensure that no memory is ever used after having been freed.

  • Freeing memory not obtained from malloc. Each memory allocation from the instrumented memory allocator contains sentinels used to verify that every allocation freed came from prior malloc.

  • Uninitialized memory. The instrumented memory allocator initializes each memory allocation to a nonsense bit pattern to help ensure that the user makes no assumptions about the content of allocation memory.

Regardless of whether or not the instrumented memory allocator is used, SQLite keeps track of how much memory is currently checked out. There are hundreds of test scripts used for testing SQLite. At the end of each script, all objects are destroyed and a test is made to ensure that all memory has been freed. This is how memory leaks are detected. Notice that memory leak detection is in force at all times, during test builds and during production builds. Whenever one of the developers runs any individual test script, memory leak detection is active. Hence memory leaks that do arise during development are quickly detected and fixed.

The response of SQLite to out-of-memory (OOM) errors is tested using a specialized memory allocator overlay that can simulate memory failures. The overlay is a layer that is inserted in between the memory allocator and the rest of SQLite. The overlay passes most memory allocation requests straight through to the underlying allocator and passes the results back up to the requester. But the overlay can be set to cause the Nth memory allocation to fail. To run an OOM test, the overlay is first set to fail on the first allocation attempt. Then some test script is run and verification that the allocation was correctly caught and handled is made. Then the overlay is set to fail on the second allocation and the test repeats. The failure point continues to advice one allocation at a time until the entire test procedure runs to completion without hitting a memory allocation error. This whole test sequence run twice. On the first pass, the overlay is set to fail only the Nth allocation. On the second pass, the overlay is set to fail the Nth and all subsequent allocations.

Note that the memory leak detection logic continues to work even when the OOM overlay is being used. This verifies that SQLite does not leak memory even when it encounters memory allocation errors. Note also that the OOM overlay can work with any underlying memory allocator, including the instrumented memory allocator that checks for memory allocation misuse. In this way it is verified that OOM errors do not induce other kinds of memory usage errors.

Finally, we observe that the instrumented memory allocator and the memory leak detector both work over the entire SQLite test suite and the TCL test suite provides over 99% statement test coverage and that the TH3 test harness provides 100% branch test coverage with no leak leaks. This is strong evidence that dynamic memory allocation is used correctly everywhere within SQLite.

3.0 Configuration

The default memory allocation settings in SQLite are appropriate for most applications. However, applications with unusual or particularly strict requirements may want to adjust the configuration to more closely align SQLite to their needs. Both compile-time and start-time configuration options are available.

3.1 Alternative low-level memory allocators

The SQLite source code includes several different memory allocation modules that can be selected at compile-time, or to a limited extent at start-time.

3.1.1 The default memory allocator

By default, SQLite uses the malloc(), realloc(), and free() routines from the standard C library for its memory allocation needs. These routines are surrounded by a thin wrapper that also provides a "memsize()" function that will return the size of an existing allocation. The memsize() function is needed to keep an accurate count of the number of bytes of outstanding memory; memsize() determines how many bytes to remove from the outstanding count when an allocation is freed. The default allocator implements memsize() by always allocating 8 extra bytes on each malloc() request and storing the size of the allocation in that 8-byte header.

The default memory allocator is recommended for most applications. If you do not have a compelling need to use an alternative memory allocator, then use the default.

3.1.2 The debugging memory allocator

If SQLite is compiled with the SQLITE_MEMDEBUG compile-time option, then a different, heavy wrapper is used around system malloc(), realloc(), and free(). The heavy wrapper allocates around 100 bytes of extra space with each allocation. The extra space is used to place sentinel values at both ends of the allocation returned to the SQLite core. When an allocation is freed, these sentinels are checked to make sure the SQLite core did not overrun the buffer in either direction. When the system library is GLIBC, the heavy wrapper also makes use of the GNU backtrace() function to examine the stack and record the ancestor functions of the malloc() call. When running the SQLite test suite, the heavy wrapper also records the name of the current test case. These latter two features are useful for tracking down the source of memory leaks detected by the test suite.

The heavy wrapper that is used when SQLITE_MEMDEBUG is set also makes sure each new allocation is filled with nonsense data prior to returning the allocation to the caller. And as soon as an allocation is free, it is again filled with nonsense data. These two actions help to ensure that the SQLite core does not make assumptions about the state of newly allocated memory and that memory allocations are not used after they have been freed.

The heavy wrapper employed by SQLITE_MEMDEBUG is intended for use only during testing, analysis, and debugging of SQLite. The heavy wrapper has a significant performance and memory overhead and probably should not be used in production.

3.1.3 Zero-malloc memory allocator

When SQLite is compiled with the SQLITE_ENABLE_MEMSYS5 option, an alternative memory allocator that does not use malloc() is included in the build. The SQLite developers refer to this alternative memory allocator as "memsys5". Even when it is included in the build, memsys5 is disabled by default. To enable memsys5, the application must invoke the following SQLite interface at start-time:

sqlite3_config(SQLITE_CONFIG_HEAP, pBuf, szBuf, mnReq);

In the call above, pBuf is a pointer to a large, contiguous chunk of memory space that SQLite will use to satisfy all of its memory allocation needs. pBuf might point to a static array or it might be memory obtained from some other application-specific mechanism. szBuf is an integer that is the number of bytes of memory space pointed to by pBuf. mnReq is another integer that is the minimum size of an allocation. Any call to sqlite3_malloc(N) where N is less than mnReq will be rounded up to mnReq. mnReq must be a power of two. We shall see later that the mnReq parameter is important in reducing the value of n and hence the minimum memory size requirement in the Robson proof.

The memsys5 allocator is designed for use on embedded systems, though there is nothing to prevent its use on workstations. The szBuf is typically between a few hundred kilobytes up to a few dozen megabytes, depending on system requirements and memory budget.

The algorithm used by memsys5 can be called "power-of-two, first-fit". The sizes of all memory allocation requests are rounded up to a power of two and the request is satisfied by the first free slot in pBuf that is large enough. Adjacent freed allocations are coalesced using a buddy system. When used appropriately, this algorithm provides mathematical guarantees against fragmentation and breakdown, as described further below.

3.1.4 Experimental memory allocators

The name "memsys5" used for the zero-malloc memory allocator implies that there are several additional memory allocators available, and indeed there are. The default memory allocator is "memsys1". The debugging memory allocator is "memsys2". Those have already been covered.

If SQLite is compiled with SQLITE_ENABLE_MEMSYS3 than another zero-malloc memory allocator, similar to memsys5, is included in the source tree. The memsys3 allocator, like memsys5, must be activated by a call to sqlite3_config(SQLITE_CONFIG_HEAP,...). Memsys3 uses the memory buffer supplied as its source for all memory allocations. The difference between memsys3 and memsys5 is that memsys3 uses a different memory allocation algorithm that seems to work well in practice, but which does not provide mathematical guarantees against memory fragmentation and breakdown. Memsys3 was a predecessor to memsys5. The SQLite developers now believe that memsys5 is superior to memsys3 and that all applications that need a zero-malloc memory allocator should use memsys5 in preference to memsys3. Memsys3 is considered both experimental and deprecated and will likely be removed from the source tree in a future release of SQLite.

Code for memsys4 is still in the SQLite source tree (as of this writing - SQLite version 3.6.1), but it has not been maintained for several release cycles and probably does not work. (Update: memsys4 was removed as of version 3.6.5) Memsys4 was an attempt to use mmap() to obtain memory and then use madvise() to release unused pages back to the operating system so that they could be reused by other processes. The work on memsys4 has been abandoned and the memsys4 module will likely be removed from the source tree in the near future.

Memsys6 uses system malloc() and free() to obtain the memory it needs. Memsys6 serves as an aggregator. Memsys6 only calls system malloc() to obtain large allocations. It then subdivides those large allocations to services multiple smaller memory allocation requests coming from the SQLite core. Memsys6 is intended for use in systems where system malloc() is particularly inefficient. The idea behind memsys6 is to reduce the number of calls to system malloc() by a factor of 10 or more.

Memsys6 is made available by compiling SQLite with the SQLITE_ENABLE_MEMSYS6 compile-time option and then at start-time invoking:

sqlite3_config(SQLITE_CONFIG_CHUNKALLOC);

Memsys6 was added in SQLite version 3.6.1. It is very experimental. Its future is uncertain and it may be removed in a subsequent release. Update: Memsys6 was removed as of version 3.6.5.

Other experimental memory allocators might be added in future releases of SQLite. One many anticipate that these will be called memsys7, memsys8, and so forth.

3.1.5 Application-defined memory allocators

New memory allocators do not have to be part of the SQLite source tree nor included in the sqlite3.c amalgamation. Individual applications can supply their own memory allocators to SQLite at start-time.

To cause SQLite to use a new memory allocator, the application simply calls:

sqlite3_config(SQLITE_CONFIG_MALLOC, pMem);

In the call above, pMem is a pointer to an sqlite3_mem_methods object that defines the interface to the application-specific memory allocator. The sqlite3_mem_methods object is really just a structure containing pointers to functions to implement the various memory allocation primitives.

In a multi-threaded application, access to the sqlite3_mem_methods is serialized if and only if SQLITE_CONFIG_MEMSTATUS is enabled. If SQLITE_CONFIG_MEMSTATUS is disabled then the methods in sqlite3_mem_methods must take care of their own serialization needs.

3.1.6 Memory allocator overlays

An application can insert layers or "overlays" in between the SQLite core and the underlying memory allocator. For example, the out-of-memory test logic for SQLite uses an overlay that can simulate memory allocation failures.

An overlay can be created by using the

sqlite3_config(SQLITE_CONFIG_GETMALLOC, pOldMem);

interface to obtain pointers to the existing memory allocator. The existing allocator is saved by the overlay and is used as a fallback to do real memory allocation. Then the overlay is inserted in place of the existing memory allocator using the sqlite3_config(SQLITE_CONFIG_MALLOC,...) as described above.

3.1.7 No-op memory allocator stub

If SQLite is compiled with the SQLITE_ZERO_MALLOC option, then the default memory allocator is omitted and replaced by a stub memory allocator that never allocates any memory. Any calls to the stub memory allocator will report back that no memory is available.

The no-op memory allocator is not useful by itself. It exists only as a placeholder so that SQLite has a memory allocator to link against on systems that may not have malloc(), free(), or realloc() in their standard library. An application that is compiled with SQLITE_ZERO_MALLOC will need to use sqlite3_config() together with SQLITE_CONFIG_MALLOC or SQLITE_CONFIG_HEAP to specify a new alternative memory allocator before beginning to use SQLite.

3.2 Scratch memory

SQLite occasionally needs a large chunk of "scratch" memory to perform some transient calculation. Scratch memory is used, for example, as temporary storage when rebalancing a B-Tree. These scratch memory allocations are typically about 10 kilobytes in size and are transient - lasting only for the duration of a single, short-lived function call.

In older versions of SQLite, the scratch memory was obtained from the processor stack. That works great on workstations with a large stack. But pulling large buffers from the stack caused problems on embedded systems with a small processor stack (typically 4K or 8K). And so SQLite was modified to allocate scratch memory from the heap.

However, doing occasional large transient allocations from the heap can lead to memory fragmentation in embedded systems. To work around this problem, a separate memory allocation system for scratch memory has been created.

The scratch memory allocator is set up as follows:

sqlite3_config(SQLITE_CONFIG_SCRATCH, pBuf, sz, N);

The pBuf parameter is a pointer to a contiguous range of bytes that SQLite will use for all scratch memory allocations. The buffer must be at least sz*N bytes in size. The "sz" parameter is the maximum size of each scratch allocation. N is the maximum number of simultaneous scratch allocations. The "sz" parameter should be approximately 6 times the maximum database page size. N should be twice the number of threads running in the system. No single thread will ever request more than two scratch allocation at a time so if there are never more than N threads, then there will always be enough scratch memory available.

If the scratch memory setup does not define enough memory, then SQLite falls back to using the regular memory allocator for its scratch memory allocations. The default setup is sz=0 and N=0 so the use of the regular memory allocator is the default behavior.

3.3 Page cache memory

In most applications, the database page cache subsystem within SQLite uses more dynamically allocated memory than all other parts of SQLite combined. It is not unusual to see the database page cache consumes over 10 times more memory than the rest of SQLite combined.

SQLite can be configured to make page cache memory allocations from a separate and distinct memory pool of fixed-size slots. This can have two advantages:

  • Because allocations are all the same size, the memory allocator can operate much faster. The allocator need not bother with coalescing adjacent free slots or searching for a slot of an appropriate size. All unallocated memory slots can be stored on a linked list. Allocating consists of removing the first entry from the list. Deallocating is simply adding an entry to the beginning of the list.

  • With a single allocation size, the n parameter in the Robson proof is 1, and the total memory space required by the allocator (N) is exactly equal to maximum memory used (M). No additional memory is required to cover fragmentation overhead, thus reducing memory requirements. This is particularly important for the page cache memory since the page cache constitutes the largest component of the memory needs of SQLite.

The page-cache memory allocator is disabled by default. An application can enabled it at start-time as follows:

sqlite3_config(SQLITE_CONFIG_PAGECACHE, pBuf, sz, N);

The pBuf parameter is a pointer to a contiguous range of bytes that SQLite will use for page-cache memory allocations. The buffer must be at least sz*N bytes in size. The "sz" parameter is the size of each page-cache allocation. N is the maximum number of available allocations.

If SQLite needs a page-cache entry that is larger than "sz" bytes or if it needs more than N entries, it falls back to using the general-purpose memory allocator.

3.4 Lookaside memory allocator

SQLite database connections make many small and short-lived memory allocations. This occurs most commonly when compiling SQL statements using sqlite3_prepare_v2() but also to a lesser extent when running prepared statements using sqlite3_step(). These small memory allocations are used to hold things such as the names of tables and columns, parse tree nodes, individual query results values, and B-Tree cursor objects. There are consequently many calls to malloc() and free() - so many calls that malloc() and free() end up using a significant fraction of the CPU time assigned to SQLite.

SQLite version 3.6.1 introduced the lookaside memory allocator to help reduce the memory allocation load. In the lookaside allocator, each database connection preallocates a single large chunk of memory (typically in the range of 50 to 100 kilobytes) and divides that chunk up into small fixed-size "slots" of around 50 to 200 byte each. This becomes the lookaside memory pool. Thereafter, memory allocations associated with the database connection and that are not too larger are satisfied using one of the lookaside pool slots rather than by calling the general-purpose memory allocator. Larger allocations continue to use the general-purpose memory allocator, as do allocations that occur when the lookaside pool slots are all checked out. But in many cases, the memory allocations are small enough and there are few enough outstanding that the new memory requests can be satisfied from the lookaside pool.

Because lookaside allocations are always the same size, the allocation and deallocation algorithms are very quick. There is no need to coalesce adjacent free slots or search for a slot of a particular size. Each database connection maintains a singly-linked list of unused slots. Allocation requests simply pull the first element of this list. Deallocations simply push the element back onto the front of the list. Furthermore, each database connection is assumed to already be running in a single thread (there are mutexes already in place to enforce this) so no additional mutexing is required to serialize access to the lookaside slot freelist. Consequently, lookaside memory allocations and deallocations are very fast. In speed tests on Linux and Mac OS X workstations, SQLite has shown overall performance improvements as high as 10% and 15%, depending on the workload how lookaside is configured.

The size of the lookaside memory pool has a global default value but can also be configured on a connection-by-connection basis. To change the default size of the lookaside memory pool use the following interface at start-time:

sqlite3_config(SQLITE_CONFIG_LOOKASIDE, sz, cnt);

The "sz" parameter is the size in bytes of each lookaside slot. The default is 100 bytes. The "cnt" parameter is the total number of lookaside memory slots per database connection. The default value is 500 slots. The total amount of lookaside memory allocated to each database connection is sz*cnt bytes. Hence the lookaside memory pool allocated per database connection is 50 kilobytes by default. (Note: these default values are for SQLite version 3.6.1 and are subject to changes in future releases.)

The lookaside pool can be changed for an individual database connection "db" using this call:

sqlite3_db_config(db, SQLITE_DBCONFIG_LOOKASIDE, pBuf, sz, cnt);

The "pBuf" parameter is a pointer to memory space that will be used for the lookaside memory pool. If pBuf is NULL, then SQLite will obtain its own space for the memory pool using sqlite3_malloc(). The "sz" and "cnt" parameters are the size of each lookaside slot and the number of slots, respectively. If pBuf is not NULL, then it must point to at least sz*cnt bytes of memory.

The lookaside configuration can only be changed while there are no outstanding lookaside allocations for the database connection. Hence, the configuration should be set immediately after creating the database connection using sqlite3_open() (or equivalent) and before evaluating any SQL statements on the connection.

3.5 Memory status

By default, SQLite keeps statistics on its memory usage. These statistics are useful in helping to determine how much memory an application really needs. The statistics can also be used in high-reliability system to determine if the memory usage is coming close to or exceeding the limits of the Robson proof and hence that the memory allocation subsystem is liable to breakdown.

Most memory statistics are global, and therefore the tracking of statistics must be serialized with a mutex. Statistics are turned on by default, but an option exists to disable them. By disabling memory statistics, SQLite avoids entering and leaving a mutex on each memory allocation and deallocation. That savings can be noticeable on systems where mutex operations are expensive. To disable memory statistics, the following interface is used at start-time:

sqlite3_config(SQLITE_CONFIG_MEMSTATUS, onoff);

The "onoff" parameter is true to enable the tracking of memory statistics and false to disable statistics tracking.

Assuming statistics are enabled, the following routine can be used to access them:

sqlite3_status(verb, ¤t, &highwater, resetflag);

The "verb" argument determines what statistic is accessed. There are various verbs defined. The list is expected to grow as the sqlite3_status() interface matures. The current value the selected parameter is written into integer "current" and the highest historical value is written into integer "highwater". If resetflag is true, then the high-water mark is reset down to the current value after the call returns.

A different interface is used to find statistics associated with a single database connection:

sqlite3_db_status(db, verb, ¤t, &highwater, resetflag);

This interface is similar except that it takes a pointer to a database connection as its first argument and returns statistics about that one object rather than about the entire SQLite library. The sqlite3_db_status() interface currently only recognizes a single verb SQLITE_DBSTATUS_LOOKASIDE_USED, though additional verbs may be added in the future.

The per-connection statistics do not use global variables and hence do not require mutexes to update or access. Consequently the per-connection statistics continue to function even if SQLITE_CONFIG_MEMSTATUS is turned off.

3.6 Setting memory usage limits

The sqlite3_soft_heap_limit64() interface can be used to set an upper bound on the total amount of outstanding memory that the general-purpose memory allocator for SQLite will allow to be outstanding at one time. If attempts are made to allocate more memory that specified by the soft heap limit, then SQLite will first attempt to free cache memory before continuing with the allocation request. The soft heap limit mechanism only works if memory statistics are enabled and it works best if the SQLite library is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option.

The soft heap limit is "soft" in this sense: If SQLite is not able to free up enough auxiliary memory to stay below the limit, it goes ahead and allocations the extra memory and exceeds its limit. This occurs under the theory that it is better to use additional memory than to fail outright.

As of SQLite version 3.6.1, the soft heap limit only applies to the general-purpose memory allocator. The soft heap limit does not know about or interact with the scratch memory allocator, the pagecache memory allocator, or the lookaside memory allocator. This deficiency will likely be addressed in a future release.

4.0 Mathematical Guarantees Against Memory Allocation Failures

The problem of dynamic memory allocation, and specifically the problem of a memory allocator breakdown, has been studied by J. M. Robson and the results published as:

J. M. Robson. "Bounds for Some Functions Concerning Dynamic Storage Allocation". Journal of the Association for Computing Machinery, Volume 21, Number 8, July 1974, pages 491-499.

Let us use the following notation (similar but not identical to Robson's notation):

N | The amount of raw memory needed by the memory allocation system in order to guarantee that no memory allocation will ever fail.
M | The maximum amount of memory that the application ever has checked out at any point in time.
n | The ratio of the largest memory allocation to the smallest. We assume that every memory allocation size is an integer multiple of the smallest memory allocation size.

Robson proves the following result:

N = M*(1 + (log2 n)/2) - n + 1

Colloquially, the Robson proof shows that in order to guarantee breakdown-free operation, any memory allocator must use a memory pool of size N which exceeds the maximum amount of memory ever used M by a multiplier that depends on n, the ratio of the largest to the smallest allocation size. In other words, unless all memory allocations are of exactly the same size (n=1) then the system needs access to more memory than it will ever use at one time. Furthermore, we see that the amount of surplus memory required grows rapidly as the ratio of largest to smallest allocations increases, and so there is strong incentive to keep all allocations as near to the same size as possible.

Robson's proof is constructive. He provides an algorithm for computing a sequence of allocation and deallocation operations that will lead to an allocation failure due to memory fragmentation if available memory is as much as one byte less than N. And, Robson shows that a power-of-two first-fit memory allocator (such as implemented by memsys5) will never fail a memory allocation provided that available memory is N or more bytes.

The values M and n are properties of the application. If an application is constructed in such a way that both M and n are known, or at least have known upper bounds, and if the application uses the memsys5 memory allocator and is provided with N bytes of available memory space using SQLITE_CONFIG_HEAP then Robson proves that no memory allocation request will ever fail within the application. To put this another way, the application developer can select a value for N that will guarantee that no call to any SQLite interface will ever return SQLITE_NOMEM. The memory pool will never become so fragmented that a new memory allocation request cannot be satisfied. This is an important property for applications where a software fault could cause injury, physical harm, or loss of irreplaceable data.

4.1 Computing and controlling parameters M and n

The Robson proof applies separately to each of the memory allocators used by SQLite:

  • The general-purpose memory allocator (memsys5).
  • The scratch memory allocator.
  • The pagecache memory allocator.
  • The lookaside memory allocator.

For allocators other than memsys5, all memory allocations are of the same size. Hence, n=1 and therefore N=M. In other words, the memory pool need be no larger than the largest amount of memory in use at any given moment.

SQLite guarantees that no thread will ever use more than two scratch memory slots at one time. So if an application allocates twice as many scratch memory slots as there are threads, and assuming the size of each slot is large enough, there is never a chance of overflowing the scratch memory allocator. An upper bound on the size of scratch memory allocations is six times the largest page size. It is easy, therefore, to guarantee breakdown-free operation of the scratch memory allocator.

The usage of pagecache memory is somewhat harder to control in SQLite version 3.6.1, though mechanisms are planned for subsequent releases that will make controlling pagecache memory much easier. Prior to the introduction of these new mechanisms, the only way to control pagecache memory is using the cache_size pragma.

Safety-critical applications will usually want to modify the default lookaside memory configuration so that when the initial lookaside memory buffer is allocated during sqlite3_open() the resulting memory allocation is not so large as to force the n parameter to be too large. In order to keep n under control, it is best to try to keep the largest memory allocation below 2 or 4 kilobytes. Hence, a reasonable default setup for the lookaside memory allocator might any one of the following:

sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 32, 32);  /* 1K */
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 64, 32);  /* 2K */
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 32, 64);  /* 2K */
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 64, 64);  /* 4K */

Another approach is to initially disable the lookaside memory allocator:

sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 0, 0);

Then let the application maintain a separate pool of larger lookaside memory buffers that it can distribute to database connections as they are created. In the common case, the application will only have a single database connection and so the lookaside memory pool can consist of a single large buffer.

sqlite3_db_config(db, SQLITE_DBCONFIG_LOOKASIDE, aStatic, 256, 500);

The lookaside memory allocator is really intended as performance optimization, not as a method for assuring breakdown-free memory allocation, so it is not unreasonable to completely disable the lookaside memory allocator for safety-critical operations.

The general purpose memory allocator is the most difficult memory pool to manage because it supports allocations of varying sizes. Since n is a multiplier on M we want to keep n as small as possible. This argues for keeping the minimum allocation size for memsys5 as large as possible. In most applications, the lookaside memory allocator is able to handle small allocations. So it is reasonable to set the minimum allocation size for memsys5 to 2, 4 or even 8 times the maximum size of a lookaside allocation. A minimum allocation size of 512 is a reasonable setting.

Further to keeping n small, one desires to keep the size of the largest memory allocations under control. Large requests to the general-purpose memory allocator might come from several sources:

  1. SQL table rows that contain large strings or BLOBs.
  2. Complex SQL queries that compile down to large prepared statements.
  3. SQL parser objects used internally by sqlite3_prepare_v2().
  4. Storage space for database connection objects.
  5. Scratch memory allocations that overflow into the general-purpose memory allocator.
  6. Page cache memory allocations that overflow into the general-purpose memory allocator.
  7. Lookaside buffer allocations for new database connections.

The last three allocations can be controlled and/or eliminated by configuring the scratch memory allocator, pagecache memory allocator, and lookaside memory allocator appropriately, as described above. The storage space required for database connection objects depends to some extent on the length of the filename of the database file, but rarely exceeds 2KB on 32-bit systems. (More space is required on 64-bit systems due to the increased size of pointers.) Each parser object uses about 1.6KB of memory. Thus, elements 3 through 7 above can easily be controlled to keep the maximum memory allocation size below 2KB.

If the application is designed to manage data in small pieces, then the database should never contain any large strings or BLOBs and hence element 1 above should not be a factor. If the database does contain large strings or BLOBs, they should be read using incremental BLOB I/O and rows that contain the large strings or BLOBs should never be update by any means other than incremental BLOB I/O. Otherwise, the sqlite3_step() routine will need to read the entire row into contiguous memory at some point, and that will involve at least one large memory allocation.

The final source of large memory allocations is the space to hold the prepared statements that result from compiling complex SQL operations. Ongoing work by the SQLite developers is reducing the amount of space required here. But large and complex queries might still require prepared statements that are several kilobytes in size. The only workaround at the moment is for the application to break complex SQL operations up into two or more smaller and simpler operations contained in separate prepared statements.

All things considered, applications should normally be able to hold their maximum memory allocation size below 2K or 4K. This gives a value for log2(n) of 2 or 3. This will limit N to between 2 and 2.5 times M.

The maximum amount of general-purpose memory needed by the application is determined by such factors as how many simultaneous open database connection and prepared statement objects the application uses, and on the complexity of the prepared statements. For any given application, these factors are normally fixed and can be determined experimentally using SQLITE_STATUS_MEMORY_USED. A typical application might only use about 40KB of general-purpose memory. This gives a value of N of around 100KB.

4.2 Ductile failure

If the memory allocation subsystems within SQLite are configured for breakdown-free operation but the actual memory usage exceeds design limits set by the Robson proof, SQLite will usually continue to operate normally. The scratch memory allocator, the pagecache memory allocator, and the lookaside memory allocator all automatically failover to the memsys5 general-purpose memory allocator. And it is usually the case that the memsys5 memory allocator will continue to function without fragmentation even if M and/or n exceeds the limits imposed by the Robson proof. The Robson proof shows that it is possible for a memory allocation to break down and fail in this circumstance, but such a failure requires an especially despicable sequence of allocations and deallocations - a sequence that SQLite has never been observed to follow. So in practice it is usually the case that the limits imposed by Robson can be exceeded by a considerable margin with no ill effect.

Nevertheless, application developers are admonished to monitor the state of the memory allocation subsystems and raise alarms when memory usage approaches or exceeds Robson limits. In this way, the application will provide operators with abundant warning well in advance of failure. The memory statistics interfaces of SQLite provide the application with all the mechanism necessary to complete the monitoring portion of this task.

5.0 Stability Of Memory Interfaces

As of this writing (circa SQLite version 3.6.1) all of the alternative memory allocators and mechanisms for manipulating, controlling, and measuring memory allocation in SQLite are considered experimental and subject to change from one release to the next. These interfaces are in the process of being refined to work on a wide variety of systems under a range of constraints. The SQLite developers need the flexibility to change the memory allocator interfaces in order to best meet the needs of a wide variety of systems.

One may anticipate that the memory allocator interfaces will eventually stabilize. Appropriate notice will be given when that occurs. In the meantime, applications developers who make use of these interfaces need to be prepared to modify their applications to accommodate changes in the SQLite interface.

Update: As of SQLite version 3.7.0, all of these interfaces are considered stable

6.0 Summary Of Memory Allocator Interfaces

To be completed...


No Title

Choose any three.
About Sitemap Documentation Download License News Support

Notes On How To Build MinGW As A Cross-Compiler

MinGW, also known as Minimalist GNU For Windows, is a version of the popular GCC compiler that builds Win95/Win98/WinNT binaries. See the website for details.

This page describes how you can build MinGW from sources as a cross-compiler running under Linux. Doing so will allow you to construct WinNT binaries from the comfort and convenience of your Unix desktop.

Here are the steps:

  1. Get a copy of source code. You will need the binutils, the compiler, and the MinGW runtime. Each are available separately. As of this writing, Mumit Khan has collected everything you need together in one FTP site: ftp://ftp.nanotech.wisc.edu/pub/khan/gnu-win32/mingw32/snapshots/gcc-2.95.2-1 The three files you will need are:

    • binutils-19990818-1-src.tar.gz
    • gcc-2.95.2-1-src.tar.gz
    • mingw-20000203.zip

    Put all the downloads in a directory out of the way. The sequel will assume all downloads are in a directory named ~/mingw/download.

  2. Create a directory in which to install the new compiler suite and make the new directory writable. Depending on what directory you choose, you might need to become root. The example shell commands that follow will assume the installation directory is /opt/mingw and that your user ID is drh.

    su
mkdir /opt/mingw
chown drh /opt/mingw
exit

  3. Unpack the source tarballs into a separate directory.

    mkdir ~/mingw/src
cd ~/mingw/src
tar xzf ../download/binutils-*.tar.gz
tar xzf ../download/gcc-*.tar.gz
unzip ../download/mingw-*.zip

  4. Create a directory in which to put all the build products.

    mkdir ~/mingw/bld

  5. Configure and build binutils and add the results to your PATH.

    mkdir ~/mingw/bld/binutils
cd ~/mingw/bld/binutils
../../src/binutils/configure --prefix=/opt/mingw --target=i386-mingw32 -v
make 2>&1 | tee make.out
make install 2>&1 | tee make-install.out
export PATH=$PATH:/opt/mingw/bin

  6. Manually copy the runtime include files into the installation directory before trying to build the compiler.

    mkdir /opt/mingw/i386-mingw32/include
cd ~/mingw/src/mingw-runtime*/mingw/include
cp -r * /opt/mingw/i386-mingw32/include

  7. Configure and build the compiler

    mkdir ~/mingw/bld/gcc
cd ~/mingw/bld/gcc
../../src/gcc-*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
cd gcc
make installdirs
cd ..
make 2>&1 | tee make.out
make install

  8. Configure and build the MinGW runtime

    mkdir ~/mingw/bld/runtime
cd ~/mingw/bld/runtime
../../src/mingw-runtime*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
make install-target-w32api
make install

And you are done...


Most Widely Deployed SQL Database Engine

Choose any three.
About Sitemap Documentation Download License News Support

Most Widely Deployed SQL Database

We believe that there are more copies of SQLite in use around the world than any other SQL database engine, and possibly all other SQL database engines combined. We cannot be certain of this since we have no way of measuring either the number of SQLite deployments nor the number of deployments of other databases. But we believe the claim is defensible.

The belief that SQLite is the most widely deployed SQL database engine stems from its use as an embedded database. Other database engines, such as MySQL, PostgreSQL, or Oracle, are typically found one to a server. And usually a single server can serve multiple users. With SQLite, on the other hand, a single user will typically have exclusive use of multiple copies of SQLite. SQLite is used on servers, but it is also used on desktop PC, and in cellphones, and PDAs, and MP3-players, and set-top boxes.

Estimates

At the end of 2006, there were 100 million websites on the internet. [1] Let us use that number as a proxy for the number of deployed SQL database engines other than SQLite. Not every website runs an SQL database engine and not every SQL database engine runs a website. Larger websites run multiple database engines. But the vast majority of smaller websites (the long tail) share a database engine with several other websites, if they use a database engine at all. And many large SQL database installations have nothing to do with websites. So using the number of websites as a surrogate for the number of operational SQL database engines is a crude approximation, but it is the best we have so we will go with it. (Readers are encouraged to submit better estimates.)

Now let's consider where SQLite is used:

  • 300 million copies of Mozilla Firefox.
  • 20 million Mac computers, each of which contains multiple copies of SQLite
  • 20 million websites run PHP which has SQLite built in. [3] We have no way of estimating what fraction of those sites actively use SQLite, but we think it is a significant fraction.
  • 450 million registered Skype users.
  • 20 million Symbian smartphones shipped in Q3 2007 [5] Newer versions of the SymbianOS have SQLite built in. It is unclear exactly how many Symbian phones actually contain SQLite, so we will use a single quarter's sales as a lower bound.
  • 10 million Solaris 10 installations, all of which require SQLite in order to boot.
  • Millions and millions of copies of McAfee anti-virus software all use SQLite internally.
  • Millions of iPhones use SQLite
  • Millions and millions of other cellphones from manufactures other than Symbian and Apple use SQLite. This has not been publicly acknowledged by the manufactures but it is known to the SQLite developers.
  • There are perhaps millions of additional deployments of SQLite that the SQLite developers do not know about.

By these estimates, we see at least 500 million SQLite deployments and about 100 million deployments of other SQL database engines. These estimates are obviously very rough and may be off significantly. But there is a wide margin. So the SQLite developers think it is likely that SQLite is the most widely deployed SQL database engine in the world.


Recent SQLite News

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

Recent News

2011-November-01 - Version 3.7.9

SQLite version 3.7.9 is a regularly scheduled maintenance release. Upgrading from version 3.7.6.3, 3.7.7, 3.7.7.1, and 3.7.8 is optional. Upgrading from other versions is recommended.

The SQLITE_ENABLE_STAT2 compile-time option is no a no-op. The enhanced query-planner functionality formerly available using SQLITE_ENABLE_STAT2 is now available through SQLITE_ENABLE_STAT3. The enhanced query planning is still disabled by default. However, future releases of SQLite might convert STAT3 from and enable-option to a disable-option so that it is available by default and is only omitted upon request.

The FTS4 full-text search engine has been enhanced such that tokens in the search string that begin with "" must be the first token in their respective columns in order to match. Formerly, "" characters in the search string were simply ignored. Hence, if a legacy application was including "" characters in FTS4 search strings, thinking that they would always be ignored, then those legacy applications might break with this update. The fix is simply remove the "" characters from the search string.

See the change summary for additional changes associated with this release.

2011-September-19 - Version 3.7.8

SQLite version 3.7.8 is a quarterly maintenance release. Upgrading from versions 3.7.6.3, 3.7.7, or 3.7.7.1 is optional. Upgrading from other versions is recommended.

This release features a new "external merge sort" algorithm used to implement ORDER BY and GROUP BY and also to presort the content of an index for CREATE INDEX. The new algorithm does approximately the same number of comparisons and I/Os as before, but the I/Os are much more sequential and so runtimes are greatly reduced when the size of the set being sorted is larger than the filesystem cache. The performance improvement can be dramatic - orders of magnitude faster for large CREATE INDEX commands. On the other hand, the code is slightly slower (1% or 2%) for a small CREATE INDEX. Since CREATE INDEX is not an operation that commonly occurs on a speed-critical path, we feel that this tradeoff is a good one. The slight slowdown for small CREATE INDEX statements might be recovered in a future release. ORDER BY and GROUP BY operations should now be faster for all cases, large and small.

The query planner has been enhanced to do a better job of handling the DISTINCT keyword on SELECT statements.

There has been a lot of work on the default VFSes. The unix VFS has been enhanced to include more overrideable system calls - a feature requested by Chromium to make it easier to build SQLite into a sandbox. The windows VFS has been enhanced to be more resistant to interference from anti-virus software.

Every version of SQLite is better tested than the previous, and 3.7.8 is no exception to this rule. Version 3.7.8 has been used internally by the SQLite team for mission critical functions and has performed flawlessly. And, of course, it passes our rigorous testing procedures with no problems detected. Version 3.7.8 is recommended for all new development.

2011-June-28 - Version 3.7.7.1

SQLite version 3.7.7.1 adds a one-line bug fix to 3.7.7 to fix a problem causing PRAGMA case_sensitive_like statements compiled using the legacy sqlite3_prepare() interface to fail with an SQLITE_SCHEMA error. Because sqlite3_exec() uses sqlite3_prepare() internally, the problem also affects sqlite3_exec().

Upgrading from 3.7.7 is only required for applications that use "PRAGMA case_sensitive_like" and the sqlite3_prepare() (or sqlite3_exec()) interface.

2011-June-24 - Version 3.7.7

SQLite version 3.7.7 is a regularly scheduled bi-monthly maintenance release. Upgrading from version 3.7.6.3 is optional. Upgrading from all prior releases is recommended.

This release adds support for naming database files using URI filenames. URI filenames are disabled by default (for backwards compatibility) but applications are encouraged to enable them since incompatibilities are likely to be exceedingly rare and the feature is useful. See the URI filename documentation for details.

Most of the other enhancements in this release involve virtual tables. The virtual table interface has been enhanced to support SAVEPOINT and ON CONFLICT clause processing, and the built-in RTREE and FTS3/FTS4 have been augmented to take advantage of the new capability. This means, for example, that it is now possible to use the REPLACE command on FTS3/FTS4 and RTREE tables.

The FTS4 full-text index extension has been enhanced to support the FTS4 prefix option and the FTS4 order option. These two enhancements are provided in support of search-as-you-type interfaces where search results begin to appear after the first keystroke in the "search" box and are refined with each subsequent keystroke. The way this is done is to do a separate full-text search after each key stroke, and add the "*" wildcard at the end of the word currently being typed. So, for example, if the text typed so far is "fast da" and the next character typed is "t", then the application does a full-text search of the pattern "fast dat*" and displays the results. Such capability has always existed. What is new is that the FTS4 prefix option allows the search to be very fast (a matter of milliseconds) even for difficult cases such as "t*" or "th*".

There has been a fair amount of work done on the FTS4 module for this release. But the core SQLite code has changed little and the previous release has not given any problems, so we expect this to be a very stable release.

2011-May-19 - Version 3.7.6.3

SQLite version 3.7.6.3 is a patch release that fixes a single bug associated with WAL mode. The bug has been in SQLite ever since WAL was added, but the problem is very obscure and so nobody has noticed before now. Nevertheless, all users are encouraged to upgrade to version 3.7.6.3 or later.

The bug is this: If the cache_size is set very small (less than 10) and SQLite comes under memory pressure and if a multi-statement transaction is started in which the last statement prior to COMMIT is a SELECT statement and if a checkpoint occurs right after the transaction commit, then it might happen that the transaction will be silently rolled back instead of being committed.

The default setting for cache_size is 2000. So in most situations, this bug will never appear. But sometimes programmers set cache_size to very small values on gadgets and other low-memory devices in order to save memory space. Such applications are vulnerable. Note that this bug does not cause database corruption. It is as if ROLLBACK were being run instead of COMMIT in some cases.

Bug Details

Transactions commit in WAL mode by adding a record onto the end of the WAL (the write-ahead log) that contains a "commit" flag. So to commit a transaction, SQLite takes all the pages that have changed during that transaction, appends them to the WAL, and sets the commit flag on the last page. Now, if SQLite comes under memory pressure, it might try to free up memory space by writing changed pages to the WAL prior to the commit. We call this "spilling" the cache to WAL. There is nothing wrong with spilling cache to WAL. But if the memory pressure is severe, it might be that by the time COMMIT is run, all changed pages for the transaction have already been spilled to WAL and there are no pages left to be written to WAL. And with no unwritten pages, there was nothing to put the commit flag on. And without a commit flag, the transaction would end up being rolled back.

The fix to this problem was that if all changed pages has already been written to the WAL when the commit was started, then page 1 of the database will be written to the WAL again, so that there will always be a page available on which to set the commit flag.

2011-April-17 - Version 3.7.6.2

SQLite version 3.7.6.2 adds a one-line bug fix to 3.7.6.1 that enables pthreads to work correctly on NetBSD. The problem was a faulty function signature for the open system call. The problem does not appear to have any adverse impact on any system other than NetBSD.

Upgrading from version 3.7.6.1 is only needed on NetBSD.

2011-April-13 - Version 3.7.6.1

SQLite version 3.7.6.1 fixes a single bug in 3.7.6 that can cause a segfault if SQLITE_FCNTL_SIZE_HINT is used on a unix build that has SQLITE_ENABLE_LOCKING_MODE set to 0 and is compiled with HAVE_POSIX_FALLOCATE.

Upgrading from 3.7.6 is only needed for users effected by the configuration-specific bug described above. There are no other changes to the code.

2011-April-12 - Version 3.7.6

SQLite version 3.7.6 is a regularly scheduled bi-monthly maintenance release of SQLite. Upgrading from version 3.7.5 is optional. Upgrading releases prior to 3.7.5 is recommended.

2011-February-01 - Version 3.7.5

SQLite version 3.7.5 is a regularly scheduled bi-monthly maintenance release of SQLite. Due to the discovery and fix of an obscure bug that could cause database corruption, upgrading from all prior releases of SQLite is recommended. This bug was found during code review and has not been observed in the wild.

This release adds new opcodes for the sqlite3_db_status() interface that allow more precise measurement of how the lookaside memory allocator is performing, which can be useful for tuning in applications with very tight memory constraints.

The sqlite3_vsnprintf() interface was added. This routine is simply a varargs version of the long-standing sqlite3_snprintf() interface.

The output from sqlite3_trace() interface has been enhanced to work better (and faster) in systems that use recursive extensions such as FTS3 or RTREE.

Testing with Valgrind shows that this release of SQLite is about 1% or 2% faster than the previous release for most operations.

A fork of the popular ADO.NET adaptor for SQLite known as System.Data.SQLite is now available on http://System.Data.SQLite.org/. The originator of System.Data.SQLite, Robert Simpson, is aware of this fork, has expressed his approval, and has commit privileges on the new Fossil repository. The SQLite development team intends to maintain System.Data.SQLite moving forward.

2010-December-08 - Version 3.7.4

SQLite version 3.7.4 is a regularly scheduled bi-monthly maintenance release of SQLite. Upgrading from version 3.7.2 and version 3.7.3 is optional. Upgrading from all other SQLite releases is recommended.

This release features full-text search enhancements. The older FTS3 virtual table is still fully supported, and should also run faster. In addition, the new FTS4 virtual table is added. FTS4 follows the same syntax as FTS3 but holds additional metadata which facilitates some performance improvements and more advanced matchinfo() output. Look for further full-text search enhancements in subsequent releases.

Also in this release, the EXPLAIN QUERY PLAN output has been enhanced and new documentation is provided so that application developers can more easily understand how SQLite is performing their queries.

Thanks to an account from the folks at http://www.devio.us/, OpenBSD has been added to the list of platforms upon which we test SQLite prior to every release. That list of platforms now includes:

  • Linux x86 & x86_64
  • MacOS 10.5 & 10.6
  • MacOS 10.2 PowerPC
  • WinXP and Win7
  • Android 2.2
  • OpenBSD 4.7

The previous release of SQLite (version 3.7.3) has proven to be very robust. The only serious issue discovered was ticket 80ba201079 that describes an incorrect query result that can occur under very unusual circumstances. The ticket description contains details of the problem. Suffice it to say here that the problem is very obscure and is unlikely to effect most applications and so upgrading is optional. The problem is fixed, of course, in this release.

2010-October-08 - Version 3.7.3

SQLite version 3.7.3 is a regularly scheduled bi-monthly maintenance release of SQLite. Upgrading from version 3.7.2 is optional. Upgrading from all other releases is recommended.

This release adds two new interfaces (really just variations on existing interfaces). The sqlite3_create_function_v2() interface adds a destructor for the application-data pointer. The new sqlite3_soft_heap_limit64() interface allows the soft heap limit to be set to a value greater than 231.

The RTREE extension has been enhanced with the ability to have an application-defined query region. This might be used, for example, to locate all objects within the field of view of a camera.

The 3.7.3 release also includes some performance enhancements, including query planner improvements, documentation updates, and fixes to some very obscure bugs.

2010-August-24 - Version 3.7.2

SQLite version 3.7.2 fixes a long-standing bug that can cause the database free-page list to go corrupt if incremental_vacuum is used multiple times to partially reduce the size of a database file that contains many hundreds of unused database pages. The original bug reports together with links to the patch that fixes it can be seen here.

This bug has been in the code for at least a year and possibly longer. The bug has nothing to do with the versions 3.7.1 or 3.7.0 or any other recent release. The fact that the bug was discovered (and fixed) within hours of the 3.7.1 release is purely a coincidence.

The bug is impossible to hit without using incremental_vacuum and is very difficult to hit even with incremental_vacuum. And the kind of corruption that the bug causes can usually be fixed simply by running VACUUM. Nevertheless, because the bug can result in database corruption, it is recommended that all SQLite users upgrade to version 3.7.2 or later.

2010-August-23 - Version 3.7.1

SQLite version 3.7.1 is a stabilization release for the 3.7.x series. Other than the filesize-in-header bug that was fixed in version 3.7.0.1, no major problems have been seen in 3.7.0. Some minor corner-case performance regressions have been fixed. A typo in the OS/2 interface has been repaired.

A biggest part of the 3.7.1 release is a cleanup and refactoring of the pager module within SQLite. This refactoring should have no application-visible effects. The purpose was to reorganize the code in ways that make it easier to prove correctness.

The 3.7.1 release adds new experimental methods for obtained more detailed memory usage information and for controlling database file fragmentation. And the query planner now does a better job of optimizing the LIKE and GLOB operators.

This release increases the maximum size of database pages from 32KiB to 64KiB. A database with 64KiB pages will not be readable or writable by older versions of SQLite. Note that further increases in page size are not feasible since the file format uses 16-bit offsets to structures within each page.

2010-August-04 - Version 3.7.0.1

SQLite version 3.7.0.1 is a patch release to fix a bug in the new filesize-in-header feature of the SQLite file format that could cause database corruption if the same database file is written alternately with version 3.7.0 and version 3.6.23.1 or earlier. A performance regression was also fixed in this release.

2010-July-22 - Version 3.7.0

SQLite version 3.7.0 is a major release of SQLite that features a new transaction control mechanism using a write-ahead log or WAL. The traditional rollback-journal is still used as the default so there should be no visible change for legacy programs. But newer programs can take advantage of improved performance and concurrency by enabling the WAL journaling mode.

SQLite version 3.7.0 also contains some query planner enhancements and a few obscure bug fixes, but the only really big change is the addition of WAL mode.

Old news...


NULL Handling in SQLite

Choose any three.
About Sitemap Documentation Download License News Support

NULL Handling in SQLite Versus Other Database Engines

The goal is to make SQLite handle NULLs in a standards-compliant way. But the descriptions in the SQL standards on how to handle NULLs seem ambiguous. It is not clear from the standards documents exactly how NULLs should be handled in all circumstances.

So instead of going by the standards documents, various popular SQL engines were tested to see how they handle NULLs. The idea was to make SQLite work like all the other engines. An SQL test script was developed and run by volunteers on various SQL RDBMSes and the results of those tests were used to deduce how each engine processed NULL values. The original tests were run in May of 2002. A copy of the test script is found at the end of this document.

SQLite was originally coded in such a way that the answer to all questions in the chart below would be "Yes". But the experiments run on other SQL engines showed that none of them worked this way. So SQLite was modified to work the same as Oracle, PostgreSQL, and DB2. This involved making NULLs indistinct for the purposes of the SELECT DISTINCT statement and for the UNION operator in a SELECT. NULLs are still distinct in a UNIQUE column. This seems somewhat arbitrary, but the desire to be compatible with other engines outweighed that objection.

It is possible to make SQLite treat NULLs as distinct for the purposes of the SELECT DISTINCT and UNION. To do so, one should change the value of the NULL_ALWAYS_DISTINCT #define in the sqliteInt.h source file and recompile.

Update 2003-07-13: Since this document was originally written some of the database engines tested have been updated and users have been kind enough to send in corrections to the chart below. The original data showed a wide variety of behaviors, but over time the range of behaviors has converged toward the PostgreSQL/Oracle model. The only significant difference is that Informix and MS-SQL both treat NULLs as indistinct in a UNIQUE column.

The fact that NULLs are distinct for UNIQUE columns but are indistinct for SELECT DISTINCT and UNION continues to be puzzling. It seems that NULLs should be either distinct everywhere or nowhere. And the SQL standards documents suggest that NULLs should be distinct everywhere. Yet as of this writing, no SQL engine tested treats NULLs as distinct in a SELECT DISTINCT statement or in a UNION.

The following table shows the results of the NULL handling experiments.

 | SQLite | PostgreSQL | Oracle | Informix | DB2 | MS-SQL | OCELOT
Adding anything to null gives null | Yes | Yes | Yes | Yes | Yes | Yes | Yes
Multiplying null by zero gives null | Yes | Yes | Yes | Yes | Yes | Yes | Yes
nulls are distinct in a UNIQUE column | Yes | Yes | Yes | No | (Note 4) | No | Yes
nulls are distinct in SELECT DISTINCT | No | No | No | No | No | No | No
nulls are distinct in a UNION | No | No | No | No | No | No | No
"CASE WHEN null THEN 1 ELSE 0 END" is 0? | Yes | Yes | Yes | Yes | Yes | Yes | Yes
"null OR true" is true | Yes | Yes | Yes | Yes | Yes | Yes | Yes
"not (null AND false)" is true | Yes | Yes | Yes | Yes | Yes | Yes | Yes
 | MySQL 3.23.41 | MySQL 4.0.16 | Firebird | SQL Anywhere | Borland Interbase
Adding anything to null gives null | Yes | Yes | Yes | Yes | Yes
Multiplying null by zero gives null | Yes | Yes | Yes | Yes | Yes
nulls are distinct in a UNIQUE column | Yes | Yes | Yes | (Note 4) | (Note 4)
nulls are distinct in SELECT DISTINCT | No | No | No (Note 1) | No | No
nulls are distinct in a UNION | (Note 3) | No | No (Note 1) | No | No
"CASE WHEN null THEN 1 ELSE 0 END" is 0? | Yes | Yes | Yes | Yes | (Note 5)
"null OR true" is true | Yes | Yes | Yes | Yes | Yes
"not (null AND false)" is true | No | Yes | Yes | Yes | Yes
Notes: | 1. | Older versions of firebird omits all NULLs from SELECT DISTINCT and from UNION.
 | 2. | Test data unavailable.
 | 3. | MySQL version 3.23.41 does not support UNION.
 | 4. | DB2, SQL Anywhere, and Borland Interbase do not allow NULLs in a UNIQUE column.
 | 5. | Borland Interbase does not support CASE expressions.

The following script was used to gather information for the table above.

-- I have about decided that SQL's treatment of NULLs is capricious and cannot be
-- deduced by logic.  It must be discovered by experiment.  To that end, I have
-- prepared the following script to test how various SQL databases deal with NULL.
-- My aim is to use the information gather from this script to make SQLite as much
-- like other databases as possible.
--
-- If you could please run this script in your database engine and mail the results
-- to me at drh@hwaci.com, that will be a big help.  Please be sure to identify the
-- database engine you use for this test.  Thanks.
--
-- If you have to change anything to get this script to run with your database
-- engine, please send your revised script together with your results.
--

-- Create a test table with data
create table t1(a int, b int, c int);
insert into t1 values(1,0,0);
insert into t1 values(2,0,1);
insert into t1 values(3,1,0);
insert into t1 values(4,1,1);
insert into t1 values(5,null,0);
insert into t1 values(6,null,1);
insert into t1 values(7,null,null);

-- Check to see what CASE does with NULLs in its test expressions
select a, case when b<>0 then 1 else 0 end from t1;
select a+10, case when not b<>0 then 1 else 0 end from t1;
select a+20, case when b<>0 and c<>0 then 1 else 0 end from t1;
select a+30, case when not (b<>0 and c<>0) then 1 else 0 end from t1;
select a+40, case when b<>0 or c<>0 then 1 else 0 end from t1;
select a+50, case when not (b<>0 or c<>0) then 1 else 0 end from t1;
select a+60, case b when c then 1 else 0 end from t1;
select a+70, case c when b then 1 else 0 end from t1;

-- What happens when you multiple a NULL by zero?
select a+80, b*0 from t1;
select a+90, b*c from t1;

-- What happens to NULL for other operators?
select a+100, b+c from t1;

-- Test the treatment of aggregate operators
select count(*), count(b), sum(b), avg(b), min(b), max(b) from t1;

-- Check the behavior of NULLs in WHERE clauses
select a+110 from t1 where b<10;
select a+120 from t1 where not b>10;
select a+130 from t1 where b<10 OR c=1;
select a+140 from t1 where b<10 AND c=1;
select a+150 from t1 where not (b<10 AND c=1);
select a+160 from t1 where not (c=1 AND b<10);

-- Check the behavior of NULLs in a DISTINCT query
select distinct b from t1;

-- Check the behavior of NULLs in a UNION query
select b from t1 union select b from t1;

-- Create a new table with a unique column.  Check to see if NULLs are considered
-- to be distinct.
create table t2(a int, b int unique);
insert into t2 values(1,1);
insert into t2 values(2,null);
insert into t2 values(3,null);
select * from t2;

drop table t1;
drop table t2;


SQLite Older News

Choose any three.
About Sitemap Documentation Download License News Support

2010-Mar-30 - Version 3.6.23.1

SQLite version 3.6.23.1 is a patch release to fix a bug in the offsets() function of FTS3 at the request of the Mozilla.

2010-Mar-09 - Version 3.6.23

SQLite version 3.6.23 is a regular bimonthly release of SQLite. Upgrading from the prior release is purely optional.

This release contains new pragmas: the secure_delete pragma, and the compile_options pragma. There are a new SQL functions: sqlite_compileoption_used() and sqlite_compileoption_get(). New C/C++ interfaces: sqlite3_compileoption_used(), sqlite3_compileoption_get(), SQLITE_CONFIG_LOG, and sqlite3_log().

This release also includes several minor bug fixes and performance improvements. Support for SQLITE_OMIT_FLOATING_POINT is enhanced. There are on-going improvements to FTS3.

The ".genfkey" command in the Command Line Interface has been removed. SQLite has supported standard SQL foreign key constraints since version 3.6.19 and so the ".genfkey" command was seen as an anachronism.

2010-Jan-06 - Version 3.6.22

SQLite version 3.6.22 is a bug-fix release. Two bugs have been fixed that might cause incorrect query results.
  • Ticket 31338dca7e describes a problem with queries that have a WHERE clause of the form (x AND y) OR z where x and z come from one table of a join and y comes from a different table.
  • Ticket eb5548a849 describes a problem where the use of the CAST operator in the WHERE clause can lead to incorrect results if the column being cast to a new datatype is also used in the same WHERE clause without being cast.
Both bugs are obscure, but because they could arise in an application after deployment, it is recommended that all applications upgrade SQLite to version 3.6.22.

This release also includes other minor bug fixes and performance enhancements, especially in the FTS3 extension.

2009-Dec-07 - Version 3.6.21

SQLite version 3.6.21 focuses on performance optimization. For a certain set of traces, this version uses 12% fewer CPU instructions than the previous release (as measured by Valgrind). In addition, the FTS3 extension has been through an extensive cleanup and rework and the sqlite3_trace() interface has been modified to insert bound parameter values into its output.

2009-Nov-04 - Version 3.6.20

SQLite version 3.6.20 is a general maintenance release. The query planner has been enhanced to work better with bound parameters in LIKE and GLOB operators and in range constraints and various minor bugs have been fixed. Upgrading from 3.6.19 is optional.

2009-Oct-14 - Version 3.6.19

SQLite version 3.6.19 adds native support for foreign key constraints, including deferred constraints and cascading deletes. Enforcement of foreign keys is disabled by default for backwards compatibility and must be turned on using the foreign_keys pragma.

Version 3.6.19 also adds support for the IS and IS NOT operators. Formerly, SQLite (as most other SQL database engines) supported IS NULL and IS NOT NULL. The IS and IS NOT operators are generalizations that allow the right-hand side to be an arbitrary expression. IS and IS NOT work the same as == (equals) and != (not equals) except that with IS and IS NOT the NULL values compare equal to one another.

2009-Sep-11 - Version 3.6.18

Beginning with this release, the SQLite source code is tracked and managed using the Fossil distributed configuration management system. SQLite was previously versioned using CVS. The entire CVS history has been imported into Fossil. The older CVS repository remains on the website but is read-only.

There are two major enhancements in SQLite version 3.6.18. The first is a series or refinements to the query planner that help SQLite to choose better plans for joins where in the past it was selecting suboptimal query plans. The SQLITE_ENABLE_STAT2 compile-time option has been added to cause SQLite to collect histogram data on indices when the ANALYZE command is run. The use of histograms improve the query planning performance even more.

The second major enhancement is that SQLite now support recursive triggers. The older non-recursive behavior of triggers is still the default behavior. Recursive triggers are activated using the recursive_triggers pragma. In addition to allowing triggers to call themselves (either directly or indirectly) the new capability also fires DELETE triggers on rows that are removed from a table as a result of REPLACE conflict resolution processing.

Non-recursive triggers are still the default behavior since this is least likely to cause problems for existing applications. However, we anticipate that triggers will become recursive by default beginning with release 3.7.0. At that point, applications that want to continue using the older non-recursive trigger behavior will need to use the recursive_triggers pragma to disable recursive triggers.

This version of SQLite also contains bug fixes, though none of the bugs are serious and all are obscure, so upgrading is optional.

The SQLite core continues to have 100% branch test coverage and so despite the many changes in this release, the developers believe that this version of SQLite is stable and ready for production use.

2009-Aug-10 - Version 3.6.17

This is a monthly maintenance release with a focus of bug fixes, performance improvements, and increased test coverage. This is the first release of SQLite since 100% branch test coverage was achieved on the SQLite core.

In addition, a new interface sqlite3_strnicmp() is provided for the convenience of extension writers.

None of the bugs fixed in this release are serious. All bugs are obscure. Upgrading is optional.

2009-July-25 - 100% Branch Test Coverage

A subset of the TH3 test suite was measured by gcov to provide 100% branch test coverage over the SQLite core (exclusive of the VFS backend and of extensions such as FTS3 and RTREE) when compiled for SuSE 10.1 Linux on x86. The SQLite developers pledge to maintain branch test coverage at 100% in all future releases. Ongoing work will strive for 100% branch test coverage on the operating-system backends and extensions as well.

2009-Jun-27 - Version 3.6.16

SQLite version 3.6.16 is another general maintenance release containing performance and robustness enhancements. A single notable bug was fixed (ticket #3929). This bug cause cause INSERT or UPDATE statements to fail on indexed tables that have AFTER triggers that modify the same table and index.

2009-Jun-15 - Version 3.6.15

SQLite version 3.6.15 is a general maintenance release containing performance and robustness enhancements and fixes for various obscure bugs.

2009-May-25 - Version 3.6.14.2

SQLite version 3.6.14.2 fixes an obscure bug in the code generator (ticket #3879) section of SQLite which can potentially cause incorrect query results. The changes from the prior release consist of only this one bug fix, check-in [6676] and a change to the version number text.

The bug was introduced in version 3.6.14. It is recommended that users of version 3.6.14 and 3.6.14.1 upgrade to this release. Applications are unlikely to hit this bug, but since it is difficult to predict which applications might hit it and which might not, we recommend that all users of 3.6.14 and 3.5.14.1 upgrade to this release.

2009-May-19 - Version 3.6.14.1

SQLite version 3.6.14.1 is a patch release to version 3.6.14 with minimal changes that fixes three bugs. Upgrading is only necessary for users who are impacted by one or more of those bugs.

2009-May-07 - Version 3.6.14

SQLite version 3.6.14 provides new performance enhancements in the btree and pager layers and in the query optimizer. Certain workloads can be as much as twice as fast as the previous release, though 10% faster is a more typical result.

Queries against virtual tables that contain OR and IN operators in the WHERE clause are now able to use indexing.

A new optional asynchronous I/O backend is available for unix and windows. The asynchronous backend gives the illusion of faster response time by pushing slow write operations into a background thread. The tradeoff for faster response time is that more memory is required (to hold the content of the pending writes) and if a power failure or program crash occurs, some transactions that appeared to have committed might end up being rolled back upon restart.

This release also contains many minor bug fixes, documentation enhancements, new test cases, and cleanups and simplifications to the source code.

There is no compelling reason to upgrade from versions 3.6.12 or 3.6.13 if those prior versions are working. Though many users may benefit from the improved performance.

2008-Dec-16 - Version 3.6.7

SQLite version 3.6.7 contains a major cleanup of the Unix driver, and support for the new Proxy Locking mechanism on Mac OS X. Though the Unix driver is reorganized, its functionality is the same and so applications should not notice a difference.

2008-Nov-26 - Version 3.6.6.2

This release fixes a bug that was introduced into SQLite version 3.6.6 and which seems like it might be able to cause database corruption. This bug was detected during stress testing. It has not been seen in the wild. An analysis of the problem suggests that the bug might be able to cause database corruption, however focused efforts to find a real-world test cases that actually causes database corruption have so far been unsuccessful. Hence, the likelihood of this bug causing problems is low. Nevertheless, we have decided to do an emergency branch release out of an abundance of caution.

The version 3.6.6.2 release also fixes an obscure memory leak that can occur following a disk I/O error.

2008-Nov-22 - Version 3.6.6.1

This release fixes a bug that was introduced into SQLite version 3.6.4 and that can cause database corruption in obscure cases. This bug has never been seen in the wild; it was first detected by internal stress tests and required substantial analysis before it could be shown to potentially lead to corruption. So we feel that SQLite versions 3.6.4, 3.6.5, and 3.6.6 are safe to use for development work. But upgrading to this patch release or later is recommended prior to deploying products that incorporate SQLite.

We have taken the unusual step of issuing a patch release in order to get the fix for this bug into circulation quickly. SQLite version 3.6.7 will continue on its normal path of development with an anticipated release in mid December.

2008-Nov-19 - Version 3.6.6

SQLite version 3.6.5 is released. This is a quick turn-around release that fixes a bug in virtual tables and FTS3 that snuck into version 3.6.5. This release also adds the new application-defined page cache mechanism.

2008-Nov-12 - Version 3.6.5

SQLite version 3.6.5 is released. There are various minor feature enhancements and numerous obscure bug fixes. The change log contains the details. Upgrading is optional.

2008-Nov-01 - Bloomberg Joins SQLite Consortium

The SQLite developers are honored to announce that Bloomberg has joined the SQLite Consortium.

2008-Oct-15 - Version 3.6.4

SQLite version 3.6.4 adds new features designed to help applications detect when indices are not being used on query. There are also some important performance improvements. Upgrading is optional.

2008-Sep-22 - Version 3.6.3

SQLite version 3.6.3 fixes a bug in SELECT DISTINCT that was introduced by the previous version. No new features are added. Upgrading is recommended for all applications that make use of DISTINCT.

2008-Aug-30 - Version 3.6.2

SQLite version 3.6.2 contains rewrites of the page-cache subsystem and the procedures for matching identifiers to table columns in SQL statements. These changes are designed to better modularize the code and make it more maintainable and reliable moving forward. Nearly 5000 non-comment lines of core code (about 11.3%) have changed from the previous release. Nevertheless, there should be no application-visible changes, other than bug fixes.

2008-Aug-06 - Version 3.6.1

SQLite version 3.6.1 is a stabilization and performance enhancement release.

2008-July-16 - Version 3.6.0 beta

Version 3.6.0 makes changes to the VFS object in order to make SQLite more easily portable to a wider variety of platforms. There are potential incompatibilities with some legacy applications. See the 35to36.html document for details.

Many new interfaces are introduced in version 3.6.0. The code is very well tested and is appropriate for use in stable systems. We have attached the "beta" designation only so that we can make tweaks to the new interfaces in the next release without having to declare an incompatibility.

2008-May-12 - Version 3.5.9

Version 3.5.9 adds a new experimental PRAGMA: journal_mode. Setting the journal mode to PERSIST can provide performance improvement on systems where deleting a file is expensive. The PERSIST journal mode is still considered experimental and should be used with caution pending further testing.

Version 3.5.9 is intended to be the last stable release prior to version 3.6.0. Version 3.6.0 will make incompatible changes to the sqlite3_vfs VFS layer in order to address deficiencies in the original design. These incompatibilities will only effect programmers who write their own custom VFS layers (typically embedded device builders). The planned VFS changes will be much smaller than the changes that occurred on the 3.4.2 to 3.5.0 transaction that occurred last September.

This release of SQLite is considered stable and ready for production use.

2008-Apr-16 - Version 3.5.8

Version 3.5.8 includes some important new performance optimizations in the virtual machine code generator, including constant subexpression factoring and common subexpression elimination. This release also creates new public interfaces: sqlite3_randomness() provides access to SQLite's internal pseudo-random number generator, sqlite3_limit() allows size limits to be set at run-time on a per-connection basis, and sqlite3_context_db_handle() is a convenience routine that allows an application-defined SQL function implementation to retrieve its database connection handle.

This release of SQLite is considered stable and ready for production use.

2008-Mar-17 - Version 3.5.7

Version 3.5.7 fixes several minor and obscure bugs, especially in the autoconf-generated makefile. Upgrading is optional. This release of SQLite is considered stable and ready for production use.

2008-Feb-6 - Version 3.5.6

Version 3.5.6 fixes a minor regression in 3.5.5 - a regression that had nothing to do with the massive change of the virtual machine to a register-based design. No problems have been reported with the new virtual machine. This release of SQLite is considered stable and ready for production use.

2008-Jan-31 - Version 3.5.5

Version 3.5.5 changes over 8% of the core source code of SQLite in order to convert the internal virtual machine from a stack-based design into a register-based design. This change will allow future optimizations and will avoid an entire class of stack overflow bugs that have caused problems in the past. Even though this change is large, extensive testing has found zero errors in the new virtual machine and so we believe this to be a very stable release.

2007-Dec-14 - Version 3.5.4

Version 3.5.4 fixes a long-standing but obscure bug in UPDATE and DELETE which might cause database corruption. (See ticket #2832.) Upgrading is recommended for all users.

This release also brings the processing of ORDER BY statements into compliance with standard SQL. This could, in theory, cause problems for existing applications that depend on the older, buggy behavior. See ticket #2822 for additional information.

2007-Dec-12 - SQLite Consortium Announced

The SQLite Consortium was launched today with Mozilla and Symbian as charter members. As noted in the press release, the Consortium's goal is to promote the continuing vitality and independence of SQLite.

2007-Nov-27 - Version 3.5.3

This is an incremental release that fixes several minor problems. Upgrading is optional. If Version 3.5.2 or 3.5.1 is working fine for you, then there is no pressing need to change to 3.5.3.

The prebuilt binaries and the amalgamation found on the download page include the FTS3 fulltext search extension module. We are doing this on an experimental basis and are not promising to provide prebuilt binaries with FTS3 in the future.

2007-Nov-05 - Version 3.5.2

This is an incremental release that fixes several minor problems, adds some obscure features, and provides some performance tweaks. Upgrading is optional.

The experimental compile-time option SQLITE_OMIT_MEMORY_ALLOCATION is no longer supported. On the other hand, it is now possible to compile SQLite so that it uses a static array for all its dynamic memory allocation needs and never calls malloc. Expect to see additional radical changes to the memory allocation subsystem in future releases.

2007-Oct-04 - Version 3.5.1

Fix a long-standing bug that might cause database corruption if a disk-full error occurs in the middle of a transaction and that transaction is not rolled back. Ticket #2686.

The new VFS layer is stable. However, we still reserve the right to make tweaks to the interface definition of the VFS if necessary.

2007-Sep-04 - Version 3.5.0 alpha

The OS interface layer and the memory allocation subsystems in SQLite have been reimplemented. The published API is largely unchanged but the (unpublished) OS interface has been modified extensively. Applications that implement their own OS interface will require modification. See 34to35.html for details.

This is a large change. Approximately 10% of the source code was modified. We are calling this first release "alpha" in order to give the user community time to test and evaluate the changes before we freeze the new design.

2007-Aug-13 - Version 3.4.2

While stress-testing the soft_heap_limit feature, a bug that could lead to database corruption was discovered and fixed. Though the consequences of this bug are severe, the chances of hitting it in a typical application are remote. Upgrading is recommended only if you use the sqlite3_soft_heap_limit interface.

2007-Jly-20 - Version 3.4.1

This release fixes a bug in VACUUM that can lead to database corruption. The bug was introduced in version 3.3.14. Upgrading is recommended for all users. Also included are a slew of other more routine enhancements and bug fixes.

2007-Jun-18 - Version 3.4.0

This release fixes two separate bugs either of which can lead to database corruption. Upgrading is strongly recommended. If you must continue using an older version of SQLite, please at least read about how to avoid these bugs at CorruptionFollowingBusyError and ticket #2418

This release also adds explicit limits on the sizes and quantities of things SQLite will handle. The new limits might causes compatibility problems for existing applications that use excessively large strings, BLOBs, tables, or SQL statements. The new limits can be increased at compile-time to work around any problems that arise. Nevertheless, the version number of this release is 3.4.0 instead of 3.3.18 in order to call attention to the possible incompatibility.

There are also new features, including incremental BLOB I/O and incremental vacuum. See the change log for additional information.

2007-Apr-25 - Version 3.3.17

This version fixes a bug in the forwards-compatibility logic of SQLite that was causing a database to become unreadable when it should have been read-only. Upgrade from 3.3.16 only if you plan to deploy into a product that might need to be upgraded in the future. For day to day use, it probably does not matter.

2007-Apr-18 - Version 3.3.16

Performance improvements added in 3.3.14 but mistakenly turned off in 3.3.15 have been reinstated. A bug has been fixed that prevented VACUUM from running if a NULL value was in a UNIQUE column.

2007-Apr-09 - Version 3.3.15

An annoying bug introduced in 3.3.14 has been fixed. There are also many enhancements to the test suite.

2007-Apr-02 - Version 3.3.14

This version focuses on performance improvements. If you recompile the amalgamation using GCC option -O3 (the precompiled binaries use -O2) you may see performance improvements of 35% or more over version 3.3.13 depending on your workload. This version also adds support for exclusive access mode.

2007-Feb-13 - Version 3.3.13

This version fixes a subtle bug in the ORDER BY optimizer that can occur when using joins. There are also a few minor enhancements. Upgrading is recommended.

2007-Jan-27 - Version 3.3.12

The first published build of the previous version used the wrong set of source files. Consequently, many people downloaded a build that was labeled as "3.3.11" but was really 3.3.10. Version 3.3.12 is released to clear up the ambiguity. A couple more bugs have also been fixed and PRAGMA integrity_check has been enhanced.

2007-Jan-22 - Version 3.3.11

Version 3.3.11 fixes for a few more problems in version 3.3.9 that version 3.3.10 failed to catch. Upgrading is recommended.

2007-Jan-9 - Version 3.3.10

Version 3.3.10 fixes several bugs that were introduced by the previous release. Upgrading is recommended.

2007-Jan-4 - Version 3.3.9

Version 3.3.9 fixes bugs that can lead to database corruption under obscure and difficult to reproduce circumstances. See DatabaseCorruption in the wiki for details. This release also adds the new sqlite3_prepare_v2() API and includes important bug fixes in the command-line shell and enhancements to the query optimizer. Upgrading is recommended.

2006-Oct-9 - Version 3.3.8

Version 3.3.8 adds support for full-text search using the FTS1 module. There are also minor bug fixes. Upgrade only if you want to try out the new full-text search capabilities or if you are having problems with 3.3.7.

2006-Aug-12 - Version 3.3.7

Version 3.3.7 includes support for loadable extensions and virtual tables. But both features are still considered "beta" and their APIs are subject to change in a future release. This release is mostly to make available the minor bug fixes that have accumulated since 3.3.6. Upgrading is not necessary. Do so only if you encounter one of the obscure bugs that have been fixed or if you want to try out the new features.

2006-Jun-19 - New Book About SQLite

The Definitive Guide to SQLite, a new book by Mike Owens is now available from Apress. The books covers the latest SQLite internals as well as the native C interface and bindings for PHP, Python, Perl, Ruby, Tcl, and Java. Recommended.

2006-Jun-6 - Version 3.3.6

Changes include improved tolerance for Windows virus scanners and faster :memory: databases. There are also fixes for several obscure bugs. Upgrade if you are having problems.

2006-Apr-5 - Version 3.3.5

This release fixes many minor bugs and documentation typos and provides some minor new features and performance enhancements. Upgrade only if you are having problems or need one of the new features.

2006-Feb-11 - Version 3.3.4

This release fixes several bugs, including a blunder that might cause a deadlock on multithreaded systems. Anyone using SQLite in a multithreaded environment should probably upgrade.

2006-Jan-31 - Version 3.3.3 stable

There have been no major problems discovered in version 3.3.2, so we hereby declare the new APIs and language features to be stable and supported.

2006-Jan-24 - Version 3.3.2 beta

More bug fixes and performance improvements as we move closer to a production-ready version 3.3.x.

2006-Jan-16 - Version 3.3.1 alpha

Many bugs found in last week's alpha release have now been fixed and the library is running much faster again.

Database connections can now be moved between threads as long as the connection holds no locks at the time it is moved. Thus the common paradigm of maintaining a pool of database connections and handing them off to transient worker threads is now supported. Please help test this new feature. See the MultiThreading wiki page for additional information.

2006-Jan-10 - Version 3.3.0 alpha

Version 3.3.0 adds support for CHECK constraints, DESC indices, separate REAL and INTEGER column affinities, a new OS interface layer design, and many other changes. The code passed a regression test but should still be considered alpha. Please report any problems.

The file format for version 3.3.0 has changed slightly to support descending indices and a more efficient encoding of boolean values. SQLite 3.3.0 will read and write legacy databases created with any prior version of SQLite 3. But databases created by version 3.3.0 will not be readable or writable by earlier versions of the SQLite. The older file format can be specified at compile-time for those rare cases where it is needed.

2005-Dec-19 - Versions 3.2.8 and 2.8.17

These versions contain one-line changes to 3.2.7 and 2.8.16 to fix a bug that has been present since March of 2002 and version 2.4.0. That bug might possibly cause database corruption if a large INSERT or UPDATE statement within a multi-statement transaction fails due to a uniqueness constraint but the containing transaction commits.

2005-Sep-24 - Version 3.2.7

This version fixes several minor and obscure bugs. Upgrade only if you are having problems.

2005-Sep-16 - Version 3.2.6 - Critical Bug Fix

This version fixes a bug that can result in database corruption if a VACUUM of a 1 gigabyte or larger database fails (perhaps do to running out of disk space or an unexpected power loss) and is later rolled back.

Also in this release: The ORDER BY and GROUP BY processing was rewritten to use less memory. Support for COUNT(DISTINCT) was added. The LIKE operator can now be used by the optimizer on columns with COLLATE NOCASE.

2005-Aug-27 - Version 3.2.5

This release fixes a few more lingering bugs in the new code. We expect that this release will be stable and ready for production use.

2005-Aug-24 - Version 3.2.4

This release fixes a bug in the new optimizer that can lead to segfaults when parsing very complex WHERE clauses.

2005-Aug-21 - Version 3.2.3

This release adds the ANALYZE command, the CAST operator, and many very substantial improvements to the query optimizer. See the change log for additional information.

2005-Aug-2 - 2005 Open Source Award for SQLite

SQLite and its primary author D. Richard Hipp have been honored with a 2005 Open Source Award from Google and O'Reilly.

2005-Jun-13 - Version 3.2.2

This release includes numerous minor bug fixes, speed improvements, and code size reductions. There is no reason to upgrade unless you are having problems or unless you just want to.

2005-Mar-29 - Version 3.2.1

This release fixes a memory allocation problem in the new ALTER TABLE ADD COLUMN command.

2005-Mar-21 - Version 3.2.0

The primary purpose for version 3.2.0 is to add support for ALTER TABLE ADD COLUMN. The new ADD COLUMN capability is made possible by AOL developers supporting and embracing great open-source software. Thanks, AOL!

Version 3.2.0 also fixes an obscure but serious bug that was discovered just prior to release. If you have a multi-statement transaction and within that transaction an UPDATE or INSERT statement fails due to a constraint, then you try to rollback the whole transaction, the rollback might not work correctly. See Ticket #1171 for details. Upgrading is recommended for all users.

2005-Mar-16 - Version 3.1.6

Version 3.1.6 fixes a critical bug that can cause database corruption when inserting rows into tables with around 125 columns. This bug was introduced in version 3.0.0. See Ticket #1163 for additional information.

2005-Mar-11 - Versions 3.1.4 and 3.1.5 Released

Version 3.1.4 fixes a critical bug that could cause database corruption if the autovacuum mode of version 3.1.0 is turned on (it is off by default) and a CREATE UNIQUE INDEX is executed within a transaction but fails because the indexed columns are not unique. Anyone using the autovacuum feature and unique indices should upgrade.

Version 3.1.5 adds the ability to disable the F_FULLFSYNC ioctl() in OS-X by setting "PRAGMA synchronous=on" instead of the default "PRAGMA synchronous=full". There was an attempt to add this capability in 3.1.4 but it did not work due to a spelling error.

2005-Feb-19 - Version 3.1.3 Released

Version 3.1.3 cleans up some minor issues discovered in version 3.1.2.

2005-Feb-15 - Versions 2.8.16 and 3.1.2 Released

A critical bug in the VACUUM command that can lead to database corruption has been fixed in both the 2.x branch and the main 3.x line. This bug has existed in all prior versions of SQLite. Even though it is unlikely you will ever encounter this bug, it is suggested that all users upgrade. See ticket #1116. for additional information.

Version 3.1.2 is also the first stable release of the 3.1 series. SQLite 3.1 features added support for correlated subqueries, autovacuum, autoincrement, ALTER TABLE, and other enhancements. See the release notes for version 3.1.0 for a detailed description of the changes available in the 3.1 series.

2005-Feb-01 - Version 3.1.1 (beta) Released

Version 3.1.1 (beta) is now available on the website. Version 3.1.1 is fully backwards compatible with the 3.0 series and features many new features including Autovacuum and correlated subqueries. The release notes From version 3.1.0 apply equally to this release beta. A stable release is expected within a couple of weeks.

2005-Jan-21 - Version 3.1.0 (alpha) Released

Version 3.1.0 (alpha) is now available on the website. Version 3.1.0 is fully backwards compatible with the 3.0 series and features many new features including Autovacuum and correlated subqueries. See the release notes for details.

This is an alpha release. A beta release is expected in about a week with the first stable release to follow after two more weeks.

2004-Nov-09 - SQLite at the 2004 International PHP Conference

There was a talk on the architecture of SQLite and how to optimize SQLite queries at the 2004 International PHP Conference in Frankfurt, Germany. Slides from that talk are available.

2004-Oct-11 - Version 3.0.8

Version 3.0.8 of SQLite contains several code optimizations and minor bug fixes and adds support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions. This is an incremental release. There is no reason to upgrade from version 3.0.7 if that version is working for you.

2004-Oct-10 - SQLite at the 11th Annual Tcl/Tk Conference

There will be a talk on the use of SQLite in Tcl/Tk at the 11th Tcl/Tk Conference this week in New Orleans. Visit http://www.tcl.tk/community/tcl2004/ for details. Slides from the talk are available.

2004-Sep-18 - Version 3.0.7

Version 3.0 has now been in use by multiple projects for several months with no major difficulties. We consider it stable and ready for production use.

2004-Sep-02 - Version 3.0.6 (beta)

Because of some important changes to sqlite3_step(), we have decided to do an additional beta release prior to the first "stable" release. If no serious problems are discovered in this version, we will release version 3.0 "stable" in about a week.

2004-Aug-29 - Version 3.0.5 (beta)

The fourth beta release of SQLite version 3.0 is now available. The next release is expected to be called "stable".

2004-Aug-08 - Version 3.0.4 (beta)

The third beta release of SQLite version 3.0 is now available. This new beta fixes several bugs including a database corruption problem that can occur when doing a DELETE while a SELECT is pending. Expect at least one more beta before version 3.0 goes final.

2004-July-22 - Version 3.0.3 (beta)

The second beta release of SQLite version 3.0 is now available. This new beta fixes many bugs and adds support for databases with varying page sizes. The next 3.0 release will probably be called a final or stable release.

Version 3.0 adds support for internationalization and a new more compact file format. Details. The API and file format have been fixed since 3.0.2. All regression tests pass (over 100000 tests) and the test suite exercises over 95% of the code.

SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software.

2004-Jly-22 - Version 2.8.15

SQLite version 2.8.15 is a maintenance release for the version 2.8 series. Version 2.8 continues to be maintained with bug fixes, but no new features will be added to version 2.8. All the changes in this release are minor. If you are not having problems, there is there is no reason to upgrade.

2004-Jun-30 - Version 3.0.2 (beta) Released

The first beta release of SQLite version 3.0 is now available. Version 3.0 adds support for internationalization and a new more compact file format. Details. As of this release, the API and file format are frozen. All regression tests pass (over 100000 tests) and the test suite exercises over 95% of the code.

SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software.

2004-Jun-25 - Website hacked

The www.sqlite.org website was hacked sometime around 2004-Jun-22 because the lead SQLite developer failed to properly patch CVS. Evidence suggests that the attacker was unable to elevate privileges above user "cvs". Nevertheless, as a precaution the entire website has been reconstructed from scratch on a fresh machine. All services should be back to normal as of 2004-Jun-28.

2004-Jun-18 - Version 3.0.0 (alpha) Released

The first alpha release of SQLite version 3.0 is available for public review and comment. Version 3.0 enhances internationalization support through the use of UTF-16 and user-defined text collating sequences. BLOBs can now be stored directly, without encoding. A new file format results in databases that are 25% smaller (depending on content). The code is also a little faster. In spite of the many new features, the library footprint is still less than 240KB (x86, gcc -O1). Additional information.

Our intent is to freeze the file format and API on 2004-Jul-01. Users are encouraged to review and evaluate this alpha release carefully and submit any feedback prior to that date.

The 2.8 series of SQLite will continue to be supported with bug fixes for the foreseeable future.

2004-Jun-09 - Version 2.8.14 Released

SQLite version 2.8.14 is a patch release to the stable 2.8 series. There is no reason to upgrade if 2.8.13 is working ok for you. This is only a bug-fix release. Most development effort is going into version 3.0.0 which is due out soon.

2004-May-31 - CVS Access Temporarily Disabled

Anonymous access to the CVS repository will be suspended for 2 weeks beginning on 2004-June-04. Everyone will still be able to download prepackaged source bundles, create or modify trouble tickets, or view change logs during the CVS service interruption. Full open access to the CVS repository will be restored on 2004-June-18.

2004-Apr-23 - Work Begins On SQLite Version 3

Work has begun on version 3 of SQLite. Version 3 is a major changes to both the C-language API and the underlying file format that will enable SQLite to better support internationalization. The first beta is schedule for release on 2004-July-01.

Plans are to continue to support SQLite version 2.8 with bug fixes. But all new development will occur in version 3.0.


SQL Features That SQLite Does Not Implement

Rather than try to list all the features of SQL92 that SQLite does support, it is much easier to list those that it does not. Unsupported features of SQL92 are shown below.

The order of this list gives some hint as to when a feature might be added to SQLite. Those features near the top of the list are likely to be added in the near future. There are no immediate plans to add features near the bottom of the list.

RIGHT and FULL OUTER JOIN | LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or FULL OUTER JOIN.
Complete ALTER TABLE support | Only the RENAME TABLE and ADD COLUMN variants of the ALTER TABLE command are supported. Other kinds of ALTER TABLE operations such as DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT, and so forth are omitted.
Complete trigger support | FOR EACH ROW triggers are supported but not FOR EACH STATEMENT triggers.
Writing to VIEWs | VIEWs in SQLite are read-only. You may not execute a DELETE, INSERT, or UPDATE statement on a view. But you can create a trigger that fires on an attempt to DELETE, INSERT, or UPDATE a view and do what you need in the body of the trigger.
GRANT and REVOKE | Since SQLite reads and writes an ordinary disk file, the only access permissions that can be applied are the normal file access permissions of the underlying operating system. The GRANT and REVOKE commands commonly found on client/server RDBMSes are not implemented because they would be meaningless for an embedded database engine.


SQLite: Single File Database

Choose any three.
About Sitemap Documentation Download License News Support

Single-file Cross-platform Database

A database in SQLite is a single disk file. Furthermore, the file format is cross-platform. A database that is created on one machine can be copied and used on a different machine with a different architecture. SQLite databases are portable across 32-bit and 64-bit machines and between big-endian and little-endian architectures.

The SQLite database file format is also stable. All releases of of SQLite version 3 can read and write database files created by the very first SQLite 3 release (version 3.0.0) going back to 2004-06-18. This is "backwards compatibility". The developers promise to maintain backwards compatibility of the database file format for all future releases of SQLite 3. "Forwards compatibility" means that older releases of SQLite can also read and write databases created by newer releases. SQLite is usually, but not completely forwards compatible.

The stability of the SQLite database file format and the fact that the file format is cross-platform combine to make SQLite database files an excellent choice as an Application File Format.


SQLite Virtual Machine Opcodes

Introduction

In order to execute an SQL statement, the SQLite library first parses the SQL, analyzes the statement, then generates a short program to execute the statement. The program is generated for a "virtual machine" implemented by the SQLite library. This document describes the operation of that virtual machine.

This document is intended as a reference, not a tutorial. A separate Virtual Machine Tutorial is available. If you are looking for a narrative description of how the virtual machine works, you should read the tutorial and not this document. Once you have a basic idea of what the virtual machine does, you can refer back to this document for the details on a particular opcode. Unfortunately, the virtual machine tutorial was written for SQLite version 1.0. There are substantial changes in the virtual machine for version 2.0 and again for version 3.0.0 and again for version 3.5.5 and the document has not been updated. But the basic concepts behind the virtual machine still apply.

The source code to the virtual machine is in the vdbe.c source file. All of the opcode definitions further down in this document are contained in comments in the source file. In fact, the opcode table in this document was generated by scanning the vdbe.c source file and extracting the necessary information from comments. So the source code comments are really the canonical source of information about the virtual machine. When in doubt, refer to the source code.

Each instruction in the virtual machine consists of an opcode and up to five operands named P1, P2 P3, P4, and P5. P1, P2, and P3 are 32-bit signed integers. These operands often refer to registers. P2 is always the jump destination in any operation that might cause a jump. P4 may be a 32-bit signed integer, a 64-bit signed integer, a 64-bit floating point value, a string literal, a Blob literal, a pointer to a collating sequence comparison function, or a pointer to the implementation of an application-defined SQL function, or various other things. P5 is an unsigned character normally used as a flag. Some operators use all five operands. Some use one or two. Some operators use none of the operands.

The virtual machine begins execution on instruction number 0. Execution continues until a Halt instruction is seen, or the program counter becomes one greater than the address of last instruction, or there is an execution error. When the virtual machine halts, all memory that it allocated is released and all database cursors it may have had open are closed. If the execution stopped due to an error, any pending transactions are terminated and changes made to the database are rolled back.

The virtual machine can have zero or more cursors. Each cursor is a pointer into a single table or index within the database. There can be multiple cursors pointing at the same index or table. All cursors operate independently, even cursors pointing to the same indices or tables. The only way for the virtual machine to interact with a database file is through a cursor. Instructions in the virtual machine can create a new cursor (OpenRead or OpenWrite), read data from a cursor (Column), advance the cursor to the next entry in the table (Next) or index (NextIdx), and many other operations. All cursors are automatically closed when the virtual machine terminates.

The virtual machine contains an arbitrary number of registers locations with addresses beginning at one and growing upward. Each memory location can hold an arbitrary string. The registers hold all intermediate results of a calculation.

Viewing Programs Generated By SQLite

Every SQL statement that SQLite interprets results in a program for the virtual machine. But if you precede the SQL statement with the keyword EXPLAIN the virtual machine will not execute the program. Instead, the instructions of the program will be returned like a query result. This feature is useful for debugging and for learning how the virtual machine operates.

You can use the sqlite3.exe command-line interface (CLI) tool to see the instructions generated by an SQL statement. The following is an example:

$ sqlite3 ex1.db
sqlite> .explain
sqlite> explain delete from tbl1 where two<20;
addr  opcode         p1    p2    p3    p4         p5  comment
----  -------------  ----  ----  ----  ---------  --  -------
0     Trace          0     0     0     explain..  00
1     Goto           0     20    0                00
2     OpenRead       0     2     0                00  tbl
3     SetNumColumns  0     2     0                00
4     Rewind         0     11    0                00
5     Column         0     1     2                00  tbl.two
6     Integer        20    3     0                00
7     Ge             3     10    2     cs(BINARY) 6a
8     Rowid          0     1     0                00
9     FifoWrite      1     0     0                00
10    Next           0     5     0                00
11    Close          0     0     0                00
12    OpenWrite      0     2     0                00  tbl
13    SetNumColumns  0     2     0                00
14    FifoRead       1     18    0                00
15    NotExists      0     17    1                00
16    Delete         0     1     0     tbl        00
17    Goto           0     14    0                00
18    Close          0     0     0                00
19    Halt           0     0     0                00
20    Transaction    0     1     0                00
21    VerifyCookie   0     1     0                00
22    TableLock      -1    2     0     tbl        00
23    Goto           0     2     0                00

All you have to do is add the EXPLAIN keyword to the front of the SQL statement. But if you use the ".explain" command in the CLI, it will set up the output mode to make the program more easily viewable.

Depending on compile-time options, you can put the SQLite virtual machine in a mode where it will trace its execution by writing messages to standard output. The non-standard SQL "PRAGMA" comments can be used to turn tracing on and off. To turn tracing on, enter:

PRAGMA vdbe_trace=on;

You can turn tracing back off by entering a similar statement but changing the value "on" to "off".

The Opcodes

There are currently 146 opcodes defined by the virtual machine. All currently defined opcodes are described in the table below. This table was generated automatically by scanning the source code from the file vdbe.c.

Opcode Name Description

Add

Add the value in register P1 to the value in register P2 and store the result in register P3. If either input is NULL, the result is NULL.

AddImm

Add the constant P2 to the value in register P1. The result is always an integer.

To force any register to be an integer, just add 0.

Affinity

Apply affinities to a range of P2 registers starting with P1.

P4 is a string that is P2 characters long. The nth character of the string indicates the column affinity that should be used for the nth memory cell in the range.

AggFinal

Execute the finalizer function for an aggregate. P1 is the memory location that is the accumulator for the aggregate.

P2 is the number of arguments that the step function takes and P4 is a pointer to the FuncDef for this function. The P2 argument is not used by this opcode. It is only there to disambiguate functions that can take varying numbers of arguments. The P4 argument is only needed for the degenerate case where the step function was not previously called.

AggStep

Execute the step function for an aggregate. The function has P5 arguments. P4 is a pointer to the FuncDef structure that specifies the function. Use register P3 as the accumulator.

The P5 arguments are taken from register P2 and its successors.

And

Take the logical AND of the values in registers P1 and P2 and write the result into register P3.

If either P1 or P2 is 0 (false) then the result is 0 even if the other input is NULL. A NULL and true or two NULLs give a NULL output.

AutoCommit

Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll back any currently active btree transactions. If there are any active VMs (apart from this one), then a ROLLBACK fails. A COMMIT fails if there are active writing VMs or active VMs that use shared cache.

This instruction causes the VM to halt.

BitAnd

Take the bit-wise AND of the values in register P1 and P2 and store the result in register P3. If either input is NULL, the result is NULL.

BitNot

Interpret the content of register P1 as an integer. Store the ones-complement of the P1 value into register P2. If P1 holds a NULL then store a NULL in P2.

BitOr

Take the bit-wise OR of the values in register P1 and P2 and store the result in register P3. If either input is NULL, the result is NULL.

Blob

P4 points to a blob of data P1 bytes long. Store this blob in register P2.

Checkpoint

Checkpoint database P1. This is a no-op if P1 is not currently in WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART. Write 1 or 0 into mem[P3] if the checkpoint returns SQLITE_BUSY or not, respectively. Write the number of pages in the WAL after the checkpoint into mem[P3+1] and the number of pages in the WAL that have been checkpointed after the checkpoint completes into mem[P3+2]. However on an error, mem[P3+1] and mem[P3+2] are initialized to -1.

Clear

Delete all contents of the database table or index whose root page in the database file is given by P1. But, unlike Destroy, do not remove the table or index from the database file.

The table being clear is in the main database file if P2==0. If P2==1 then the table to be clear is in the auxiliary database file that is used to store tables create using CREATE TEMPORARY TABLE.

If the P3 value is non-zero, then the table referred to must be an intkey table (an SQL table, not an index). In this case the row change count is incremented by the number of rows in the table being cleared. If P3 is greater than zero, then the value stored in register P3 is also incremented by the number of rows in the table being cleared.

See also: Destroy

Close

Close a cursor previously opened as P1. If P1 is not currently open, this instruction is a no-op.

CollSeq

P4 is a pointer to a CollSeq struct. If the next call to a user function or aggregate calls sqlite3GetFuncCollSeq(), this collation sequence will be returned. This is used by the built-in min(), max() and nullif() functions.

The interface used by the implementation of the aforementioned functions to retrieve the collation sequence set by this opcode is not available publicly, only to user functions defined in func.c.

Column

Interpret the data that cursor P1 points to as a structure built using the MakeRecord instruction. (See the MakeRecord opcode for additional information about the format of the data.) Extract the P2-th column from this record. If there are less that (P2+1) values in the record, extract a NULL.

The value extracted is stored in register P3.

If the column contains fewer than P2 fields, then extract a NULL. Or, if the P4 argument is a P4_MEM use the value of the P4 argument as the result.

If the OPFLAG_CLEARCACHE bit is set on P5 and P1 is a pseudo-table cursor, then the cache of the cursor is reset prior to extracting the column. The first OP_Column against a pseudo-table after the value of the content register has changed should have this bit set.

Compare

Compare two vectors of registers in reg(P1)..reg(P1+P3-1) (call this vector "A") and in reg(P2)..reg(P2+P3-1) ("B"). Save the result of the comparison for use by the next OP_Jump instruct.

P4 is a KeyInfo structure that defines collating sequences and sort orders for the comparison. The permutation applies to registers only. The KeyInfo elements are used sequentially.

The comparison is a sort comparison, so NULLs compare equal, NULLs are less than numbers, numbers are less than strings, and strings are less than blobs.

Concat

Add the text in register P1 onto the end of the text in register P2 and store the result in register P3. If either the P1 or P2 text are NULL then store NULL in P3.

P3 = P2 || P1

It is illegal for P1 and P3 to be the same register. Sometimes, if P3 is the same register as P2, the implementation is able to avoid a memcpy().

Copy

Make a copy of register P1 into register P2.

This instruction makes a deep copy of the value. A duplicate is made of any string or blob constant. See also OP_SCopy.

Count

Store the number of entries (an integer value) in the table or index opened by cursor P1 in register P2

CreateIndex

Allocate a new index in the main database file if P1==0 or in the auxiliary database file if P1==1 or in an attached database if P1>1. Write the root page number of the new table into register P2.

See documentation on OP_CreateTable for additional information.

CreateTable

Allocate a new table in the main database file if P1==0 or in the auxiliary database file if P1==1 or in an attached database if P1>1. Write the root page number of the new table into register P2

The difference between a table and an index is this: A table must have a 4-byte integer key and can have arbitrary data. An index has an arbitrary key but no data.

See also: CreateIndex

Delete

Delete the record at which the P1 cursor is currently pointing.

The cursor will be left pointing at either the next or the previous record in the table. If it is left pointing at the next record, then the next Next instruction will be a no-op. Hence it is OK to delete a record from within an Next loop.

If the OPFLAG_NCHANGE flag of P2 is set, then the row change count is incremented (otherwise not).

P1 must not be pseudo-table. It has to be a real table with multiple rows.

If P4 is not NULL, then it is the name of the table that P1 is pointing to. The update hook will be invoked, if it exists. If P4 is not NULL then the P1 cursor must have been positioned using OP_NotFound prior to invoking this opcode.

Destroy

Delete an entire database table or index whose root page in the database file is given by P1.

The table being destroyed is in the main database file if P3==0. If P3==1 then the table to be clear is in the auxiliary database file that is used to store tables create using CREATE TEMPORARY TABLE.

If AUTOVACUUM is enabled then it is possible that another root page might be moved into the newly deleted root page in order to keep all root pages contiguous at the beginning of the database. The former value of the root page that moved - its value before the move occurred - is stored in register P2. If no page movement was required (because the table being dropped was already the last one in the database) then a zero is stored in register P2. If AUTOVACUUM is disabled then a zero is stored in register P2.

See also: Clear

Divide

Divide the value in register P1 by the value in register P2 and store the result in register P3 (P3=P2/P1). If the value in register P1 is zero, then the result is NULL. If either input is NULL, the result is NULL.

DropIndex

Remove the internal (in-memory) data structures that describe the index named P4 in database P1. This is called after an index is dropped in order to keep the internal representation of the schema consistent with what is on disk.

DropTable

Remove the internal (in-memory) data structures that describe the table named P4 in database P1. This is called after a table is dropped in order to keep the internal representation of the schema consistent with what is on disk.

DropTrigger

Remove the internal (in-memory) data structures that describe the trigger named P4 in database P1. This is called after a trigger is dropped in order to keep the internal representation of the schema consistent with what is on disk.

Eq

This works just like the Lt opcode except that the jump is taken if the operands in registers P1 and P3 are equal. See the Lt opcode for additional information.

If SQLITE_NULLEQ is set in P5 then the result of comparison is always either true or false and is never NULL. If both operands are NULL then the result of comparison is true. If either operand is NULL then the result is false. If neither operand is NULL the result is the same as it would be if the SQLITE_NULLEQ flag were omitted from P5.

Expire

Cause precompiled statements to become expired. An expired statement fails with an error code of SQLITE_SCHEMA if it is ever executed (via sqlite3_step()).

If P1 is 0, then all SQL statements become expired. If P1 is non-zero, then only the currently executing statement is affected.

FkCounter

Increment a "constraint counter" by P2 (P2 may be negative or positive). If P1 is non-zero, the database constraint counter is incremented (deferred foreign key constraints). Otherwise, if P1 is zero, the statement counter is incremented (immediate foreign key constraints).

FkIfZero

This opcode tests if a foreign key constraint-counter is currently zero. If so, jump to instruction P2. Otherwise, fall through to the next instruction.

If P1 is non-zero, then the jump is taken if the database constraint-counter is zero (the one that counts deferred constraint violations). If P1 is zero, the jump is taken if the statement constraint-counter is zero (immediate foreign key constraint violations).

Found

If P4==0 then register P3 holds a blob constructed by MakeRecord. If P4>0 then register P3 is the first of P4 registers that form an unpacked record.

Cursor P1 is on an index btree. If the record identified by P3 and P4 is a prefix of any entry in P1 then a jump is made to P2 and P1 is left pointing at the matching entry.

Function

Invoke a user function (P4 is a pointer to a Function structure that defines the function) with P5 arguments taken from register P2 and successors. The result of the function is stored in register P3. Register P3 must not be one of the function inputs.

P1 is a 32-bit bitmask indicating whether or not each argument to the function was determined to be constant at compile time. If the first argument was constant then bit 0 of P1 is set. This is used to determine whether meta data associated with a user function argument using the sqlite3_set_auxdata() API may be safely retained until the next invocation of this opcode.

See also: AggStep and AggFinal

Ge

This works just like the Lt opcode except that the jump is taken if the content of register P3 is greater than or equal to the content of register P1. See the Lt opcode for additional information.

Gosub

Write the current address onto register P1 and then jump to address P2.

Goto

An unconditional jump to address P2. The next instruction executed will be the one at index P2 from the beginning of the program.

Gt

This works just like the Lt opcode except that the jump is taken if the content of register P3 is greater than the content of register P1. See the Lt opcode for additional information.

Halt

Exit immediately. All open cursors, etc are closed automatically.

P1 is the result code returned by sqlite3_exec(), sqlite3_reset(), or sqlite3_finalize(). For a normal halt, this should be SQLITE_OK (0). For errors, it can be some other value. If P1!=0 then P2 will determine whether or not to rollback the current transaction. Do not rollback if P2==OE_Fail. Do the rollback if P2==OE_Rollback. If P2==OE_Abort, then back out all changes that have occurred during this execution of the VDBE, but do not rollback the transaction.

If P4 is not null then it is an error message string.

There is an implied "Halt 0 0 0" instruction inserted at the very end of every program. So a jump past the last instruction of the program is the same as executing Halt.

HaltIfNull

Check the value in register P3. If it is NULL then Halt using parameter P1, P2, and P4 as if this were a Halt instruction. If the value in register P3 is not NULL, then this routine is a no-op.

IdxDelete

The content of P3 registers starting at register P2 form an unpacked index key. This opcode removes that entry from the index opened by cursor P1.

IdxGE

The P4 register values beginning with P3 form an unpacked index key that omits the ROWID. Compare this key value against the index that P1 is currently pointing to, ignoring the ROWID on the P1 index.

If the P1 index entry is greater than or equal to the key value then jump to P2. Otherwise fall through to the next instruction.

If P5 is non-zero then the key value is increased by an epsilon prior to the comparison. This make the opcode work like IdxGT except that if the key from register P3 is a prefix of the key in the cursor, the result is false whereas it would be true with IdxGT.

IdxInsert

Register P2 holds an SQL index key made using the MakeRecord instructions. This opcode writes that key into the index P1. Data for the entry is nil.

P3 is a flag that provides a hint to the b-tree layer that this insert is likely to be an append.

This instruction only works for indices. The equivalent instruction for tables is OP_Insert.

IdxLT

The P4 register values beginning with P3 form an unpacked index key that omits the ROWID. Compare this key value against the index that P1 is currently pointing to, ignoring the ROWID on the P1 index.

If the P1 index entry is less than the key value then jump to P2. Otherwise fall through to the next instruction.

If P5 is non-zero then the key value is increased by an epsilon prior to the comparison. This makes the opcode work like IdxLE.

IdxRowid

Write into register P2 an integer which is the last entry in the record at the end of the index key pointed to by cursor P1. This integer should be the rowid of the table entry to which this index entry points.

See also: Rowid, MakeRecord.

If

Jump to P2 if the value in register P1 is true. The value is considered true if it is numeric and non-zero. If the value in P1 is NULL then take the jump if P3 is true.

IfNeg

If the value of register P1 is less than zero, jump to P2.

It is illegal to use this instruction on a register that does not contain an integer. An assertion fault will result if you try.

IfNot

Jump to P2 if the value in register P1 is False. The value is considered true if it has a numeric value of zero. If the value in P1 is NULL then take the jump if P3 is true.

IfPos

If the value of register P1 is 1 or greater, jump to P2.

It is illegal to use this instruction on a register that does not contain an integer. An assertion fault will result if you try.

IfZero

The register P1 must contain an integer. Add literal P3 to the value in register P1. If the result is exactly 0, jump to P2.

It is illegal to use this instruction on a register that does not contain an integer. An assertion fault will result if you try.

IncrVacuum

Perform a single step of the incremental vacuum procedure on the P1 database. If the vacuum has finished, jump to instruction P2. Otherwise, fall through to the next instruction.

Insert

Write an entry into the table of cursor P1. A new entry is created if it doesn't already exist or the data for an existing entry is overwritten. The data is the value MEM_Blob stored in register number P2. The key is stored in register P3. The key must be a MEM_Int.

If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is incremented (otherwise not). If the OPFLAG_LASTROWID flag of P5 is set, then rowid is stored for subsequent return by the sqlite3_last_insert_rowid() function (otherwise it is unmodified).

If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of the last seek operation (OP_NotExists) was a success, then this operation will not attempt to find the appropriate row before doing the insert but will instead overwrite the row that the cursor is currently pointing to. Presumably, the prior OP_NotExists opcode has already positioned the cursor correctly. This is an optimization that boosts performance by avoiding redundant seeks.

If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an UPDATE operation. Otherwise (if the flag is clear) then this opcode is part of an INSERT operation. The difference is only important to the update hook.

Parameter P4 may point to a string containing the table-name, or may be NULL. If it is not NULL, then the update-hook (sqlite3.xUpdateCallback) is invoked following a successful insert.

(WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically allocated, then ownership of P2 is transferred to the pseudo-cursor and register P2 becomes ephemeral. If the cursor is changed, the value of register P2 will then change. Make sure this does not cause any problems.)

This instruction only works on tables. The equivalent instruction for indices is OP_IdxInsert.

InsertInt

This works exactly like OP_Insert except that the key is the integer value P3, not the value of the integer stored in register P3.

Int64

P4 is a pointer to a 64-bit integer value. Write that value into register P2.

Integer

The 32-bit integer value P1 is written into register P2.

IntegrityCk

Do an analysis of the currently open database. Store in register P1 the text of an error message describing any problems. If no problems are found, store a NULL in register P1.

The register P3 contains the maximum number of allowed errors. At most reg(P3) errors will be reported. In other words, the analysis stops as soon as reg(P1) errors are seen. Reg(P1) is updated with the number of errors remaining.

The root page numbers of all tables in the database are integer stored in reg(P1), reg(P1+1), reg(P1+2), .... There are P2 tables total.

If P5 is not zero, the check is done on the auxiliary database file, not the main database file.

This opcode is used to implement the integrity_check pragma.

IsNull

Jump to P2 if the value in register P1 is NULL.

IsUnique

Cursor P1 is open on an index b-tree - that is to say, a btree which no data and where the key are records generated by OP_MakeRecord with the list field being the integer ROWID of the entry that the index entry refers to.

The P3 register contains an integer record number. Call this record number R. Register P4 is the first in a set of N contiguous registers that make up an unpacked index key that can be used with cursor P1. The value of N can be inferred from the cursor. N includes the rowid value appended to the end of the index record. This rowid value may or may not be the same as R.

If any of the N registers beginning with register P4 contains a NULL value, jump immediately to P2.

Otherwise, this instruction checks if cursor P1 contains an entry where the first (N-1) fields match but the rowid value at the end of the index entry is not R. If there is no such entry, control jumps to instruction P2. Otherwise, the rowid of the conflicting index entry is copied to register P3 and control falls through to the next instruction.

See also: NotFound, NotExists, Found

JournalMode

Change the journal mode of database P1 to P3. P3 must be one of the PAGER_JOURNALMODE_XXX values. If changing between the various rollback modes (delete, truncate, persist, off and memory), this is a simple operation. No IO is required.

If changing into or out of WAL mode the procedure is more complicated.

Write a string containing the final journal-mode to register P2.

Jump

Jump to the instruction at address P1, P2, or P3 depending on whether in the most recent OP_Compare instruction the P1 vector was less than equal to, or greater than the P2 vector, respectively.

Last

The next use of the Rowid or Column or Next instruction for P1 will refer to the last entry in the database table or index. If the table or index is empty and P2>0, then jump immediately to P2. If P2 is 0 or if the table or index is not empty, fall through to the following instruction.

Le

This works just like the Lt opcode except that the jump is taken if the content of register P3 is less than or equal to the content of register P1. See the Lt opcode for additional information.

LoadAnalysis

Read the sqlite_stat1 table for database P1 and load the content of that table into the internal index hash table. This will cause the analysis to be used when preparing all subsequent queries.

Lt

Compare the values in register P1 and P3. If reg(P3)<reg(P1) then jump to address P2.

If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or reg(P3) is NULL then take the jump. If the SQLITE_JUMPIFNULL bit is clear then fall through if either operand is NULL.

The SQLITE_AFF_MASK portion of P5 must be an affinity character - SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made to coerce both inputs according to this affinity before the comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric affinity is used. Note that the affinity conversions are stored back into the input registers P1 and P3. So this opcode can cause persistent changes to registers P1 and P3.

Once any conversions have taken place, and neither value is NULL, the values are compared. If both values are blobs then memcmp() is used to determine the results of the comparison. If both values are text, then the appropriate collating function specified in P4 is used to do the comparison. If P4 is not specified then memcmp() is used to compare text string. If both values are numeric, then a numeric comparison is used. If the two values are of different types, then numbers are considered less than strings and strings are considered less than blobs.

If the SQLITE_STOREP2 bit of P5 is set, then do not jump. Instead, store a boolean result (either 0, or 1, or NULL) in register P2.

MakeRecord

Convert P2 registers beginning with P1 into the record format use as a data record in a database table or as a key in an index. The OP_Column opcode can decode the record later.

P4 may be a string that is P2 characters long. The nth character of the string indicates the column affinity that should be used for the nth field of the index key.

The mapping from character to affinity is given by the SQLITE_AFF_ macros defined in sqliteInt.h.

If P4 is NULL then all index fields have the affinity NONE.

MaxPgcnt

Try to set the maximum page count for database P1 to the value in P3. Do not let the maximum page count fall below the current page count and do not change the maximum page count value if P3==0.

Store the maximum page count after the change in register P2.

MemMax

P1 is a register in the root frame of this VM (the root frame is different from the current frame if this instruction is being executed within a sub-program). Set the value of register P1 to the maximum of its current value and the value in register P2.

This instruction throws an error if the memory cell is not initially an integer.

Move

Move the values in register P1..P1+P3-1 over into registers P2..P2+P3-1. Registers P1..P1+P1-1 are left holding a NULL. It is an error for register ranges P1..P1+P3-1 and P2..P2+P3-1 to overlap.

Multiply

Multiply the value in register P1 by the value in register P2 and store the result in register P3. If either input is NULL, the result is NULL.

MustBeInt

Force the value in register P1 to be an integer. If the value in P1 is not an integer and cannot be converted into an integer without data loss, then jump immediately to P2, or if P2==0 raise an SQLITE_MISMATCH exception.

Ne

This works just like the Lt opcode except that the jump is taken if the operands in registers P1 and P3 are not equal. See the Lt opcode for additional information.

If SQLITE_NULLEQ is set in P5 then the result of comparison is always either true or false and is never NULL. If both operands are NULL then the result of comparison is false. If either operand is NULL then the result is true. If neither operand is NULL the result is the same as it would be if the SQLITE_NULLEQ flag were omitted from P5.

NewRowid

Get a new integer record number (a.k.a "rowid") used as the key to a table. The record number is not previously used as a key in the database table that cursor P1 points to. The new record number is written written to register P2.

If P3>0 then P3 is a register in the root frame of this VDBE that holds the largest previously generated record number. No new record numbers are allowed to be less than this value. When this value reaches its maximum, an SQLITE_FULL error is generated. The P3 register is updated with the ' generated record number. This P3 mechanism is used to help implement the AUTOINCREMENT feature.

Next

Advance cursor P1 so that it points to the next key/data pair in its table or index. If there are no more key/value pairs then fall through to the following instruction. But if the cursor advance was successful, jump immediately to P2.

The P1 cursor must be for a real table, not a pseudo-table.

P4 is always of type P4_ADVANCE. The function pointer points to sqlite3BtreeNext().

If P5 is positive and the jump is taken, then event counter number P5-1 in the prepared statement is incremented.

See also: Prev

Noop

Do nothing. This instruction is often useful as a jump destination.

Not

Interpret the value in register P1 as a boolean value. Store the boolean complement in register P2. If the value in register P1 is NULL, then a NULL is stored in P2.

NotExists

Use the content of register P3 as an integer key. If a record with that key does not exist in table of P1, then jump to P2. If the record does exist, then fall through. The cursor is left pointing to the record if it exists.

The difference between this operation and NotFound is that this operation assumes the key is an integer and that P1 is a table whereas NotFound assumes key is a blob constructed from MakeRecord and P1 is an index.

See also: Found, NotFound, IsUnique

NotFound

If P4==0 then register P3 holds a blob constructed by MakeRecord. If P4>0 then register P3 is the first of P4 registers that form an unpacked record.

Cursor P1 is on an index btree. If the record identified by P3 and P4 is not the prefix of any entry in P1 then a jump is made to P2. If P1 does contain an entry whose prefix matches the P3/P4 record then control falls through to the next instruction and P1 is left pointing at the matching entry.

See also: Found, NotExists, IsUnique

NotNull

Jump to P2 if the value in register P1 is not NULL.

Null

Write a NULL into register P2.

NullRow

Move the cursor P1 to a null row. Any OP_Column operations that occur while the cursor is on the null row will always write a NULL.

Once

Jump to P2 if the value in register P1 is a not null or zero. If the value is NULL or zero, fall through and change the P1 register to an integer 1.

When P1 is not used otherwise in a program, this opcode falls through once and jumps on all subsequent invocations. It is the equivalent of "OP_If P1 P2", followed by "OP_Integer 1 P1".

OpenAutoindex

This opcode works the same as OP_OpenEphemeral. It has a different name to distinguish its use. Tables created using by this opcode will be used for automatically created transient indices in joins.

OpenEphemeral

Open a new cursor P1 to a transient table. The cursor is always opened read/write even if the main database is read-only. The ephemeral table is deleted automatically when the cursor is closed.

P2 is the number of columns in the ephemeral table. The cursor points to a BTree table if P4==0 and to a BTree index if P4 is not 0. If P4 is not NULL, it points to a KeyInfo structure that defines the format of keys in the index.

This opcode was once called OpenTemp. But that created confusion because the term "temp table", might refer either to a TEMP table at the SQL level, or to a table opened by this opcode. Then this opcode was call OpenVirtual. But that created confusion with the whole virtual-table idea.

The P5 parameter can be a mask of the BTREE_* flags defined in btree.h. These flags control aspects of the operation of the btree. The BTREE_OMIT_JOURNAL and BTREE_SINGLE flags are added automatically.

OpenPseudo

Open a new cursor that points to a fake table that contains a single row of data. The content of that one row in the content of memory register P2. In other words, cursor P1 becomes an alias for the MEM_Blob content contained in register P2.

A pseudo-table created by this opcode is used to hold a single row output from the sorter so that the row can be decomposed into individual columns using the OP_Column opcode. The OP_Column opcode is the only cursor opcode that works with a pseudo-table.

P3 is the number of fields in the records that will be stored by the pseudo-table.

OpenRead

Open a read-only cursor for the database table whose root page is P2 in a database file. The database file is determined by P3. P3==0 means the main database, P3==1 means the database used for temporary tables, and P3>1 means used the corresponding attached database. Give the new cursor an identifier of P1. The P1 values need not be contiguous but all P1 values should be small integers. It is an error for P1 to be negative.

If P5!=0 then use the content of register P2 as the root page, not the value of P2 itself.

There will be a read lock on the database whenever there is an open cursor. If the database was unlocked prior to this instruction then a read lock is acquired as part of this instruction. A read lock allows other processes to read the database but prohibits any other process from modifying the database. The read lock is released when all cursors are closed. If this instruction attempts to get a read lock but fails, the script terminates with an SQLITE_BUSY error code.

The P4 value may be either an integer (P4_INT32) or a pointer to a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo structure, then said structure defines the content and collating sequence of the index being opened. Otherwise, if P4 is an integer value, it is set to the number of columns in the table.

See also OpenWrite.

OpenSorter

This opcode works like OP_OpenEphemeral except that it opens a transient index that is specifically designed to sort large tables using an external merge-sort algorithm.

OpenWrite

Open a read/write cursor named P1 on the table or index whose root page is P2. Or if P5!=0 use the content of register P2 to find the root page.

The P4 value may be either an integer (P4_INT32) or a pointer to a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo structure, then said structure defines the content and collating sequence of the index being opened. Otherwise, if P4 is an integer value, it is set to the number of columns in the table, or to the largest index of any column of the table that is actually used.

This instruction works just like OpenRead except that it opens the cursor in read/write mode. For a given table, there can be one or more read-only cursors or a single read/write cursor but not both.

See also OpenRead.

Or

Take the logical OR of the values in register P1 and P2 and store the answer in register P3.

If either P1 or P2 is nonzero (true) then the result is 1 (true) even if the other input is NULL. A NULL and false or two NULLs give a NULL output.

Pagecount

Write the current number of pages in database P1 to memory cell P2.

Param

This opcode is only ever present in sub-programs called via the OP_Program instruction. Copy a value currently stored in a memory cell of the calling (parent) frame to cell P2 in the current frames address space. This is used by trigger programs to access the new.* and old.* values.

The address of the cell in the parent frame is determined by adding the value of the P1 argument to the value of the P1 argument to the calling OP_Program instruction.

ParseSchema

Read and parse all entries from the SQLITE_MASTER table of database P1 that match the WHERE clause P4.

This opcode invokes the parser to create a new virtual machine, then runs the new virtual machine. It is thus a re-entrant opcode.

Permutation

Set the permutation used by the OP_Compare operator to be the array of integers in P4.

The permutation is only valid until the next OP_Permutation, OP_Compare, OP_Halt, or OP_ResultRow. Typically the OP_Permutation should occur immediately prior to the OP_Compare.

Prev

Back up cursor P1 so that it points to the previous key/data pair in its table or index. If there is no previous key/value pairs then fall through to the following instruction. But if the cursor backup was successful, jump immediately to P2.

The P1 cursor must be for a real table, not a pseudo-table.

P4 is always of type P4_ADVANCE. The function pointer points to sqlite3BtreePrevious().

If P5 is positive and the jump is taken, then event counter number P5-1 in the prepared statement is incremented.

Program

Execute the trigger program passed as P4 (type P4_SUBPROGRAM).

P1 contains the address of the memory cell that contains the first memory cell in an array of values used as arguments to the sub-program. P2 contains the address to jump to if the sub-program throws an IGNORE exception using the RAISE() function. Register P3 contains the address of a memory cell in this (the parent) VM that is used to allocate the memory required by the sub-vdbe at runtime.

P4 is a pointer to the VM containing the trigger program.

ReadCookie

Read cookie number P3 from database P1 and write it into register P2. P3==1 is the schema version. P3==2 is the database format. P3==3 is the recommended pager cache size, and so forth. P1==0 is the main database file and P1==1 is the database file used to store temporary tables.

There must be a read-lock on the database (either a transaction must be started or there must be an open cursor) before executing this instruction.

Real

P4 is a pointer to a 64-bit floating point value. Write that value into register P2.

RealAffinity

If register P1 holds an integer convert it to a real value.

This opcode is used when extracting information from a column that has REAL affinity. Such column values may still be stored as integers, for space efficiency, but after extraction we want them to have only a real value.

Remainder

Compute the remainder after integer division of the value in register P1 by the value in register P2 and store the result in P3. If the value in register P2 is zero the result is NULL. If either operand is NULL, the result is NULL.

ResetCount

The value of the change counter is copied to the database handle change counter (returned by subsequent calls to sqlite3_changes()). Then the VMs internal change counter resets to 0. This is used by trigger programs.

ResultRow

The registers P1 through P1+P2-1 contain a single row of results. This opcode causes the sqlite3_step() call to terminate with an SQLITE_ROW return code and it sets up the sqlite3_stmt structure to provide access to the top P1 values as the result row.

Return

Jump to the next instruction after the address in register P1.

Rewind

The next use of the Rowid or Column or Next instruction for P1 will refer to the first entry in the database table or index. If the table or index is empty and P2>0, then jump immediately to P2. If P2 is 0 or if the table or index is not empty, fall through to the following instruction.

RowData

Write into register P2 the complete row data for cursor P1. There is no interpretation of the data. It is just copied onto the P2 register exactly as it is found in the database file.

If the P1 cursor must be pointing to a valid row (not a NULL row) of a real table, not a pseudo-table.

Rowid

Store in register P2 an integer which is the key of the table entry that P1 is currently point to.

P1 can be either an ordinary table or a virtual table. There used to be a separate OP_VRowid opcode for use with virtual tables, but this one opcode now works for both table types.

RowKey

Write into register P2 the complete row key for cursor P1. There is no interpretation of the data. The key is copied onto the P3 register exactly as it is found in the database file.

If the P1 cursor must be pointing to a valid row (not a NULL row) of a real table, not a pseudo-table.

RowSetAdd

Insert the integer value held by register P2 into a boolean index held in register P1.

An assertion fails if P2 is not an integer.

RowSetRead

Extract the smallest value from boolean index P1 and put that value into register P3. Or, if boolean index P1 is initially empty, leave P3 unchanged and jump to instruction P2.

RowSetTest

Register P3 is assumed to hold a 64-bit integer value. If register P1 contains a RowSet object and that RowSet object contains the value held in P3, jump to register P2. Otherwise, insert the integer in P3 into the RowSet and continue on to the next opcode.

The RowSet object is optimized for the case where successive sets of integers, where each set contains no duplicates. Each set of values is identified by a unique P4 value. The first set must have P4==0, the final set P4=-1. P4 must be either -1 or non-negative. For non-negative values of P4 only the lower 4 bits are significant.

This allows optimizations: (a) when P4==0 there is no need to test the rowset object for P3, as it is guaranteed not to contain it, (b) when P4==-1 there is no need to insert the value, as it will never be tested for, and (c) when a value that is part of set X is inserted, there is no need to search to see if the same value was previously inserted as part of set X (only if it was previously inserted as part of some other set).

Savepoint

Open, release or rollback the savepoint named by parameter P4, depending on the value of P1. To open a new savepoint, P1==0. To release (commit) an existing savepoint, P1==1, or to rollback an existing savepoint P1==2.

SCopy

Make a shallow copy of register P1 into register P2.

This instruction makes a shallow copy of the value. If the value is a string or blob, then the copy is only a pointer to the original and hence if the original changes so will the copy. Worse, if the original is deallocated, the copy becomes invalid. Thus the program must guarantee that the original will not change during the lifetime of the copy. Use OP_Copy to make a complete copy.

Seek

P1 is an open table cursor and P2 is a rowid integer. Arrange for P1 to move so that it points to the rowid given by P2.

This is actually a deferred seek. Nothing actually happens until the cursor is used to read a record. That way, if no reads occur, no unnecessary I/O happens.

SeekGe

If cursor P1 refers to an SQL table (B-Tree that uses integer keys), use the value in register P3 as the key. If cursor P1 refers to an SQL index, then P3 is the first in an array of P4 registers that are used as an unpacked index key.

Reposition cursor P1 so that it points to the smallest entry that is greater than or equal to the key value. If there are no records greater than or equal to the key and P2 is not zero, then jump to P2.

See also: Found, NotFound, Distinct, SeekLt, SeekGt, SeekLe

SeekGt

If cursor P1 refers to an SQL table (B-Tree that uses integer keys), use the value in register P3 as a key. If cursor P1 refers to an SQL index, then P3 is the first in an array of P4 registers that are used as an unpacked index key.

Reposition cursor P1 so that it points to the smallest entry that is greater than the key value. If there are no records greater than the key and P2 is not zero, then jump to P2.

See also: Found, NotFound, Distinct, SeekLt, SeekGe, SeekLe

SeekLe

If cursor P1 refers to an SQL table (B-Tree that uses integer keys), use the value in register P3 as a key. If cursor P1 refers to an SQL index, then P3 is the first in an array of P4 registers that are used as an unpacked index key.

Reposition cursor P1 so that it points to the largest entry that is less than or equal to the key value. If there are no records less than or equal to the key and P2 is not zero, then jump to P2.

See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLt

SeekLt

If cursor P1 refers to an SQL table (B-Tree that uses integer keys), use the value in register P3 as a key. If cursor P1 refers to an SQL index, then P3 is the first in an array of P4 registers that are used as an unpacked index key.

Reposition cursor P1 so that it points to the largest entry that is less than the key value. If there are no records less than the key and P2 is not zero, then jump to P2.

See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLe

Sequence

Find the next available sequence number for cursor P1. Write the sequence number into register P2. The sequence number on the cursor is incremented after this instruction.

SetCookie

Write the content of register P3 (interpreted as an integer) into cookie number P2 of database P1. P2==1 is the schema version. P2==2 is the database format. P2==3 is the recommended pager cache size, and so forth. P1==0 is the main database file and P1==1 is the database file used to store temporary tables.

A transaction must be started before executing this opcode.

ShiftLeft

Shift the integer value in register P2 to the left by the number of bits specified by the integer in register P1. Store the result in register P3. If either input is NULL, the result is NULL.

ShiftRight

Shift the integer value in register P2 to the right by the number of bits specified by the integer in register P1. Store the result in register P3. If either input is NULL, the result is NULL.

Sort

This opcode does exactly the same thing as OP_Rewind except that it increments an undocumented global variable used for testing.

Sorting is accomplished by writing records into a sorting index, then rewinding that index and playing it back from beginning to end. We use the OP_Sort opcode instead of OP_Rewind to do the rewinding so that the global variable will be incremented and regression tests can determine whether or not the optimizer is correctly optimizing out sorts.

SorterCompare

P1 is a sorter cursor. This instruction compares the record blob in register P3 with the entry that the sorter cursor currently points to. If, excluding the rowid fields at the end, the two records are a match, fall through to the next instruction. Otherwise, jump to instruction P2.

SorterData

Write into register P2 the current sorter data for sorter cursor P1.

String

The string value P4 of length P1 (bytes) is stored in register P2.

String8

P4 points to a nul terminated UTF-8 string. This opcode is transformed into an OP_String before it is executed for the first time.

Subtract

Subtract the value in register P1 from the value in register P2 and store the result in register P3. If either input is NULL, the result is NULL.

TableLock

Obtain a lock on a particular table. This instruction is only used when the shared-cache feature is enabled.

P1 is the index of the database in sqlite3.aDb[] of the database on which the lock is acquired. A readlock is obtained if P3==0 or a write lock if P3==1.

P2 contains the root-page of the table to lock.

P4 contains a pointer to the name of the table being locked. This is only used to generate an error message if the lock cannot be obtained.

ToBlob

Force the value in register P1 to be a BLOB. If the value is numeric, convert it to a string first. Strings are simply reinterpreted as blobs with no change to the underlying data.

A NULL value is not changed by this routine. It remains NULL.

ToInt

Force the value in register P1 to be an integer. If The value is currently a real number, drop its fractional part. If the value is text or blob, try to convert it to an integer using the equivalent of atoi() and store 0 if no such conversion is possible.

A NULL value is not changed by this routine. It remains NULL.

ToNumeric

Force the value in register P1 to be numeric (either an integer or a floating-point number.) If the value is text or blob, try to convert it to an using the equivalent of atoi() or atof() and store 0 if no such conversion is possible.

A NULL value is not changed by this routine. It remains NULL.

ToReal

Force the value in register P1 to be a floating point number. If The value is currently an integer, convert it. If the value is text or blob, try to convert it to an integer using the equivalent of atoi() and store 0.0 if no such conversion is possible.

A NULL value is not changed by this routine. It remains NULL.

ToText

Force the value in register P1 to be text. If the value is numeric, convert it to a string using the equivalent of printf(). Blob values are unchanged and are afterwards simply interpreted as text.

A NULL value is not changed by this routine. It remains NULL.

Trace

If tracing is enabled (by the sqlite3_trace()) interface, then the UTF-8 string contained in P4 is emitted on the trace callback.

Transaction

Begin a transaction. The transaction ends when a Commit or Rollback opcode is encountered. Depending on the ON CONFLICT setting, the transaction might also be rolled back if an error is encountered.

P1 is the index of the database file on which the transaction is started. Index 0 is the main database file and index 1 is the file used for temporary tables. Indices of 2 or more are used for attached databases.

If P2 is non-zero, then a write-transaction is started. A RESERVED lock is obtained on the database file when a write-transaction is started. No other process can start another write transaction while this transaction is underway. Starting a write transaction also creates a rollback journal. A write transaction must be started before any changes can be made to the database. If P2 is 2 or greater then an EXCLUSIVE lock is also obtained on the file.

If a write-transaction is started and the Vdbe.usesStmtJournal flag is true (this flag is set if the Vdbe may modify more than one row and may throw an ABORT exception), a statement transaction may also be opened. More specifically, a statement transaction is opened iff the database connection is currently not in autocommit mode, or if there are other active statements. A statement transaction allows the affects of this VDBE to be rolled back after an error without having to roll back the entire transaction. If no error is encountered, the statement transaction will automatically commit when the VDBE halts.

If P2 is zero, then a read-lock is obtained on the database file.

Vacuum

Vacuum the entire database. This opcode will cause other virtual machines to be created and run. It may not be called from within a transaction.

Variable

Transfer the values of bound parameter P1 into register P2

If the parameter is named, then its name appears in P4 and P3==1. The P4 value is used by sqlite3_bind_parameter_name().

VBegin

P4 may be a pointer to an sqlite3_vtab structure. If so, call the xBegin method for that table.

Also, whether or not P4 is set, check that this is not being called from within a callback to a virtual table xSync() method. If it is, the error code will be set to SQLITE_LOCKED.

VColumn

Store the value of the P2-th column of the row of the virtual-table that the P1 cursor is pointing to into register P3.

VCreate

P4 is the name of a virtual table in database P1. Call the xCreate method for that table.

VDestroy

P4 is the name of a virtual table in database P1. Call the xDestroy method of that table.

VerifyCookie

Check the value of global database parameter number 0 (the schema version) and make sure it is equal to P2 and that the generation counter on the local schema parse equals P3.

P1 is the database number which is 0 for the main database file and 1 for the file holding temporary tables and some higher number for auxiliary databases.

The cookie changes its value whenever the database schema changes. This operation is used to detect when that the cookie has changed and that the current process needs to reread the schema.

Either a transaction needs to have been started or an OP_Open needs to be executed (to establish a read lock) before this opcode is invoked.

VFilter

P1 is a cursor opened using VOpen. P2 is an address to jump to if the filtered result set is empty.

P4 is either NULL or a string that was generated by the xBestIndex method of the module. The interpretation of the P4 string is left to the module implementation.

This opcode invokes the xFilter method on the virtual table specified by P1. The integer query plan parameter to xFilter is stored in register P3. Register P3+1 stores the argc parameter to be passed to the xFilter method. Registers P3+2..P3+1+argc are the argc additional parameters which are passed to xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter.

A jump is made to P2 if the result set after filtering would be empty.

VNext

Advance virtual table P1 to the next row in its result set and jump to instruction P2. Or, if the virtual table has reached the end of its result set, then fall through to the next instruction.

VOpen

P4 is a pointer to a virtual table object, an sqlite3_vtab structure. P1 is a cursor number. This opcode opens a cursor to the virtual table and stores that cursor in P1.

VRename

P4 is a pointer to a virtual table object, an sqlite3_vtab structure. This opcode invokes the corresponding xRename method. The value in register P1 is passed as the zName argument to the xRename method.

VUpdate

P4 is a pointer to a virtual table object, an sqlite3_vtab structure. This opcode invokes the corresponding xUpdate method. P2 values are contiguous memory cells starting at P3 to pass to the xUpdate invocation. The value in register (P3+P2-1) corresponds to the p2th element of the argv array passed to xUpdate.

The xUpdate method will do a DELETE or an INSERT or both. The argv[0] element (which corresponds to memory cell P3) is the rowid of a row to delete. If argv[0] is NULL then no deletion occurs. The argv[1] element is the rowid of the new row. This can be NULL to have the virtual table select the new rowid for itself. The subsequent elements in the array are the values of columns in the new row.

If P2==1 then no insert is performed. argv[0] is the rowid of a row to delete.

P1 is a boolean flag. If it is set to true and the xUpdate call is successful, then the value returned by sqlite3_last_insert_rowid() is set to the value of the rowid for the row just inserted.

Yield

Swap the program counter with the value in register P1.


The SQLite Query Optimizer Overview

Choose any three.
About Sitemap Documentation Download License News Support

The SQLite Query Planner

This document provides overview of how the query planner and optimizer for SQLite works.

Given a single SQL statement, there might be dozens, hundreds, or even thousands of ways to implement that statement, depending on the complexity of the statement itself and of the underlying database schema. The task of the query planner is to select an algorithm from among the many choices that provides the answer with a minimum of disk I/O and CPU overhead.

1.0 WHERE clause analysis

The WHERE clause on a query is broken up into "terms" where each term is separated from the others by an AND operator. If the WHERE clause is composed of constraints separate by the OR operator then the entire clause is considered to be a single "term" to which the OR-clause optimization is applied.

All terms of the WHERE clause are analyzed to see if they can be satisfied using indices. Terms that cannot be satisfied through the use of indices become tests that are evaluated against each row of the relevant input tables. No tests are done for terms that are completely satisfied by indices. Sometimes one or more terms will provide hints to indices but still must be evaluated against each row of the input tables.

The analysis of a term might cause new "virtual" terms to be added to the WHERE clause. Virtual terms can be used with indices to restrict a search. But virtual terms never generate code that is tested against input rows.

To be usable by an index a term must be of one of the following forms:

  column = expression
  column > expression
  column >= expression
  column < expression
  column <= expression
  expression = column
  expression > column
  expression >= column
  expression < column
  expression <= column
  column IN (expression-list)
  column IN (subquery)
  column IS NULL

If an index is created using a statement like this:

  CREATE INDEX idx_ex1 ON ex1(a,b,c,d,e,...,y,z);

Then the index might be used if the initial columns of the index (columns a, b, and so forth) appear in WHERE clause terms. The initial columns of the index must be used with the = or IN operators. The right-most column that is used can employ inequalities. For the right-most column of an index that is used, there can be up to two inequalities that must sandwich the allowed values of the column between two extremes.

It is not necessary for every column of an index to appear in a WHERE clause term in order for that index to be used. But there can not be gaps in the columns of the index that are used. Thus for the example index above, if there is no WHERE clause term that constraints column c, then terms that constrain columns a and b can be used with the index but not terms that constraint columns d through z. Similarly, no index column will be used (for indexing purposes) that is to the right of a column that is constrained only by inequalities.

1.1 Index term usage examples

For the index above and WHERE clause like this:

  ... WHERE a=5 AND b IN (1,2,3) AND c IS NULL AND d='hello'

The first four columns a, b, c, and d of the index would be usable since those four columns form a prefix of the index and are all bound by equality constraints.

For the index above and WHERE clause like this:

  ... WHERE a=5 AND b IN (1,2,3) AND c>12 AND d='hello'

Only columns a, b, and c of the index would be usable. The d column would not be usable because it occurs to the right of c and c is constrained only by inequalities.

For the index above and WHERE clause like this:

  ... WHERE a=5 AND b IN (1,2,3) AND d='hello'

Only columns a and b of the index would be usable. The d column would not be usable because column c is not constrained and there can be no gaps in the set of columns that usable by the index.

For the index above and WHERE clause like this:

  ... WHERE b IN (1,2,3) AND c NOT NULL AND d='hello'

The index is not usable at all because the left-most column of the index (column "a") is not constrained.) Assuming there are no other indices, the query above would result in a full table scan.

For the index above and WHERE clause like this:

  ... WHERE a=5 OR b IN (1,2,3) OR c NOT NULL OR d='hello'

The index is not usable because the WHERE clause terms are connected by OR instead of AND. This query would result in a full table scan. However, if three additional indices where added that contained columns b, c, and d as their left-most columns, then the OR-clause optimization might apply.

2.0 The BETWEEN optimization

If a term of the WHERE clause is of the following form:

  expr1 BETWEEN expr2 AND expr3

Then two virtual terms are added as follows:

  expr1 >= expr2 AND expr1 <= expr3

If both virtual terms end up being used as constraints on an index, then the original BETWEEN term is omitted and the corresponding test is not performed on input rows. Thus if the BETWEEN term ends up being used as an index constraint no tests are ever performed on that term. On the other hand, the virtual terms themselves never causes tests to be performed on input rows. Thus if the BETWEEN term is not used as an index constraint and instead must be used to test input rows, the expr1 expression is only evaluated once.

3.0 OR optimizations

WHERE clause constraints that are connected by OR instead of AND are handled in one of two way. If a term consists of multiple subterms containing a common column name and separated by OR, like this:

  column = expr1 OR column = expr2 OR column = expr3 OR ...

Then that term is rewritten as follows:

  column IN (expr1,expr2,expr3,expr4,...)

The rewritten term then might go on to constrain an index using the normal rules for IN operators. Note that column must be the same column in every OR-connected subterm, although the column can occur on either the left or the right side of the = operator.

If and only if the previously described conversion of OR to an IN operator does not work, the second OR-clause optimization is attempted. Suppose the OR clause consists of multiple subterms as follows:

  expr1 OR expr2 OR expr3

Individual subterms might be a single comparison expression like a=5 or x>y or they can be LIKE or BETWEEN expressions, or a subterm can be a parenthesized list of AND-connected sub-subterms. Each subterm is analyzed as if it were itself the entire WHERE clause in order to see if the subterm is indexable by itself. If every subterm of an OR clause is separately indexable then the OR clause might be coded such that a separate index is used to evaluate each term of the OR clause. One way to think about how SQLite uses separate indices foreach each OR clause term is to imagine that the WHERE clause where rewritten as follows:

  rowid IN (SELECT rowid FROM table WHERE expr1
            UNION SELECT rowid FROM table WHERE expr2
            UNION SELECT rowid FROM table WHERE expr3)

The rewritten expression above is conceptual; WHERE clauses containing OR are not really rewritten this way. The actual implementation of the OR clause uses a mechanism that is more efficient than subqueries and which works even for tables where the "rowid" column name has been overloaded for other uses and no longer refers to the real rowid. But the essence of the implementation is captured by the statement above: Separate indices are used to find candidate result rows from each OR clause term and the final result is the union of those rows.

Note that in most cases, SQLite will only use a single index for each table in the FROM clause of a query. The second OR-clause optimization described here is the exception to that rule. With an OR-clause, a different index might be used for each subterm in the OR-clause.

For any given query, the fact that the OR-clause optimization described here can be used does not guarantee that it will be used. SQLite uses a cost-based query planner that estimates the CPU and disk I/O costs of various competing query plans and chooses the plan that it thinks will be the fastest. If there are many OR terms in the WHERE clause or if some of the indices on individual OR-clause subterms are not very selective, then SQLite might decide that it is faster to use a different query algorithm, or even a full-table scan. Application developers can use the EXPLAIN QUERY PLAN prefix on a statement to get a high-level overview of the chosen query strategy.

4.0 The LIKE optimization

Terms that are composed of the LIKE or GLOB operator can sometimes be used to constrain indices. There are many conditions on this use:

  1. The left-hand side of the LIKE or GLOB operator must be the name of an indexed column with TEXT affinity.
  2. The right-hand side of the LIKE or GLOB must be either a string literal or a parameter bound to a string literal that does not begin with a wildcard character.
  3. The ESCAPE clause cannot appear on the LIKE operator.
  4. The build-in functions used to implement LIKE and GLOB must not have been overloaded using the sqlite3_create_function() API.
  5. For the GLOB operator, the column must be indexed using the built-in BINARY collating sequence.
  6. For the LIKE operator, if case_sensitive_like mode is enabled then the column must indexed using BINARY collating sequence, or if case_sensitive_like mode is disabled then the column must indexed using built-in NOCASE collating sequence.

The LIKE operator has two modes that can be set by a pragma. The default mode is for LIKE comparisons to be insensitive to differences of case for latin1 characters. Thus, by default, the following expression is true:

  'a' LIKE 'A'

But if the case_sensitive_like pragma is enabled as follows:

  PRAGMA case_sensitive_like=ON;

Then the LIKE operator pays attention to case and the example above would evaluate to false. Note that case insensitivity only applies to latin1 characters - basically the upper and lower case letters of English in the lower 127 byte codes of ASCII. International character sets are case sensitive in SQLite unless an application-defined collating sequence and like() SQL function are provided that take non-ASCII characters into account. But if an application-defined collating sequence and/or like() SQL function are provided, the LIKE optimization described here will never be taken.

The LIKE operator is case insensitive by default because this is what the SQL standard requires. You can change the default behavior at compile time by using the SQLITE_CASE_SENSITIVE_LIKE command-line option to the compiler.

The LIKE optimization might occur if the column named on the left of the operator is indexed using the built-in BINARY collating sequence and case_sensitive_like is turned on. Or the optimization might occur if the column is indexed using the built-in NOCASE collating sequence and the case_sensitive_like mode is off. These are the only two combinations under which LIKE operators will be optimized.

The GLOB operator is always case sensitive. The column on the left side of the GLOB operator must always use the built-in BINARY collating sequence or no attempt will be made to optimize that operator with indices.

The LIKE optimization will only be attempted if the right-hand side of the GLOB or LIKE operator is either literal string or a parameter that has been bound to a string literal. The string literal must not begin with a wildcard; if the right-hand side begins with a wildcard character then this optimization is attempted. If the right-hand side is a parameter that is bound to a string, then this optimization is only attempted if the prepared statement containing the expression was compiled with sqlite3_prepare_v2() or sqlite3_prepare16_v2(). The LIKE optimization is not attempted if the right-hand side is a parameter and the statement was prepared using sqlite3_prepare() or sqlite3_prepare16(). The LIKE optimization is not attempted if there is an EXCEPT phrase on the LIKE operator.

Suppose the initial sequence of non-wildcard characters on the right-hand side of the LIKE or GLOB operator is x. We are using a single character to denote this non-wildcard prefix but the reader should understand that the prefix can consist of more than 1 character. Let y be the smallest string that is the same length as /x/ but which compares greater than x. For example, if x is hello then y would be hellp. The LIKE and GLOB optimizations consist of adding two virtual terms like this:

  column >= x AND column < y

Under most circumstances, the original LIKE or GLOB operator is still tested against each input row even if the virtual terms are used to constrain an index. This is because we do not know what additional constraints may be imposed by characters to the right of the x prefix. However, if there is only a single global wildcard to the right of x, then the original LIKE or GLOB test is disabled. In other words, if the pattern is like this:

  column LIKE x%
  column GLOB x*

then the original LIKE or GLOB tests are disabled when the virtual terms constrain an index because in that case we know that all of the rows selected by the index will pass the LIKE or GLOB test.

Note that when the right-hand side of a LIKE or GLOB operator is a parameter and the statement is prepared using sqlite3_prepare_v2() or sqlite3_prepare16_v2() then the statement is automatically reparsed and recompiled on the first sqlite3_step() call of each run if the binding to the right-hand side parameter has changed since the previous run. This reparse and recompile is essentially the same action that occurs following a schema change. The recompile is necessary so that the query planner can examine the new value bound to the right-hand side of the LIKE or GLOB operator and determine whether or not to employ the optimization described above.

5.0 Joins

The ON and USING clauses of an inner join are converted into additional terms of the WHERE clause prior to WHERE clause analysis described above in paragraph 1.0. Thus with SQLite, there is no computational advantage to use the newer SQL92 join syntax over the older SQL89 comma-join syntax. They both end up accomplishing exactly the same thing on inner joins.

For a LEFT OUTER JOIN the situation is more complex. The following two queries are not equivalent:

  SELECT * FROM tab1 LEFT JOIN tab2 ON tab1.x=tab2.y;
  SELECT * FROM tab1 LEFT JOIN tab2 WHERE tab1.x=tab2.y;

For an inner join, the two queries above would be identical. But special processing applies to the ON and USING clauses of an OUTER join: specifically, the constraints in an ON or USING clause do not apply if the right table of the join is on a null row, but the constraints do apply in the WHERE clause. The net effect is that putting the ON or USING clause expressions for a LEFT JOIN in the WHERE clause effectively converts the query to an ordinary INNER JOIN - albeit an inner join that runs more slowly.

5.1 Order of tables in a join

The current implementation of SQLite uses only loop joins. That is to say, joins are implemented as nested loops.

The default order of the nested loops in a join is for the left-most table in the FROM clause to form the outer loop and the right-most table to form the inner loop. However, SQLite will nest the loops in a different order if doing so will help it to select better indices.

Inner joins can be freely reordered. However a left outer join is neither commutative nor associative and hence will not be reordered. Inner joins to the left and right of the outer join might be reordered if the optimizer thinks that is advantageous but the outer joins are always evaluated in the order in which they occur.

When selecting the order of tables in a join, SQLite uses a greedy algorithm that runs in polynomial (O(N²)) time. Because of this, SQLite is able to efficiently plan queries with 50- or 60-way joins.

Join reordering is automatic and usually works well enough that programmers do not have to think about it, especially if ANALYZE has been used to gather statistics about the available indices. But occasionally some hints from the programmer are needed. Consider, for example, the following schema:

  CREATE TABLE node(
     id INTEGER PRIMARY KEY,
     name TEXT
  );
  CREATE INDEX node_idx ON node(name);
  CREATE TABLE edge(
     orig INTEGER REFERENCES node,
     dest INTEGER REFERENCES node,
     PRIMARY KEY(orig, dest)
  );
  CREATE INDEX edge_idx ON edge(dest,orig);

The schema above defines a directed graph with the ability to store a name at each node. Now consider a query against this schema:

  SELECT *
    FROM edge AS e,
         node AS n1,
         node AS n2
   WHERE n1.name = 'alice'
     AND n2.name = 'bob'
     AND e.orig = n1.id
     AND e.dest = n2.id;

This query asks for is all information about edges that go from nodes labeled "alice" to nodes labeled "bob". The query optimizer in SQLite has basically two choices on how to implement this query. (There are actually six different choices, but we will only consider two of them here.) Pseudocode below demonstrating these two choices.

Option 1:

  foreach n1 where n1.name='alice' do:
    foreach n2 where n2.name='bob' do:
      foreach e where e.orig=n1.id and e.dest=n2.id
        return n1.*, n2.*, e.*
      end
    end
  end

Option 2:

  foreach n1 where n1.name='alice' do:
    foreach e where e.orig=n1.id do:
      foreach n2 where n2.id=e.dest and n2.name='bob' do:
        return n1.*, n2.*, e.*
      end
    end
  end

The same indices are used to speed up every loop in both implementation options. The only difference in these two query plans is the order in which the loops are nested.

So which query plan is better? It turns out that the answer depends on what kind of data is found in the node and edge tables.

Let the number of alice nodes be M and the number of bob nodes be N. Consider two scenarios. In the first scenario, M and N are both 2 but there are thousands of edges on each node. In this case, option 1 is preferred. With option 1, the inner loop checks for the existence of an edge between a pair of nodes and outputs the result if found. But because there are only 2 alice and bob nodes each, the inner loop only has to run 4 times and the query is very quick. Option 2 would take much longer here. The outer loop of option 2 only executes twice, but because there are a large number of edges leaving each alice node, the middle loop has to iterate many thousands of times. It will be much slower. So in the first scenario, we prefer to use option 1.

Now consider the case where M and N are both 3500. Alice nodes are abundant. But suppose each of these nodes is connected by only one or two edges. In this case, option 2 is preferred. With option 2, the outer loop still has to run 3500 times, but the middle loop only runs once or twice for each outer loop and the inner loop will only run once for each middle loop, if at all. So the total number of iterations of the inner loop is around 7000. Option 1, on the other hand, has to run both its outer loop and its middle loop 3500 times each, resulting in 12 million iterations of the middle loop. Thus in the second scenario, option 2 is nearly 2000 times faster than option 1.

So you can see that depending on how the data is structured in the table, either query plan 1 or query plan 2 might be better. Which plan does SQLite choose by default? As of version 3.6.18, without running ANALYZE, SQLite will choose option 2. But if the ANALYZE command is run in order to gather statistics, a different choice might be made if the statistics indicate that the alternative is likely to run faster.

5.2 Manual Control Of Query Plans

SQLite provides the ability for advanced programmers to exercise control over the query plan chosen by the optimizer. One method for doing this is to fudge the ANALYZE results in the sqlite_stat1 and sqlite_stat2 tables. That approach is not recommended except for the one scenario described in the following paragraph.

For a program that uses an SQLite database as its application file format, when a new database instances is first created the ANALYZE command is ineffective because the database contain no data from which to gather statistics. In that case, one could construct a large prototype database containing typical data during development and run the ANALYZE command on this prototype database to gather statistics, then save the prototype statistics as part of the application. After deployment, when the application goes to create a new database file, it can run the ANALYZE command in order to create the sqlite_stat1 and sqlite_stat2 tables, then copy the precomputed statistics obtained from the prototype database into these new statistics tables. In that way, statistics from large working data sets can be preloaded into newly created application files.

If you really must take manual control of join loop nesting order, the preferred method is to use some peculiar (though valid) SQL syntax to specify the join. If you use the keyword CROSS in a join, then the two tables connected by that join will not be reordered. So in the query, the optimizer is free to reorder the tables of the FROM clause anyway it sees fit:

  SELECT *
    FROM node AS n1,
         edge AS e,
         node AS n2
   WHERE n1.name = 'alice'
     AND n2.name = 'bob'
     AND e.orig = n1.id
     AND e.dest = n2.id;

But in the following logically equivalent formulation of the query, the substitution of "CROSS JOIN" for the "," means that the order of tables must be N1, E, N2.

  SELECT *
    FROM node AS n1 CROSS JOIN
         edge AS e CROSS JOIN
         node AS n2
   WHERE n1.name = 'alice'
     AND n2.name = 'bob'
     AND e.orig = n1.id
     AND e.dest = n2.id;

Hence, in the second form, the query plan must be option 2. Note that you must use the keyword CROSS in order to disable the table reordering optimization; INNER JOIN, NATURAL JOIN, JOIN, and other similar combinations work just like a comma join in that the optimizer is free to reorder tables as it sees fit. (Table reordering is also disabled on an outer join, but that is because outer joins are not associative or commutative. Reordering tables in outer joins changes the result.)

6.0 Choosing between multiple indices

Each table in the FROM clause of a query can use at most one index (except when the OR-clause optimization comes into play) and SQLite strives to use at least one index on each table. Sometimes, two or more indices might be candidates for use on a single table. For example:

  CREATE TABLE ex2(x,y,z);
  CREATE INDEX ex2i1 ON ex2(x);
  CREATE INDEX ex2i2 ON ex2(y);
  SELECT z FROM ex2 WHERE x=5 AND y=6;

For the SELECT statement above, the optimizer can use the ex2i1 index to lookup rows of ex2 that contain x=5 and then test each row against the y=6 term. Or it can use the ex2i2 index to lookup rows of ex2 that contain y=6 then test each of those rows against the x=5 term.

When faced with a choice of two or more indices, SQLite tries to estimate the total amount of work needed to perform the query using each option. It then selects the option that gives the least estimated work.

To help the optimizer get a more accurate estimate of the work involved in using various indices, the user may optionally run the ANALYZE command. The ANALYZE command scans all indices of database where there might be a choice between two or more indices and gathers statistics on the selectiveness of those indices. The statistics gathered by this scan are stored in special database tables names shows names all begin with "sqlite_stat". The content of these tables is not updated as the database changes so after making significant changes it might be prudent to rerun ANALYZE. The results of an ANALYZE command are only available to database connections that are opened after the ANALYZE command completes.

The various sqlite_stat N tables contain information on how selective the various indices are. For example, the sqlite_stat1 table might indicate that an equality constraint on column x reduces the search space to 10 rows on average, whereas an equality constraint on column y reduces the search space to 3 rows on average. In that case, SQLite would prefer to use index ex2i2 since that index.

Terms of the WHERE clause can be manually disqualified for use with indices by prepending a unary + operator to the column name. The unary + is a no-op and will not slow down the evaluation of the test specified by the term. But it will prevent the term from constraining an index. So, in the example above, if the query were rewritten as:

  SELECT z FROM ex2 WHERE +x=5 AND y=6;

The + operator on the x column will prevent that term from constraining an index. This would force the use of the ex2i2 index.

Note that the unary + operator also removes type affinity from an expression, and in some cases this can cause subtle changes in the meaning of an expression. In the example above, if column x has TEXT affinity then the comparison "x=5" will be done as text. But the + operator removes the affinity. So the comparison "+x=5" will compare the text in column x with the numeric value 5 and will always be false.

6.1 Range Queries

Consider a slightly different scenario:

  CREATE TABLE ex2(x,y,z);
  CREATE INDEX ex2i1 ON ex2(x);
  CREATE INDEX ex2i2 ON ex2(y);
  SELECT z FROM ex2 WHERE x BETWEEN 1 AND 100 AND y BETWEEN 1 AND 100;

Further suppose that column x contains values spread out between 0 and 1,000,000 and column y contains values that span between 0 and 1,000. In that scenario, the range constraint on column x should reduce the search space by a factor of 10,000 whereas the range constraint on column y should reduce the search space by a factor of only 10. So the ex2i1 index should be preferred.

SQLite will make this determination, but only if it has been compiled with SQLITE_ENABLE_STAT3. The SQLITE_ENABLE_STAT3 option causes the ANALYZE command to collect a histogram of column content in the sqlite_stat3 table and to use this histogram to make a better guess at the best query to use for range constraints such as the above.

The histogram data is only useful if the right-hand side of the constraint is a simple compile-time constant or parameter and not an expression.

Another limitation of the histogram data is that it only applies to the left-most column on an index. Consider this scenario:

  CREATE TABLE ex3(w,x,y,z);
  CREATE INDEX ex3i1 ON ex2(w, x);
  CREATE INDEX ex3i2 ON ex2(w, y);
  SELECT z FROM ex3 WHERE w=5 AND x BETWEEN 1 AND 100 AND y BETWEEN 1 AND 100;

Here the inequalities are on columns x and y which are not the left-most index columns. Hence, the histogram data which is collected no left-most column of indices is useless in helping to choose between the range constraints on columns x and y.

7.0 Avoidance of table lookups

When doing an indexed lookup of a row, the usual procedure is to do a binary search on the index to find the index entry, then extract the rowid from the index and use that rowid to do a binary search on the original table. Thus a typical indexed lookup involves two binary searches. If, however, all columns that were to be fetched from the table are already available in the index itself, SQLite will use the values contained in the index and will never look up the original table row. This saves one binary search for each row and can make many queries run twice as fast.

8.0 ORDER BY optimizations

SQLite attempts to use an index to satisfy the ORDER BY clause of a query when possible. When faced with the choice of using an index to satisfy WHERE clause constraints or satisfying an ORDER BY clause, SQLite does the same work analysis described above and chooses the index that it believes will result in the fastest answer.

9.0 Subquery flattening

When a subquery occurs in the FROM clause of a SELECT, the simplest behavior is to evaluate the subquery into a transient table, then run the outer SELECT against the transient table. But such a plan can be suboptimal since the transient table will not have any indices and the outer query (which is likely a join) will be forced to do a full table scan on the transient table.

To overcome this problem, SQLite attempts to flatten subqueries in the FROM clause of a SELECT. This involves inserting the FROM clause of the subquery into the FROM clause of the outer query and rewriting expressions in the outer query that refer to the result set of the subquery. For example:

  SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5

Would be rewritten using query flattening as:

  SELECT x+y AS a FROM t1 WHERE z<100 AND a>5

There is a long list of conditions that must all be met in order for query flattening to occur.

  1. The subquery and the outer query do not both use aggregates.
  2. The subquery is not an aggregate or the outer query is not a join.
  3. The subquery is not the right operand of a left outer join.
  4. The subquery is not DISTINCT or the outer query is not a join.
  5. The subquery is not DISTINCT or the outer query does not use aggregates.
  6. The subquery does not use aggregates or the outer query is not DISTINCT.
  7. The subquery has a FROM clause.
  8. The subquery does not use LIMIT or the outer query is not a join.
  9. The subquery does not use LIMIT or the outer query does not use aggregates.
  10. The subquery does not use aggregates or the outer query does not use LIMIT.
  11. The subquery and the outer query do not both have ORDER BY clauses.
  12. The subquery and outer query do not both use LIMIT.
  13. The subquery does not use OFFSET.
  14. The outer query is not part of a compound select or the subquery does not have both an ORDER BY and a LIMIT clause.
  15. The outer query is not an aggregate or the subquery does not contain ORDER BY.
  16. The sub-query is not a compound select, or it is a UNION ALL compound clause made up entirely of non-aggregate queries, and the parent query:
    • is not itself part of a compound select,
    • is not an aggregate or DISTINCT query, and
    • has no other tables or sub-selects in the FROM clause.
    The parent and sub-query may contain WHERE clauses. Subject to rules (11), (12) and (13), they may also contain ORDER BY, LIMIT and OFFSET clauses.
  17. If the sub-query is a compound select, then all terms of the ORDER by clause of the parent must be simple references to columns of the sub-query.
  18. The subquery does not use LIMIT or the outer query does not have a WHERE clause.
  19. If the sub-query is a compound select, then it must not use an ORDER BY clause.

The casual reader is not expected to understand or remember any part of the list above. The point of this list is to demonstrate that the decision of whether or not to flatten a query is complex.

Query flattening is an important optimization when views are used as each use of a view is translated into a subquery.

10.0 The MIN/MAX optimization

Queries of the following forms will be optimized to run in logarithmic time assuming appropriate indices exist:

  SELECT MIN(x) FROM table;
  SELECT MAX(x) FROM table;

In order for these optimizations to occur, they must appear in exactly the form shown above - changing only the name of the table and column. It is not permissible to add a WHERE clause or do any arithmetic on the result. The result set must contain a single column. The column in the MIN or MAX function must be an indexed column.

11.0 Automatic Indices

When no indices are available to aid the evaluation of a query, SQLite might create an automatic index that lasts only for the duration of a single SQL statement and use that index to help boost the query performance. Since the cost of constructing the automatic index is O(NlogN) (where N is the number of entries in the table) and the cost of doing a full table scan is only O(N), an automatic index will only be created if SQLite expects that the lookup will be run more than logN times during the course of the SQL statement. Consider an example:

  CREATE TABLE t1(a,b);
  CREATE TABLE t2(c,d);
  -- Insert many rows into both t1 and t2
  SELECT * FROM t1, t2 WHERE a=c;

In the query above, if both t1 and t2 have approximately N rows, then without any indices the query will require O(N*N) time. On the other hand, creating an index on table t2 requires O(NlogN) time and then using that index to evaluate the query requires an additional O(NlogN) time. In the absence of ANALYZE information, SQLite guesses that N is one million and hence it believes that constructing the automatic index will be the cheaper approach.

An automatic index might also be used for a subquery:

  CREATE TABLE t1(a,b);
  CREATE TABLE t2(c,d);
  -- Insert many rows into both t1 and t2
  SELECT a, (SELECT d FROM t2 WHERE c=b) FROM t1;

In this example, the t2 table is used in a subquery to translate values of the t1.b column. If each table contains N rows, SQLite expects that the subquery will run N times, and hence it will believe it is faster to construct an automatic, transient index on t2 first and then using that index to satisfy the N instances of the subquery.

The automatic indexing capability can be disabled at run-time using the automatic_index pragma and can be omitted from the build at compile-time using the SQLITE_OMIT_AUTOMATIC_INDEX compile-time option.


Pragma statements supported by SQLite

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

PRAGMA Statements

The PRAGMA statement is an SQL extension specific to SQLite and used to modify the operation of the SQLite library or to query the SQLite library for internal (non-table) data. The PRAGMA statement is issued using the same interface as other SQLite commands (e.g. SELECT, INSERT) but is different in the following important respects:

  • Specific pragma statements may be removed and others added in future releases of SQLite. There is no guarantee of backwards compatibility.
  • No error messages are generated if an unknown pragma is issued. Unknown pragmas are simply ignored. This means if there is a typo in a pragma statement the library does not inform the user of the fact.
  • Some pragmas take effect during the SQL compilation stage, not the execution stage. This means if using the C-language sqlite3_prepare(), sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper interface), the pragma may run during the sqlite3_prepare() call, not during the sqlite3_step() call as normal SQL statements do. Or the pragma might run during sqlite3_step() just like normal SQL statements. Whether or not the pragma runs during sqlite3_prepare() or sqlite3_step() depends on the pragma and on the specific release of SQLite.
  • The pragma command is specific to SQLite and is very unlikely to be compatible with any other SQL database engine.

PRAGMA command syntax

pragma-stmt:

syntax diagram pragma-stmt

pragma-value:

syntax diagram pragma-value

A pragma can take either zero or one argument. The argument is may be either in parentheses or it may be separated from the pragma name by an equal sign. The two syntaxes yield identical results. In many pragmas, the argument is a boolean. The boolean can be one of:

1 yes true on
0 no false off

Keyword arguments can optionally appear in quotes. (Example: 'yes' [FALSE].) Some pragmas takes a string literal as their argument. When pragma takes a keyword argument, it will usually also take a numeric equivalent as well. For example, "0" and "no" mean the same thing, as does "1" and "yes". When querying the value of a setting, many pragmas return the number rather than the keyword.

A pragma may have an optional database name before the pragma name. The database name is the name of an ATTACH-ed database or it can be "main" or "temp" for the main and the TEMP databases. If the optional database name is omitted, "main" is assumed. In some pragmas, the database name is meaningless and is simply ignored.

List Of PRAGMAs

  • auto_vacuum
  • automatic_index
  • cache_size
  • case_sensitive_like
  • checkpoint_fullfsync
  • collation_list
  • compile_options
  • count_changes¹
  • database_list
  • default_cache_size¹
  • empty_result_callbacks¹
  • encoding
  • foreign_key_list
  • foreign_keys
  • freelist_count
  • full_column_names¹
  • fullfsync
  • ignore_check_constraints
  • incremental_vacuum
  • index_info
  • index_list
  • integrity_check
  • journal_mode
  • journal_size_limit
  • legacy_file_format
  • locking_mode
  • max_page_count
  • page_count
  • page_size
  • parser_trace²
  • quick_check
  • read_uncommitted
  • recursive_triggers
  • reverse_unordered_selects
  • schema_version
  • secure_delete
  • short_column_names¹
  • synchronous
  • table_info
  • temp_store
  • temp_store_directory¹
  • user_version
  • vdbe_listing²
  • vdbe_trace²
  • wal_autocheckpoint
  • wal_checkpoint
  • writable_schema

Notes:

  1. Pragmas whose names are marked through in the list above are deprecated that are maintained for historical compatibility only. Do not use the deprecated pragmas in new applications. Remove deprecated pragmas from existing applications at your earliest opportunity.
  2. These pragmas are used for debugging SQLite itself and are only available when SQLite is compiled using SQLITE_DEBUG.

PRAGMA auto_vacuum;
PRAGMA auto_vacuum = 0 | NONE | 1 | FULL | 2 | INCREMENTAL;

Query or set the auto-vacuum status in the database.

The default setting for auto-vacuum is 0 or "none", unless the SQLITE_DEFAULT_AUTOVACUUM compile-time option is used. The "none" setting means that auto-vacuum is disabled. When auto-vacuum is disabled and data is deleted data from a database, the database file remains the same size. Unused database file pages are added to a "freelist" and reused for subsequent inserts. So no database file space is lost. However, the database file does not shrink. In this mode the VACUUM command can be used to rebuild the entire database file and thus reclaim unused disk space.

When the auto-vacuum mode is 1 or "full", the freelist pages are moved to the end of the database file and the database file is truncated to remove the freelist pages at every transaction commit. Note, however, that auto-vacuum only truncates the freelist pages from the file. Auto-vacuum does not defragment the database nor repack individual database pages the way that the VACUUM command does. In fact, because it moves pages around within the file, auto-vacuum can actually make fragmentation worse.

Auto-vacuuming is only possible if the database stores some additional information that allows each database page to be traced backwards to its referrer. Therefore, auto-vacuuming must be turned on before any tables are created. It is not possible to enable or disable auto-vacuum after a table has been created.

When the value of auto-vacuum is 2 or "incremental" then the additional information needed to do auto-vacuuming is stored in the database file but auto-vacuuming does not occur automatically at each commit as it does with auto_vacuum=full. In incremental mode, the separate incremental_vacuum pragma must be invoked to cause the auto-vacuum to occur.

The database connection can be changed between full and incremental autovacuum mode at any time. However, changing from "none" to "full" or "incremental" can only occur when the database is new (no tables have yet been created) or by running the VACUUM command. To change auto-vacuum modes, first use the auto_vacuum pragma to set the new desired mode, then invoke the VACUUM command to reorganize the entire database file. To change from "full" or "incremental" back to "none" always requires running VACUUM even on an empty database.

When the auto_vacuum pragma is invoked with no arguments, it returns the current auto_vacuum mode.

PRAGMA automatic_index;
PRAGMA automatic_index = boolean;

Query, set, or clear the automatic indexing capability.

Automatic indexing is enabled by default.

PRAGMA cache_size;
PRAGMA cache_size = Number-of-pages;

Query or change the suggested maximum number of database disk pages that SQLite will hold in memory at once per open database file. Whether or not this suggestion is honored is at the discretion of the Application Defined Page Cache. Alternative application-defined page cache implementations may choose to interpret the suggested cache size in different ways or to ignore it all together. The default suggested cache size is 2000.

The suggested cache size is set to the absolute value of the Number-of-pages argument given to this pragma.

When you change the cache size using the cache_size pragma, the change only endures for the current session. The cache size reverts to the default value when the database is closed and reopened. Use the default_cache_size pragma to check the cache size permanently.

PRAGMA case_sensitive_like = boolean;

The default behavior of the LIKE operator is to ignore case for ASCII characters. Hence, by default 'a' LIKE 'A' is true. The case_sensitive_like pragma installs a new application-defined LIKE function that is either case sensitive or insensitive depending on the value of the case_sensitive_like pragma. When case_sensitive_like is disabled, the default LIKE behavior is expressed. When case_sensitive_like is enabled, case becomes significant. So, for example, 'a' LIKE 'A' is false but 'a' LIKE 'a' is still true.

This pragma uses sqlite3_create_function() to overload the LIKE and GLOB functions, which may override previous implementations of LIKE and GLOB registered by the application.

PRAGMA checkpoint_fullfsync
PRAGMA checkpoint_fullfsync = boolean;

Query or change the fullfsync flag for checkpoint operations. If this flag is set, then the F_FULLFSYNC syncing method is used during checkpoint operations on systems that support F_FULLFSYNC. The default value of the checkpoint_fullfsync flag is off. Only Mac OS-X supports F_FULLFSYNC.

If the fullfsync flag is set, then the F_FULLFSYNC syncing method is used for all sync operations and the checkpoint_fullfsync setting is irrelevant.

PRAGMA collation_list;

Return a list of the collating sequences defined for the current database connection.

PRAGMA compile_options;

This pragma returns the names of compile-time options used when building SQLite, one option per row. The "SQLITE_" prefix is omitted from the returned option names. See also the sqlite3_compileoption_get() C/C++ interface and the sqlite_compileoption_get() SQL functions.

PRAGMA count_changes;
PRAGMA count_changes = boolean;

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

Query or change the count-changes flag. Normally, when the count-changes flag is not set, INSERT, UPDATE and DELETE statements return no data. When count-changes is set, each of these commands returns a single row of data consisting of one integer value - the number of rows inserted, modified or deleted by the command. The returned change count does not include any insertions, modifications or deletions performed by triggers, or any changes made automatically by foreign key actions.

Another way to get the row change counts is to use the sqlite3_changes() or sqlite3_total_changes() interfaces. There is a subtle different, though. When an INSERT, UPDATE, or DELETE is run against a view using an INSTEAD OF trigger, the count_changes pragma reports the number of rows in the view that fired the trigger, whereas sqlite3_changes() and sqlite3_total_changes() do not.

PRAGMA database_list;

This pragma works like a query to return one row for each database attached to the current database connection. The second column is the "main" for the main database file, "temp" for the database file used to store TEMP objects, or the name of the ATTACHed database for other database files. The third column is the name of the database file itself, or an empty string if the database is not associated with a file.

PRAGMA default_cache_size;
PRAGMA default_cache_size = Number-of-pages;

This pragma queries or sets the suggested maximum number of pages of disk cache that will be allocated per open database file. The difference between this pragma and cache_size is that the value set here persists across database connections. The value of the default cache size is stored in the 4-byte big-endian integer located at offset 48 in the header of the database file.

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

PRAGMA empty_result_callbacks;
PRAGMA empty_result_callbacks = boolean;

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

Query or change the empty-result-callbacks flag.

The empty-result-callbacks flag affects the sqlite3_exec() API only. Normally, when the empty-result-callbacks flag is cleared, the callback function supplied to the sqlite3_exec() is not invoked for commands that return zero rows of data. When empty-result-callbacks is set in this situation, the callback function is invoked exactly once, with the third parameter set to 0 (NULL). This is to enable programs that use the sqlite3_exec() API to retrieve column-names even when a query returns no data.

PRAGMA encoding;
PRAGMA encoding = "UTF-8";
PRAGMA encoding = "UTF-16";
PRAGMA encoding = "UTF-16le";
PRAGMA encoding = "UTF-16be";

In first form, if the main database has already been created, then this pragma returns the text encoding used by the main database, one of "UTF-8", "UTF-16le" (little-endian UTF-16 encoding) or "UTF-16be" (big-endian UTF-16 encoding). If the main database has not already been created, then the value returned is the text encoding that will be used to create the main database, if it is created by this session.

The second through fifth forms of this pragma set the encoding that the main database will be created with if it is created by this session. The string "UTF-16" is interpreted as "UTF-16 encoding using native machine byte-ordering". It is not possible to change the text encoding of a database after it has been created and any attempt to do so will be silently ignored.

Once an encoding has been set for a database, it cannot be changed.

Databases created by the ATTACH command always use the same encoding as the main database. An attempt to ATTACH a database with a different text encoding from the "main" database will fail.

PRAGMA foreign_key_list(table-name);

This pragma returns one row for each foreign key that references a column in the argument table.

PRAGMA foreign_keys;
PRAGMA foreign_keys = boolean;

Query, set, or clear the enforcement of foreign key constraints.

This pragma is a no-op within a transaction; foreign key constraint enforcement may only be enabled or disabled when there is no pending BEGIN or SAVEPOINT.

Changing the foreign_keys setting affects the execution of all statements prepared using the database connection, including those prepared before the setting was changed. Any existing statements prepared using the legacy sqlite3_prepare() interface may fail with an SQLITE_SCHEMA error after the foreign_keys setting is changed.

As of SQLite version 3.6.19, the default setting for foreign key enforcement is OFF. However, that might change in a future release of SQLite. The default setting for foreign key enforcement can be specified at compile-time using the SQLITE_DEFAULT_FOREIGN_KEYS preprocessor macro. To minimize future problems, applications should set the foreign key enforcement flag as required by the application and not depend on the default setting.

PRAGMA freelist_count;

Return the number of unused pages in the database file.

PRAGMA full_column_names;
PRAGMA full_column_names = boolean;

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

Query or change the full_column_names flag. This flag together with the short_column_names flag determine the way SQLite assigns names to result columns of SELECT statements. Result columns are named by applying the following rules in order:

  1. If there is an AS clause on the result, then the name of the column is the right-hand side of the AS clause.

  2. If the result is a general expression, not a just the name of a source table column, then the name of the result is a copy of the expression text.

  3. If the short_column_names pragma is ON, then the name of the result is the name of the source table column without the source table name prefix: COLUMN.

  4. If both pragmas short_column_names and full_column_names are OFF then case (2) applies.

  5. The name of the result column is a combination of the source table and source column name: TABLE.COLUMN

PRAGMA fullfsync
PRAGMA fullfsync = boolean;

Query or change the fullfsync flag. This flag determines whether or not the F_FULLFSYNC syncing method is used on systems that support it. The default value of the fullfsync flag is off. Only Mac OS X supports F_FULLFSYNC.

See also checkpoint_fullfsync.

PRAGMA ignore_check_constraints = boolean;

This pragma enables or disables the enforcement of CHECK constraints. The default setting is off, meaning that CHECK constraints are enforced by default.

PRAGMA incremental_vacuum(N);

The incremental_vacuum pragma causes up to N pages to be removed from the freelist. The database file is truncated by the same amount. The incremental_vacuum pragma has no effect if the database is not in auto_vacuum=incremental mode or if there are no pages on the freelist. If there are fewer than N pages on the freelist, or if N is less than 1, or if N is omitted entirely, then the entire freelist is cleared.

PRAGMA index_info(index-name);

This pragma returns one row each column in the named index. The first column of the result is the rank of the column within the index. The second column of the result is the rank of the column within the table. The third column of output is the name of the column being indexed.

PRAGMA index_list(table-name);

This pragma returns one row for each index associated with the given table. Columns of the result set include the index name and a flag to indicate whether or not the index is UNIQUE.

PRAGMA integrity_check;
PRAGMA integrity_check(integer)

This pragma does an integrity check of the entire database. It looks for out-of-order records, missing pages, malformed records, and corrupt indices. If any problems are found, then strings are returned (as multiple rows with a single column per row) which describe the problems. At most integer errors will be reported before the analysis quits. The default value for integer is 100. If no errors are found, a single row with the value "ok" is returned.

PRAGMA journal_mode;
PRAGMA database.journal_mode;
PRAGMA journal_mode = DELETE | TRUNCATE | PERSIST | MEMORY | WAL | OFF
PRAGMA database.journal_mode = DELETE | TRUNCATE | PERSIST | MEMORY | WAL | OFF

This pragma queries or sets the journal mode for databases associated with the current database connection.

The first two forms of this pragma query the current journaling mode for database. When database is omitted, the "main" database is queried.

The last two forms change the journaling mode. The 4th form changes the journaling mode for a specific database connection named. Use "main" for the main database (the database that was opened by the original sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() interface call) and use "temp" for database that holds TEMP tables. The 3rd form changes the journaling mode on all databases attached to the connection. The new journal mode is returned. If the journal mode could not be changed, the original journal mode is returned.

The DELETE journaling mode is the normal behavior. In the DELETE mode, the rollback journal is deleted at the conclusion of each transaction. Indeed, the delete operation is the action that causes the transaction to commit. (See the documented titled Atomic Commit In SQLite for additional detail.)

The TRUNCATE journaling mode commits transactions by truncating the rollback journal to zero-length instead of deleting it. On many systems, truncating a file is much faster than deleting the file since the containing directory does not need to be changed.

The PERSIST journaling mode prevents the rollback journal from being deleted at the end of each transaction. Instead, the header of the journal is overwritten with zeros. This will prevent other database connections from rolling the journal back. The PERSIST journaling mode is useful as an optimization on platforms where deleting or truncating a file is much more expensive than overwriting the first block of a file with zeros.

The MEMORY journaling mode stores the rollback journal in volatile RAM. This saves disk I/O but at the expense of database safety and integrity. If the application using SQLite crashes in the middle of a transaction when the MEMORY journaling mode is set, then the database file will very likely go corrupt.

The WAL journaling mode uses a write-ahead log instead of a rollback journal to implement transactions. The WAL journaling mode is persistent; after being set it stays in effect across multiple database connections and after closing and reopening the database. A database in WAL journaling mode can only be accessed by SQLite version 3.7.0 or later.

The OFF journaling mode disables the rollback journal completely. No rollback journal is ever created and hence there is never a rollback journal to delete. The OFF journaling mode disables the atomic commit and rollback capabilities of SQLite. The ROLLBACK command no longer works; it behaves in an undefined way. Applications must avoid using the ROLLBACK command when the journal mode is OFF. If the application crashes in the middle of a transaction when the OFF journaling mode is set, then the database file will very likely go corrupt.

Note that the journal_mode for an in-memory database is either MEMORY or OFF and can not be changed to a different value. An attempt to change the journal_mode of an in-memory database to any setting other than MEMORY or OFF is ignored. Note also that the journal_mode cannot be changed while a transaction is active.

PRAGMA journal_size_limit
PRAGMA journal_size_limit = N ;

If a database connection is operating in either "exclusive mode" (PRAGMA locking_mode=exclusive) or "persistent journal mode" (PRAGMA journal_mode=persist) then under certain circumstances after committing a transaction the journal file may remain in the file-system. This increases efficiency but also consumes space in the file-system. After a large transaction (e.g. a VACUUM), it may consume a very large amount of space.

This pragma may be used to limit the size of journal files left in the file-system after transactions are committed on a per database basis. Each time a transaction is committed, SQLite compares the size of the journal file left in the file-system to the size limit configured using this pragma and if the journal file is larger than the limit allows for, it is truncated to the limit.

The second form of the pragma listed above is used to set a new limit in bytes for the specified database. A negative number implies no limit. Both the first and second forms of the pragma listed above return a single result row containing a single integer column - the value of the journal size limit in bytes. The default limit value is -1 (no limit), which may be overridden by defining the preprocessor macro SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT at compile time.

This pragma only operates on the single database specified prior to the pragma name (or on the "main" database if no database is specified.) There is no way to operate on all attached databases using a single PRAGMA statement, nor is there a way to set the limit to use for databases that will be attached in the future.

PRAGMA legacy_file_format;
PRAGMA legacy_file_format = boolean

This pragma sets or queries the value of the legacy_file_format flag. When this flag is on, new SQLite databases are created in a file format that is readable and writable by all versions of SQLite going back to 3.0.0. When the flag is off, new databases are created using the latest file format which might not be readable or writable by versions of SQLite prior to 3.3.0.

When the legacy_file_format pragma is issued with no argument, it returns the setting of the flag. This pragma does not tell which file format the current database is using; it tells what format will be used by any newly created databases.

The legacy_file_format pragma is initialized to OFF when an existing database in the newer file format is first opened.

The default file format is set by the SQLITE_DEFAULT_FILE_FORMAT compile-time option.

PRAGMA locking_mode;
PRAGMA locking_mode = NORMAL | EXCLUSIVE

This pragma sets or queries the database connection locking-mode. The locking-mode is either NORMAL or EXCLUSIVE.

In NORMAL locking-mode (the default unless overridden at compile-time using SQLITE_DEFAULT_LOCKING_MODE), a database connection unlocks the database file at the conclusion of each read or write transaction. When the locking-mode is set to EXCLUSIVE, the database connection never releases file-locks. The first time the database is read in EXCLUSIVE mode, a shared lock is obtained and held. The first time the database is written, an exclusive lock is obtained and held.

Database locks obtained by a connection in EXCLUSIVE mode may be released either by closing the database connection, or by setting the locking-mode back to NORMAL using this pragma and then accessing the database file (for read or write). Simply setting the locking-mode to NORMAL is not enough - locks are not be released until the next time the database file is accessed.

There are three reasons to set the locking-mode to EXCLUSIVE.

  1. The application wants to prevent other processes from accessing the database file.
  2. The number of system calls for filesystem operations is reduced, possibly resulting in a small performance increase.
  3. WAL databases can be accessed in EXCLUSIVE mode without the use of shared memory. (Additional information)

When the locking_mode pragma specifies a particular database, for example:

PRAGMA main.locking_mode=EXCLUSIVE;

Then the locking mode applies only to the named database. If no database name qualifier precedes the "locking_mode" keyword then the locking mode is applied to all databases, including any new databases added by subsequent ATTACH commands.

The "temp" database (in which TEMP tables and indices are stored) and in-memory databases always uses exclusive locking mode. The locking mode of temp and in-memory databases cannot be changed. All other databases use the normal locking mode by default and are affected by this pragma.

If the locking mode is EXCLUSIVE when first entering WAL journal mode, then the locking mode cannot be changed to NORMAL until after exiting WAL journal mode. If the locking mode is NORMAL when first entering WAL journal mode, then the locking mode can be changed between NORMAL and EXCLUSIVE and back again at any time and without needing to exit WAL journal mode.

PRAGMA max_page_count;
PRAGMA max_page_count = N;

Query or set the maximum number of pages in the database file. Both forms of the pragma return the maximum page count. The second form attempts to modify the maximum page count. The maximum page count cannot be reduced below the current database size.

PRAGMA page_count;

Return the total number of pages in the database file.

PRAGMA page_size;
PRAGMA page_size = bytes;

Query or set the page size of the database. The page size must be a power of two between 512 and 65536 inclusive.

When a new database is created, SQLite assigned a default page size based on information received from the xSectorSize and xDeviceCharacteristics methods of the sqlite3_io_methods object of the newly created database file. The page_size pragma will only cause an immediate change in the page size if it is issued while the database is still empty, prior to the first CREATE TABLE statement. If the page_size pragma is used to specify a new page size just prior to running the VACUUM command and if the database is not in WAL journal mode then VACUUM will change the page size to the new value.

If SQLite is compiled with the SQLITE_ENABLE_ATOMIC_WRITE option, then the default page size is chosen to be the largest page size less than or equal to SQLITE_MAX_DEFAULT_PAGE_SIZE for which atomic write is enabled according to the xDeviceCharacteristics method of the sqlite3_io_methods object for the database file. If the SQLITE_ENABLE_ATOMIC_WRITE option is disabled or if xDeviceCharacteristics reports no suitable atomic write page sizes, then the default page size is the larger of SQLITE_DEFAULT_PAGE_SIZE and the sector size as reported by the xSectorSize method of the sqlite3_io_methods object, but not more than SQLITE_MAX_DEFAULT_PAGE_SIZE. The normal configuration for SQLite running on workstations is for atomic write to be disabled, for the maximum page size to be set to 65536, for SQLITE_DEFAULT_PAGE_SIZE to be 1024, and for the maximum default page size to be set to 8192. The default xSectorSize method on unix workstation implementations always reports a sector size of 512 bytes. Hence, the default page size chosen by SQLite on unix is usually 1024 bytes. On windows, the GetDiskFreeSpace() interface is used to obtain the actual device sector size and hence the default page size on windows will sometimes be greater than 1024.

PRAGMA parser_trace = boolean;

This pragma is intended for use when debugging SQLite itself. It is only contained in the build when the SQLITE_DEBUG compile-time option is used.

If SQLite has been compiled with the SQLITE_DEBUG compile-time option, then the parser_trace pragma can be used to turn on tracing for the SQL parser used internally by SQLite. This feature is used for debugging SQLite itself.

PRAGMA quick_check;
PRAGMA quick_check(integer)

The pragma is like integrity_check except that it does not verify that index content matches table content. By skipping the verification of index content, quick_check is able to run much faster than integrity_check. Otherwise the two pragmas are the same.

PRAGMA read_uncommitted;
PRAGMA read_uncommitted = boolean;

Query, set, or clear READ UNCOMMITTED isolation. The default isolation level for SQLite is SERIALIZABLE. Any process or thread can select READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except between connections that share a common page and schema cache. Cache sharing is enabled using the sqlite3_enable_shared_cache() API. Cache sharing is disabled by default.

See SQLite Shared-Cache Mode for additional information.

PRAGMA recursive_triggers;
PRAGMA recursive_triggers = boolean;

Query, set, or clear the recursive trigger capability.

Changing the recursive_triggers setting affects the execution of all statements prepared using the database connection, including those prepared before the setting was changed. Any existing statements prepared using the legacy sqlite3_prepare() interface may fail with an SQLITE_SCHEMA error after the recursive_triggers setting is changed.

Prior to SQLite version 3.6.18, recursive triggers were not supported. The behavior of SQLite was always as if this pragma was set to OFF. Support for recursive triggers was added in version 3.6.18 but was initially turned OFF by default, for compatibility. Recursive triggers may be turned on by default in future versions of SQLite.

The depth of recursion for triggers has a hard upper limit set by the SQLITE_MAX_TRIGGER_DEPTH compile-time option and a run-time limit set by sqlite3_limit(db,SQLITE_LIMIT_TRIGGER_DEPTH,...).

PRAGMA reverse_unordered_selects;
PRAGMA reverse_unordered_selects = boolean;

When enabled, this PRAGMA causes SELECT statements without an ORDER BY clause to emit their results in the reverse order of what they normally would. This can help debug applications that are making invalid assumptions about the result order.

SQLite makes no guarantees about the order of results if a SELECT omits the ORDER BY clause. Even so, the order of results does not change from one run to the next, and so many applications mistakenly come to depend on the arbitrary output order whatever that order happens to be. However, sometimes new versions of SQLite will contain optimizer enhancements that will cause the output order of queries without ORDER BY clauses to shift. When that happens, applications that depend on a certain output order might malfunction. By running the application multiple times with this pragma both disabled and enabled, cases where the application makes faulty assumptions about output order can be identified and fixed early, reducing problems that might be caused by linking against a different version of SQLite.

PRAGMA schema_version;
PRAGMA schema_version = integer ;
PRAGMA user_version;
PRAGMA user_version = integer ;

The pragmas schema_version and user_version are used to set or get the value of the schema-version and user-version, respectively. The schema-version and the user-version are big-endian 32-bit signed integers stored in the database header at offsets 40 and 60, respectively.

The schema-version is usually only manipulated internally by SQLite. It is incremented by SQLite whenever the database schema is modified (by creating or dropping a table or index). The schema version is used by SQLite each time a query is executed to ensure that the internal cache of the schema used when compiling the SQL query matches the schema of the database against which the compiled query is actually executed. Subverting this mechanism by using "PRAGMA schema_version" to modify the schema-version is potentially dangerous and may lead to program crashes or database corruption. Use with caution!

The user-version is not used internally by SQLite. It may be used by applications for any purpose.

PRAGMA secure_delete;
PRAGMA database.secure_delete;
PRAGMA secure_delete = boolean
PRAGMA database.secure_delete =
               boolean

Query or change the secure-delete setting. When secure-delete on, SQLite overwrites deleted content with zeros. The default setting is determined by the SQLITE_SECURE_DELETE compile-time option.

When there are attached databases and no database is specified in the pragma, all databases have their secure-delete setting altered. The secure-delete setting for newly attached databases is the setting of the main database at the time the ATTACH command is evaluated.

When multiple database connections share the same cache, changing the secure-delete flag on one database connection changes it for them all.

PRAGMA short_column_names;
PRAGMA short_column_names = boolean;

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

Query or change the short-column-names flag. This flag affects the way SQLite names columns of data returned by SELECT statements. See the full_column_names pragma for full details.

PRAGMA synchronous;
PRAGMA synchronous = 0 | OFF | 1 | NORMAL | 2 | FULL;

Query or change the setting of the "synchronous" flag. The first (query) form will return the synchronous setting as an integer. When synchronous is FULL (2), the SQLite database engine will use the xSync method of the VFS to ensure that all content is safely written to the disk surface prior to continuing. This ensures that an operating system crash or power failure will not corrupt the database. FULL synchronous is very safe, but it is also slower. When synchronous is NORMAL (1), the SQLite database engine will still sync at the most critical moments, but less often than in FULL mode. There is a very small (though non-zero) chance that a power failure at just the wrong time could corrupt the database in NORMAL mode. But in practice, you are more likely to suffer a catastrophic disk failure or some other unrecoverable hardware fault. With synchronous OFF (0), SQLite continues without syncing as soon as it has handed data off to the operating system. If the application running SQLite crashes, the data will be safe, but the database might become corrupted if the operating system crashes or the computer loses power before that data has been written to the disk surface. On the other hand, some operations are as much as 50 or more times faster with synchronous OFF.

In WAL mode when synchronous is NORMAL (1), the WAL file is synchronized before each checkpoint and the database file is synchronized after each completed checkpoint, but no other sync operations occur. With synchronous=FULL in WAL mode, an additional sync operation of the WAL file happens after each transaction commit. If durability is not a concern, then synchronous=NORMAL is normally all one needs in WAL mode.

The default setting is synchronous=FULL.

See also the fullfsync and checkpoint_fullfsync pragmas.

PRAGMA table_info(table-name);

This pragma returns one row for each column in the named table. Columns in the result set include the column name, data type, whether or not the column can be NULL, and the default value for the column.

PRAGMA temp_store;
PRAGMA temp_store = 0 | DEFAULT | 1 | FILE | 2 | MEMORY;

Query or change the setting of the "temp_store" parameter. When temp_store is DEFAULT (0), the compile-time C preprocessor macro SQLITE_TEMP_STORE is used to determine where temporary tables and indices are stored. When temp_store is MEMORY (2) temporary tables and indices are kept in as if they were pure in-memory databases memory. When temp_store is FILE (1) temporary tables and indices are stored in a file. The temp_store_directory pragma can be used to specify the directory containing temporary files when FILE is specified. When the temp_store setting is changed, all existing temporary tables, indices, triggers, and views are immediately deleted.

It is possible for the library compile-time C preprocessor symbol SQLITE_TEMP_STORE to override this pragma setting. The following table summarizes the interaction of the SQLITE_TEMP_STORE preprocessor macro and the temp_store pragma:

SQLITE_TEMP_STORE PRAGMA
temp_store 		Storage used for
TEMP tables and indices
0 | any | file
1 | 0 | file
1 | 1 | file
1 | 2 | memory
2 | 0 | memory
2 | 1 | file
2 | 2 | memory
3 | any | memory

PRAGMA temp_store_directory;
PRAGMA temp_store_directory = 'directory-name';

Query or change the value of the sqlite3_temp_directory global variable, which many operating-system interface backends use to determine where to store temporary tables and indices.

Do not use this pragma! This pragma is deprecated and exists for backwards compatibility only. New applications should avoid using this pragma. Older applications should discontinue use of this pragma at the earliest opportunity. This pragma may be omitted from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.

When the temp_store_directory setting is changed, all existing temporary tables, indices, triggers, and viewers in the database connection that issued the pragma are immediately deleted. In practice, temp_store_directory should be set immediately after the first database connection for a process is opened. If the temp_store_directory is changed for one database connection while other database connections are open in the same process, then the behavior is undefined and probably undesirable.

Changing the temp_store_directory setting is not threadsafe. Never change the temp_store_directory setting if another thread within the application is running any SQLite interface at the same time. Doing so results in undefined behavior. Changing the temp_store_directory setting writes to the sqlite3_temp_directory global variable and that global variable is not protected by a mutex.

The value directory-name should be enclosed in single quotes. To revert the directory to the default, set the directory-name to an empty string, e.g., PRAGMA temp_store_directory = ''. An error is raised if directory-name is not found or is not writable.

The default directory for temporary files depends on the OS. Some OS interfaces may choose to ignore this variable and place temporary files in some other directory different from the directory specified here. In that sense, this pragma is only advisory.

PRAGMA vdbe_listing = boolean;

This pragma is intended for use when debugging SQLite itself. It is only contained in the build when the SQLITE_DEBUG compile-time option is used.

If SQLite has been compiled with the SQLITE_DEBUG compile-time option, then the vdbe_listing pragma can be used to cause a complete listing of the virtual machine opcodes to appear on standard output as each statement is evaluated. With listing is on, the entire content of a program is printed just prior to beginning execution. The statement executes normally after the listing is printed. This feature is used for debugging SQLite itself. See the VDBE documentation for more information.

PRAGMA vdbe_trace = boolean;

This pragma is intended for use when debugging SQLite itself. It is only contained in the build when the SQLITE_DEBUG compile-time option is used.

If SQLite has been compiled with the SQLITE_DEBUG compile-time option, then the vdbe_trace pragma can be used to cause virtual machine opcodes to be printed on standard output as they are evaluated. This feature is used for debugging SQLite. See the VDBE documentation for more information.

PRAGMA wal_autocheckpoint;
PRAGMA wal_autocheckpoint=N;

This pragma queries or sets the write-ahead log auto-checkpoint interval. When the write-ahead log is enabled (via the journal_mode pragma) a checkpoint will be run automatically whenever the write-ahead log equals or exceeds N pages in length. Setting the auto-checkpoint size to zero or a negative value turns auto-checkpointing off.

This pragma is a wrapper around the sqlite3_wal_autocheckpoint() C interface.

Autocheckpointing is enabled by default with an interval of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT.

PRAGMA database.wal_checkpoint;
PRAGMA database.wal_checkpoint(PASSIVE);
PRAGMA database.wal_checkpoint(FULL);
PRAGMA database.wal_checkpoint(RESTART);

If the write-ahead log is enabled (via the journal_mode pragma), this pragma causes a checkpoint operation to run on database database, or on all attached databases if database is omitted. If write-ahead log is disabled, this pragma is a harmless no-op.

Invoking this pragma is equivalent to calling the sqlite3_wal_checkpoint_v2() C interface with a 3rd parameter corresponding to the argument of the PRAGMA. Invoking this pragma without an argument is equivalent to calling the sqlite3_wal_checkpoint() C interface.

PRAGMA writable_schema = boolean;

When this pragma is on, the SQLITE_MASTER tables in which database can be changed using ordinary UPDATE, INSERT, and DELETE statements. Warning: misuse of this pragma can easily result in a corrupt database file.


FOR IMMEDIATE RELEASE:

SQLite Consortium Launches With Mozilla And Symbian As Charter Members

Ensures independent technical direction for world's most deployed SQL database engine

Charlotte, North Carolina - December 12, 2007 - The SQLite Consortium, a new membership association dedicated to maintaining SQLite as a fully open and independent product, was formally announced today. Mozilla and Symbian Ltd. have joined the SQLite Consortium as charter members.

SQLite is a compact, high efficiency, high reliability, embeddable SQL database engine. The source code to SQLite is in the public domain and is available with no associated fees. SQLite is the most deployed SQL database engine in the world and is currently used in a wide range of commercial software products and electronic devices from leading manufacturers. SQLite is found today in many mobile phones, MP3 players, set-top boxes, and PCs.

The mission of the SQLite Consortium is to continue developing and enhancing SQLite as a product that anyone may use without paying royalties or licensing fees. Members of the SQLite Consortium provide funding to enable this mission and in return receive enterprise-level technical support. Technical control and direction of SQLite remains entirely with the SQLite developers.

Mozilla, developer of the popular open-source Firefox web browser, and Symbian, the market-leading open operating system for advanced data-enabled smartphones, both deploy the SQLite database engine in their products. As charter members of the Consortium, Mozilla and Symbian are ensuring the development and support of SQLite as a freely accessible and public domain software asset.

"SQLite has become a popular embedded database because it is lightweight, fast, and open source," said Michael Schroepfer, Vice President of Engineering, Mozilla. "As a charter member of the SQLite Consortium, Mozilla is excited to help ensure SQLite remains a vibrant and open technology, in line with our mission to promote choice and innovation on the Internet."

"The SQLite Consortium will help set the standards for database management which are essential in smartphone functionality and will also help create a pool of developers, highly-skilled in SQLite for future mobile phone development, " said Bruce Carney, Director, Developer Programmes & Services, Symbian. "Our involvement with the SQL Consortium not only demonstrates Symbian's commitment to open standards in the industry, but as mobile phones become increasingly powerful and smartphones become increasingly popular, we are focused on ensuring that desktop developers, who move to the mobile space, have the easiest and most productive experience possible."

SQLite is a winner of the 2005 Google/O'Reilly Open Source Award. Additional information regarding the SQLite Consortium is available at the SQLite website, http://www.sqlite.org/.

# # #

About SQLite

SQLite is a software library that implements a self-contained, embeddable, serverless, zero-configuration, transactional SQL database engine. The code for SQLite is in the public domain and is free for any use, commercial or private. SQLite is currently found in countless software titles and electronic devices.

SQLite was originally developed and released 2000 by Dr. D. Richard Hipp. The code continues to be maintained and enhanced by an international team of developers under Hipp's direction.

CONTACT INFORMATION:
SQLite Consortium
Dr. D. Richard Hipp
6200 Maple Cove Lane
Charlotte, NC 28269
Email: drh@sqlite.org
http://www.sqlite.org/
Tel: +1.704.948.4565

About Mozilla

Mozilla is a global community dedicated to building free, open source products and technologies that improve the online experience for people everywhere. Mozilla works in the open with a highly disciplined, transparent and cooperative development process, under the umbrella of the non-profit Mozilla Foundation. As a wholly owned subsidiary, the Mozilla Corporation organizes the development and marketing of Mozilla products. This unique structure has enabled Mozilla to financially support and cultivate competitive, viable community innovation. For more information, visit www.mozilla.com.

CONTACT INFORMATION:
Mozilla Corporation
Jessica Waight
Tel: +1.415.345.4754
Email: jwaight@outcastpr.com

About Symbian Limited

Symbian is a software licensing company that develops and licenses Symbian OS, the market-leading open operating system for advanced, data-enabled mobile phones known as smartphones.

Symbian licenses Symbian OS to the world's leading handset manufacturers and has built close co-operative business relationships with leading companies across the mobile industry. During Q3 2007, 20.4 million Symbian smartphones were sold worldwide to over 250 major network operators, bringing the total number of Symbian smartphones shipped up to 30 September 2007 to 165 million.

Symbian has its headquarters in London, United Kingdom, with offices in the United States, United Kingdom, Asia (India, P.R. China, and Korea) and Japan. For more information, please visit www.symbian.com.

CONTACT INFORMATION:
Symbian Global Press Office
Karen Hamblen
+44 207 154 1707
press@symbian.com


Private Branches Of SQLite

Choose any three.
About Sitemap Documentation Download License News Support

Maintaining Private Branches Of SQLite

1.0 Introduction

SQLite is designed to meet most developer's needs without any changes or customization. When changes are needed, they can normally be accomplished using start-time (1) or runtime (2) (3) (4) configuration methods or via compile-time options. It is very rare that an application developer will need to edit the SQLite source code in order to incorporate SQLite into a product.

We call custom modifications to the SQLite source code that are held for the use of a single application a "private branch". When a private branch becomes necessary, the application developer must take on the task of keeping the private branch in synchronization with the public SQLite sources. This is tedious. It can also be tricky, since while the SQLite file format and published interfaces are very stable, the internal implementation of SQLite changes quite rapidly. Hundreds or thousands of lines of code might change for any given SQLite point release.

This article outlines one possible method for keeping a private branch of SQLite in sync with the public SQLite source code. There are many ways of maintaining a private branch, of course. Nobody is compelled to use the method describe here. This article is not trying to impose a particular procedure on maintainers of private branches. The point of this article is to offer an example of one process for maintaining a private branch which can be used as a template for designing processes best suited for the circumstances of each individual project.

2.0 The Basic Idea

We propose to use the fossil software configuration management system to set up two branches. One branch (the "public branch" or "trunk") contains the published SQLite sources and the other branch is the private branch which contains the code that is customized for the project. Whenever a new public release of SQLite is made, that release is added to the public branch and then the changes are merged into the private branch.

This document proposes to use fossil, but any other distributed software configuration management system such as monotone or mercurial (a.k.a. "hg"), or git could serve just as well. The concept will be the same, though the specifics of the procedure will vary.

The diagram at the right illustrates the concept. One begins with a standard SQLite release. For the sake of example, suppose that one intends to create a private branch off of SQLite version 3.6.15. In the diagram this is version (1). The maintainer makes an exact copy of the baseline SQLite into the branch space, shown as version (2). Note that (1) and (2) are exactly the same. Then the maintainer applies the private changes to version (2) resulting in version (3). In other words, version (3) is SQLite version 3.6.15 plus edits.

Later, SQLite version 3.6.16 is released, as shown by circle (4) in the diagram. At the point, the private branch maintainer does a merge which takes all of the changes going from (1) to (4) and applies those changes to (3). The result is version (5), which is SQLite 3.6.16 plus edits.

There might be merge conflicts. In other words, it might be that the changes from (2) to (3) are incompatible with the changes from (1) to (4). In that case, the maintainer will have to manually resolve the conflicts. Hopefully conflicts will not come up that often. Conflicts are less likely to occur when the private edits are kept to a minimum.

The cycle above can be repeated many times. The diagram shows a third SQLite release, 3.6.17 in circle (6). The private branch maintainer can do another merge in order to incorporate the changes moving from (4) to (6) into the private branch, resulting in version (7).

3.0 The Procedure

The remainder of this document will guide the reader through the steps needed to maintain a private branch. The general idea is the same as outlined above. This section merely provides more detail.

We emphasize again that these steps are not intended to be the only acceptable method for maintaining private branch. This approach is one of many. Use this document as a baseline for preparing project-specific procedures. Do not be afraid to experiment.

3.1 Obtain The Software

Fossil is a computer program that must be installed on your machine before you use it. Fortunately, installing fossil is very easy. Fossil is a single "*.exe" file that you simply download and run. To uninstall fossil, simply delete the exe file. Detailed instructions for installing and getting started with fossil are available on the fossil website.

3.2 Create A Project Repository

Create a fossil repository to host the private branch using the following command:

fossil new private-project.fossil

You can call your project anything you like. The ".fossil" suffix is optional. For this document, we will continue to call the project "private-project.fossil". Note that private-project.fossil is an ordinary disk file (actually an SQLite database) that will contain your complete project history. You can make a backup of the project simply by making a copy of that one file.

If you want to configure the new project, type:

fossil ui private-project.fossil

The "ui" command will cause fossil to run a miniature built-in webserver and to launch your web-browser pointing at that webserver. You can use your web-browser to configure your project in various ways. See the instructions on the fossil website for additional information.

Once the project repository is created, create an open checkout of the project by moving to the directory where you want to keep all of the project source code and typing:

fossil open private-project.fossil

You can have multiple checkouts of the same project if you want. And you can "clone" the repository to different machines so that multiple developers can use it. See the fossil website for further information.

3.3 Installing The SQLite Baseline In Fossil

The repository created in the previous step is initially empty. The next step is to load the baseline SQLite release - circle (1) in the diagram above.

Begin by obtaining a copy of SQLite in whatever form you use it. The public SQLite you obtain should be as close to your private edited copy as possible. If your project uses the SQLite amalgamation, then get a copy of the amalgamation. If you use the preprocessed separate source files, get those instead. Put all the source files in the checkout directory created in the previous step.

The source code in public SQLite releases uses unix line endings (ASCII code 10: "newline" only, NL) and spaces instead of tabs. If you will be changing the line ending to windows-style line endings (ASCII codes 13, 10: "carriage-return" and "newline"; CR-NL) or if you will be changing space indents into tab indents, make that change now before you check in the baseline. The merging process will only work well if the differences between the public and the private branches are minimal. If every single line of the source file is changed in the private branch because you changed from NL to CR-NL line endings, then the merge steps will not work correctly.

Let us assume that you are using the amalgamation source code. Add the baseline to your project as follows:

fossil add sqlite3.c sqlite3.h

If you are using separate source files, name all of the source files instead of just the two amalgamation source files. Once this is done, commit your changes as follows:

fossil commit

You will be prompted for a check-in comment. Say whatever you like. After the commit completes, your baseline will be part of the repository. The following command, if you like, to see this on the "timeline":

fossil ui

That last command is the same "ui" command that we ran before. It starts a mini-webserver running and points your web browser at it. But this time we didn't have to specify the repository file because we are located inside a checkout and so fossil can figure out the repository for itself. If you want to type in the repository filename as the second argument, you can. But it is optional.

If you do not want to use your web browser to view the new check-in, you can get some information from the command-line using commands like these:

fossil timeline
fossil info
fossil status

3.4 Creating The Private Branch

The previous step created circle (1) in the diagram above. This step will create circle (2). Run the following command:

fossil branch new private trunk -bgcolor "#add8e8"

This command will create a new branch named "private" (you can use a different name if you like) and assign it a background color of light blue ("#add8e8"). You can omit the background color if you want, though having a distinct background does make it easier to tell the branch from the "trunk" (the public branch) on timeline displays. You can change the background color of the private branch or of the public branch (the "trunk") using the web interface if you like.

The command above created the new branch. But your checkout is still on the trunk - a fact you can see by running the command:

fossil info

To change your check-out to the private branch, type:

fossil update private

You can run the "info" command again to verify that you are on the private branch. To go back to the public branch, type:

fossil update trunk

Normally, fossil will modify all the files in your checkout when switching between the private and the public branches. But at this point, the files are identical in both branches so not modifications need to be made.

3.5 Adding Customizations To The Code In The Private Branch

Now it is time to make the private, custom modifications to SQLite which are the whole point of this exercise. Switch to the private branch (if you are not already there) using the "fossil update private" command, then bring up the source files in your text editor and make whatever changes you want to make. Once you have finished making changes, commit those changes using this command:

fossil commit

You will be prompted once again to enter a commit describing your changes. Then the commit will occur. The commit creates a new checkin in the repository that corresponds to circle (3) in the diagram above.

Now that the public and private branches are different, you can run the "fossil update trunk" and "fossil update private" commands and see that fossil really does change the files in the checkout as you switch back and forth between branches.

Note that in the diagram above, we showed the private edits as a single commit. This was for clarity of presentation only. There is nothing to stop you from doing dozens or hundreds of separate tiny changes and committing each separately. In fact, making many small changes is the preferred way to work. The only reason for doing all the changes in a single commit is that it makes the diagram easier to draw.

3.6 Incorporating New Public SQLite Releases

Suppose that after a while (about a month, usually) a new version of SQLite is released: 3.6.16. You will want to incorporate this new public version of SQLite into your repository in the public branch (the trunk). To do this, first change your repository over to the trunk:

fossil update trunk

Then download the new version of the SQLite sources and overwrite the files that are in the checkout.

If you made NL to CR-NL line ending changes or space to tab indentation changes in the original baseline, make the same changes to the new source file.

Once everything is ready, run the "fossil commit" command to check in the changes. This creates circle (4) in the diagram above.

3.7 Merging Public SQLite Updates Into The Private Branch

The next step is to move the changes in the public branch over into the private branch. In other words, we want to create circle (5) in the diagram above. Begin by changing to the private branch using "fossil update private". Then type this command:

fossil merge trunk

The "merge" command attempts to apply all the changes between circles (1) and (4) to the files in the local checkout. Note that circle (5) has not been created yet. You will need to run the "commit" to create circle (5).

It might be that there are conflicts in the merge. Conflicts occur when the same line of code was changed in different ways between circles (1) and (4) versus circles (2) and (3). The merge command will announce any conflicts and will include both versions of the conflicting lines in the output. You will need to bring up the files that contain conflicts and manually resolve the conflicts.

After resolving conflicts, many users like to compile and test the new version before committing it to the repository. Or you can commit first and test later. Either way, run the "fossil commit" command to check-in the circle (5) version.

3.8 Further Updates

As new versions of SQLite are released, repeat steps 3.6 and 3.7 to add changes in the new release to the private branch. Additional private changes can be made on the private branch in between releases if desired.

4.0 Variations

Since this document was first written, the canonical SQLite source code has been moved from the venerable CVS system into a Fossil repository at http://www.sqlite.org/src. This means that if you are working with canonical SQLite source code (as opposed to the amalgamation source code files, sqlite3.c and sqlite3.h) then you can create a private repository simply by cloning the official repository:

fossil clone http://www.sqlite.org/src private-project.fossil

This command both creates the new repository and populates it with all the latest SQLite could. You can the create a private branch as described in section 3.4.

When the private repository is created by cloning, incorporating new public SQLite releases becomes much easier too. To pull in all of the latest changes from the public SQLite repository, simply move into the open check-out and do:

fossil update

Then continue to merge the changes in "trunk" with your "private" changes as described in section 3.7.


Query Planning

The best feature of SQL (in all its implementations, not just SQLite) is that it is a declarative language, not a procedural language. When programming in SQL you tell the system what you want to compute, not how to compute it. The task of figuring out the how is delegated to the query planner subsystem within the SQL database engine. Relieving the programmer from the chore of designing specific query algorithms reduces the workload on the programmer and reduces the number of opportunities for the programmer to make mistakes.

Most of the time, the query planner in SQLite does a good job on its own and without outside help. However, the query planner needs indices to work with and it usually falls to the programmer to add indices to the schema that are sufficient for the query planner to accomplish its task.

This document is intended to provide programmers who are new to SQL with background information to help them understand what is going on behind the scenes with SQLite, which in turn should make it easier for programmers to create the indices that will help the SQLite query planner to pick the best plans.

1.0 Searching

1.1 Tables Without Indices

Every table in SQLite consists of zero or more rows with a unique integer key (the rowid or INTEGER PRIMARY KEY) followed by content. The rows are logically stored in order of increasing rowid. As an example, this article uses a table named "FruitsForSale" which relates various fruits to the state where they are grown and their unit price at market. The schema is this:

CREATE TABLE FruitsForSale(
  Fruit TEXT,
  State TEXT,
  Price REAL
);

With some (arbitrary) data, such a table might be logically stored on disk as shown in figure 1:

figure 1
Figure 1: Logical Layout Of Table "FruitsForSale"

The key features to notice in this example is that the rowids are not consecutive but they are ordered. SQLite usually creates rowids beginning with one and increasing by one with each added row. But if rows are deleted, gaps can appear in the sequence. And the application can control the rowid assigned if desired, so that rows are not necessarily inserted at the bottom. But regardless of what happens, the rowids are always unique and in strictly ascending order.

Now suppose you want to look up the price of peaches. The query would be as follows:

SELECT price FROM fruitsforsale WHERE fruit='Peach';

In order to satisfy this query, SQLite has to read every row out of the table, check to see if the "fruit" column has the value of "Peach" and if so, output the "price" column from that row. The process is illustrated by figure 2 below. This is called a full table scan since the entire content of the table must be read and examined in order to find the one row of interest. With a table of only 7 rows, this is not a big deal, but if your table contained 7 million rows, a full table scan might read megabytes of content in order to find a single 8-byte number. For that reason, one normally tries to avoid full table scans.

figure 2
Figure 2: Full Table Scan

1.2 Lookup By Rowid

One technique for avoiding a full table scan is to do lookups by rowid (or by the equivalent INTEGER PRIMARY KEY). To lookup the price of peaches, one would query for the entry with a rowid of 4:

SELECT price FROM fruitsforsale WHERE rowid=4;

Since the information is stored in the table in rowid order, SQLite can find the correct row using doing a binary search on the rowid. If the table contains N element, the time required to look up the desired row is proportional to logN rather than being proportional to N as in a full table scan. If the table contains 10 million elements, that means the query will be on the order of N/logN or about 1 million times faster!

figure 3
Figure 3: Lookup By Rowid

1.3 Lookup By Index

The problem with looking up information by rowid is that you probably do not care what the price of "item 4" is - you want to know the price of peaches. And so a rowid lookup is not helpful.

To make the original query more efficient, we can add an index on the "fruit" column of the "fruitsforsale" table like this:

CREATE INDEX idx1 ON fruitsforsale(fruit);

An index is another table similar to the original "fruitsforsale" table but with the content (the fruit column in this case) stored in front of the rowid and with all rows in content order. Figure 4 gives a logical view of the Idx1 index. The "fruit" column is the primary key used to order the elements of the table and the "rowid" is the secondary key used to break the tie when two or more rows have the same "fruit". In the example, the rowid has to be used as a tie-breaker for the "Orange" rows. Notice that since the rowid is always unique over all elements of the original table, the composite key of "fruit" followed by "rowid" will be unique over all elements of the index.

figure 4
Figure 4: An Index On The Fruit Column

With the new index in place, we can devise an alternative plan for the original "Price of Peaches" query.

SELECT price FROM fruitsforsale WHERE fruit='Peach';

The query starts by doing a binary search on the Idx1 index for entries that have fruit='Peach'. SQLite can do this binary search on the Idx1 index but not on the original FruitsForSale table because the rows in Idx1 are sorted by the "fruit" column. Having found a row in the Idx1 index that has fruit='Peach', the database engine can extract the rowid for that row, then do a separate binary search on the original FruitsForSale table to find the original row that contains fruit='Peach'. From the row in the FruitsForSale table, SQLite can extract the value of the price column. This procedure is illustrated by figure 5.

figure 5
Figure 5: Indexed Lookup For The Price Of Peaches

SQLite has to do two binary searches to find the price of peaches using the method show above. But for a table with a large number of rows, this is still much faster than doing a full table scan.

1.4 Multiple Result Rows

In the previous query the fruit='Peach' constraint narrowed the result down to a single row. But the same technique works even if multiple rows are obtained. Suppose we looked up the price of Oranges instead Peaches:

SELECT price FROM fruitsforsale WHERE fruit='Orange'

figure 6
Figure 6: Indexed Lookup For The Price Of Oranges

In this case, SQLite still does a single binary search to find the first entry of the index where fruit='Orange'. Then it extracts the rowid from the index and uses that rowid to lookup the original table entry via binary search and output the price from the original table. But instead of quitting, the database engine then advances to the next row of index to repeat the process for next fruit='Orange' entry. Advancing to the next row of an index (or table) is much less costly than doing a binary search since the next row is often located on the same database page as the current row. In fact, the cost of advancing to the next row is so cheap in comparison to a binary search that we usually ignore it. So our estimate for the total cost of this query is 3 binary searches. If the number of rows of output is K and the number of rows in the table is N, then in general the cost of doing the query proportional to (K+1)*logN.

1.5 Multiple AND-Connected WHERE-Clause Terms

Next, suppose that you want to look up the price of not just any orange, but specifically California-grown oranges. The appropriate query would be as follows:

SELECT price FROM fruitsforsale WHERE fruit='Orange' AND state='CA'

figure 7
Figure 7: Indexed Lookup Of California Oranges

One approach to this query is to use the fruit='Orange' term of the WHERE clause to find all rows dealing with oranges, then filter those rows by rejecting any that are from states other than California. This process is shown by figure 7 above. This is a perfectly reasonable approach in most cases. Yes, the database engine did have to do an extra binary search for the Florida orange row that was later rejected, so it was not as efficient as we might hope, though for many applications it is efficient enough.

Suppose that in addition to the index on "fruit" there was also an index on "state".

CREATE INDEX Idx2 ON fruitsforsale(state);

figure 8
Figure 8: Index On The State Column

The "state" index works just like the "fruit" index in that it is a new table with an extra column in front of the rowid and sorted by that extra column as the primary key. The only difference is that in Idx2, the first column is "state" instead of "fruit" as it is with Idx1. In our example data set, the is more redundancy in the "state" column and so they are more duplicate entries. The ties are still resolved using the rowid.

Using the new Idx2 index on "state", SQLite has another option for lookup up the price of California oranges: it can look up every row that contains fruit from California and filter out those rows that are not oranges.

figure 9
Figure 9: Indexed Lookup Of California Oranges

Using Idx2 instead of Idx1 causes SQLite to examine a different set of rows, but it gets the same answer in the end (which is very important - remember that indices should never change the answer, only help SQLite to get to the answer more quickly) and it does the same amount of work. So the Idx2 index did not help performance in this case.

The last two queries take the same amount of time, in our example. So which index, Idx1 or Idx2, will SQLite choose? If the ANALYZE command has been run on the database, so that SQLite has had an opportunity to gather statistics about the available indices, then SQLite will know that the Idx1 table usually narrows the search down to a single item (our example of fruit='Orange' is the exception to this rule) where as the Idx table will normally only narrow the search down to two rows. So, if all else is equal, SQLite will choose Idx1 with the hope of narrowing the search to as small a number of rows as possible. This choice is only possible because of the statistics provided by ANALYZE. If ANALYZE has not been run then the choice of which index to use is arbitrary.

1.6 Multi-Column Indices

To get the maximum performance out of a query with multiple AND-connected terms in the WHERE clause, you really want a multi-column index with columns for each of the AND terms. In this case we create a new index on the "fruit" and "state" columns of FruitsForSale:

CREATE INDEX Idx3 ON FruitsForSale(fruit, state);

figure 1
Figure 1: A Two-Column Index

A multi-column index follows the same pattern as a single-column index; the indexed columns are added in front of the rowid. The only difference is that now multiple columns are added. The left-most column is the primary key used for ordering the rows in the index. The second column is used to break ties in the left-most column. If there were a third column, it would be used to break ties for the first to columns. And so forth for as many columns as their are in the index. Because rowid is guaranteed to be unique, every row of the index will be unique even if all of the content columns for two rows are the same. That case does not happen in our sample data, but there is one case (fruit='Orange') where there is a tie on the first column which must be broken by the second column.

Given the new multi-column Idx3 index, it is now possible for SQLite to find the price of California oranges using only 2 binary searches:

SELECT price FROM fruitsforsale WHERE fruit='Orange' AND state='CA'

figure 11
Figure 11: Lookup Using A Two-Column Index

With the Idx3 index on both columns that are constrained by the WHERE clause, SQLite can do a single binary search against Idx3 to find the one rowid for California oranges, then do a single binary search to find the price for that item in the original table. There are no dead-ends and no wasted binary searches. This is a more efficient query.

Note that Idx3 contains all the same information as the original Idx1. And so if we have Idx3, we do not really need Idx1 any more. The "price of peaches" query can be satisfied using Idx3 by simply ignoring the "state" column of Idx3:

SELECT price FROM fruitsforsale WHERE fruit='Peach'

figure 12
Figure 12: Single-Column Lookup On A Multi-Column Index

Hence, a good rule of thumb is that your database schema should never contain two indices where one index is a prefix of the other. Drop the index with fewer columns. SQLite will still be able to do efficient lookups with the longer index.

1.7 Covering Indices

The "price of California oranges" query was made more efficient through the use of a two-column index. But SQLite can do even better with a three-column index that also includes the "price" column:

CREATE INDEX Idx4 ON FruitsForSale(fruit, state, price);

figure 13
Figure 13: A Covering Index

This new index contains all the columns of the original FruitsForSale table that are used by the query - both the search terms and the output. We call this a "covering index". Because all of the information needed is in the covering index, SQLite never needs to consult the original table in order to find the price.

SELECT price FROM fruitsforsale WHERE fruit='Orange' AND state='CA';

figure 14
Figure 14: Query Using A Covering Index

Hence, by adding extra "output" columns onto the end of an index, one can avoid having to reference the original table and thereby cut the number of binary searches for a query in half. This is a constant-factor improvement in performance (roughly a doubling of the speed). But on the other hand, it is also just a refinement; A two-fold performance increase is not nearly as dramatic as the one-million-fold increase seen when the table was first indexed. And for most queries, the difference between 1 microsecond and 2 microseconds is unlikely to be noticed.

1.8 OR-Connected Terms In The WHERE Clause

Multi-column indices only work if the constraint terms in the WHERE clause of the query are connected by AND. So Idx3 and Idx4 are helpful when the search is for items that are both Oranges and grown in California, but neither index would be that useful if we wanted all items that were either oranges or are grown in California.

SELECT price FROM FruitsForSale WHERE fruit='Orange' OR state='CA';

When confronted with OR-connected terms in a WHERE clause, SQLite examines each OR term separately and tries to use an index to find the rowids associated with each term. It then takes the union of the resulting rowid sets to find the end result. The following figure illustrates this process:

figure 15
Figure 15: Query With OR Constraints

The diagram above implies that SQLite computes all of the rowids first and then combines them with a union operation before starting to do rowid lookups on the original table. In reality, the rowid lookups are interspersed with rowid computations. SQLite uses one index at a time to find rowids while remembering which rowids it has seen before so as to avoid duplicates. That is just an implementation detail, though. The diagram, while not 100% accurate, provides a good overview of what is happening.

In order for the OR-by-UNION technique shown above to be useful, there must be an index available that helps resolve every OR-connected term in the WHERE clause. If even a single OR-connected term is not indexed, then a full table scan would have to be done in order to find the rowids generated by the one term, and if SQLite has to do a full table scan, it might as well do it on the original table and get all of the results in a single pass without having to mess with union operations and follow-on binary searches.

One can see how the OR-by-UNION technique could also be leveraged to use multiple indices on queries where the WHERE clause has terms connected by AND, by using an intersect operator in place of union. Many SQL database engines will do just that. But the performance gain over using just a single index is slight and so SQLite does not implement that technique at this time. However, a future version SQLite might be enhanced to support AND-by-INTERSECT.

2.0 Sorting

SQLite (like all other SQL database engines) can also use indices to satisfy the ORDER BY clauses in a query, in addition to expediting lookup. In other words, indices can be used to speed up sorting as well as searching.

When no appropriate indices are available, a query with an ORDER BY clause must be sorted as a separate step. Consider this query:

SELECT * FROM fruitsforsale ORDER BY fruit;

SQLite processes this by gather all the output of query and then running that output through a sorter.

figure 16
Figure 16: Sorting Without An Index

If the number of output rows is K, then the time needed to sort is proportional to KlogK. If K is small, the sorting time is usually not a factor, but in a query such as the above where K==N, the time needed to sort can be much greater than the time needed to do a full table scan. Furthermore, the entire output is accumulated in temporary storage (which might be either in main memory or on disk, depending on various compile-time and run-time settings) which can mean that a lot of temporary storage is required to complete the query.

2.1 Sorting By Rowid

Because sorting can be expensive, SQLite works hard to convert ORDER BY clauses into no-ops. If SQLite determines that output will naturally appear in the order specified, then no sorting is done. So, for example, if you request the output in rowid order, no sorting will be done:

SELECT * FROM fruitsforsale ORDER BY rowid;

figure 17
Figure 17: Sorting By Rowid

You can also request a reverse-order sort like this:

SELECT * FROM fruitsforsale ORDER BY rowid DESC;

SQLite will still omit the sorting step. But in order for output to appear in the correct order, SQLite will do the table scan starting at the end and working toward the beginning, rather than starting at the beginning and working toward the end as shown in figure 17.

2.2 Sorting By Index

Of course, ordering the output of a query by rowid is seldom useful. Usually one wants to order the output by some other column.

If an index is available on the ORDER BY column, that index can be used for sorting. Consider the request for all items sorted by "fruit":

SELECT * FROM fruitsforsale ORDER BY fruit;

figure 18
Figure 18: Sorting With An Index

The Idx1 index is scanned from top to bottom (or from bottom to top if "ORDER BY fruit DESC" is used) in order to find the rowids for each item in order by fruit. Then for each rowid, a binary search is done to lookup and output that row. In this way, the output appears in the requested order with the need to gather then entire output and sort it using a separate step.

But does this really save time? The number of steps in the original indexless sort is proportional to NlogN since that is how much time it takes to sort N rows. But when we use Idx1 as shown here, we have to do N rowid lookups which take logN time each, so the total time of NlogN is the same!

SQLite uses a cost-based query planner. When there are two or more ways of solving the same query, SQLite tries to estimate the total amount of time needed to run the query using each plan, and then uses the plan with the lowest estimated cost. A cost is computed mostly from the estimated time, and so this case could go either way depending on the table size and what WHERE clause constraints were available, and so forth. But generally speaking, the indexed sort would probably be chosen, if for no other reason, because it does not need to accumulate the entire result set in temporary storage before sorting and thus uses much less temporary storage.

2.3 Sorting By Covering Index

If a covering index can be used for a query, then the multiple rowid lookups can be avoided and the cost of the query drops dramatically.

figure 19
Figure 19: Sorting With A Covering Index

With a covering index, SQLite can simply walk the index from one end to the other and deliver the output in time proportional to N and without having allocate a large buffer to hold the result set.

3.0 Searching And Sorting At The Same Time

The previous discussion has treated searching and sorting as separate topics. But in practice, it is often the case that one wants to search and sort at the same time. Fortunately, it is possible to do this using a single index.

3.1 Searching And Sorting With A Multi-Column Index

Suppose we want to find the prices of all kinds of oranges sorted in order of the state where they are grown. The query is this:

SELECT price FROM fruitforsale WHERE fruit='Orange' ORDER BY state

The query contains both a search restriction in the WHERE clause and a sort order in the ORDER BY clause. Both the search and the sort can be accomplished at the same time using the two-column index Idx3.

figure 20
Figure 20: Search And Sort By Multi-Column Index

The query does a binary search on the index to find the subset of rows that have fruit='Orange'. (Because the fruit column is the left-most column of the index and the rows of the index are in sorted order, all such rows will be adjacent.) Then it scans the matching index rows from top to bottom to get the rowids for the original table, and for each rowid does a binary search on the original table to find the price.

You will notice that there is no "sort" box anywhere in the above diagram. The ORDER BY clause of the query has become a no-op. No sorting has to be done here because the output order is by the state column and the state column also happens to be the first column after the fruit column in the index. So, if we scan entries of the index that have the same value for the fruit column from top to bottom, those index entries are guaranteed to be ordered by the state column.

3.2 Searching And Sorting With A Covering Index

A covering index can also be used to search and sort at the same time. Consider the following:

SELECT * FROM fruitforsale WHERE fruit='Orange' ORDER BY state

figure 21
Figure 21: Search And Sort By Covering Index

As before, SQLite does single binary search for the range of rows in the covering index that satisfy the WHERE clause, the scans that range from top to bottom to get the desired results. The rows that satisfy the WHERE clause are guaranteed to be adjacent since the WHERE clause is an equality constraint on the left-most column of the index. And by scanning the matching index rows from top to bottom, the output is guaranteed to be ordered by state since the state column is the very next column to the right of the fruit column. And so the resulting query is very efficient.

SQLite can pull a similar trick for a descending ORDER BY:

SELECT * FROM fruitforsale WHERE fruit='Orange' ORDER BY state DESC

The same basic algorithm is followed, except this time the matching rows of the index are scanned from bottom to top instead of from top to bottom, so that the states will appear in descending order.

To Be Continued...

Further topics:

  • How to construct a good index
  • Joins and join-order
  • Automatic transient indices
  • How to determine what query plan SQLite is using
  • Automatic detection of inefficient query plans
  • Techniques for influencing what query plan SQLite chooses


SQLite In 5 Minutes Or Less

Choose any three.
About Sitemap Documentation Download License News Support

Here is what you do to start experimenting with SQLite without having to do a lot of tedious reading and configuration:

Download The Code

  • Get a copy of the prebuilt binaries for your machine, or get a copy of the sources and compile them yourself. Visit the download page for more information.

Create A New Database

  • At a shell or DOS prompt, enter: "sqlite3 test.db". This will create a new database named "test.db". (You can use a different name if you like.)

  • Enter SQL commands at the prompt to create and populate the new database.

  • Additional documentation is available here

Write Programs That Use SQLite

  • Below is a simple TCL program that demonstrates how to use the TCL interface to SQLite. The program executes the SQL statements given as the second argument on the database defined by the first argument. The commands to watch for are the sqlite3 command on line 7 which opens an SQLite database and creates a new TCL command named "db" to access that database, the invocation of the db command on line 8 to execute SQL commands against the database, and the closing of the database connection on the last line of the script.

    01  #!/usr/bin/tclsh
02  if {$argc!=2} {
03    puts stderr "Usage: %s DATABASE SQL-STATEMENT"
04    exit 1
05  }
06  load /usr/lib/tclsqlite3.so Sqlite3
07  sqlite3 db [lindex $argv 0]
08  db eval [lindex $argv 1] x {
09    foreach v $x(*) {
10      puts "$v = $x($v)"
11    }
12    puts ""
13  }
14  db close

  • Below is a simple C program that demonstrates how to use the C/C++ interface to SQLite. The name of a database is given by the first argument and the second argument is one or more SQL statements to execute against the database. The function calls to pay attention to here are the call to sqlite3_open() on line 22 which opens the database, sqlite3_exec() on line 28 that executes SQL commands against the database, and sqlite3_close() on line 33 that closes the database connection.

    See also the Introduction To The SQLite C/C++ Interface for an introductory overview and roadmap to the dozens of SQLite interface functions.

    01  #include <stdio.h>
02  #include <sqlite3.h>
03
04  static int callback(void *NotUsed, int argc, char **argv, char **azColName){
05    int i;
06    for(i=0; i<argc; i++){
07      printf("%s = %s\n", azColName[i], argv[i] ? argv[i] : "NULL");
08    }
09    printf("\n");
10    return 0;
11  }
12
13  int main(int argc, char **argv){
14    sqlite3 *db;
15    char *zErrMsg = 0;
16    int rc;
17
18    if( argc!=3 ){
19      fprintf(stderr, "Usage: %s DATABASE SQL-STATEMENT\n", argv[0]);
20      return(1);
21    }
22    rc = sqlite3_open(argv[1], &db);
23    if( rc ){
24      fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db));
25      sqlite3_close(db);
26      return(1);
27    }
28    rc = sqlite3_exec(db, argv[2], callback, 0, &zErrMsg);
29    if( rc!=SQLITE_OK ){
30      fprintf(stderr, "SQL error: %s\n", zErrMsg);
31      sqlite3_free(zErrMsg);
32    }
33    sqlite3_close(db);
34    return 0;
35  }


No Title

Choose any three.
About Sitemap Documentation Download License News Support

SQLite Requirements

1.0 Introduction

These requirements strive to describe the interfaces and operation of SQLite in sufficient detail that a compatible implementation of SQLite can be written solely from these requirements and without reference to the canonical SQLite source code.

Software development processes typically recognize a hierarchy of requirements:

  • System requirements
  • High-level requirements
  • Derived high-level requirements
  • Low-level requirements
  • Derived low-level requirements

The usual distinction between high-level and low-level requirements is that high-level requirements describe "what" the system does and the low-level requirements describe "how" the system does it. Since the requirements denoted here describe the behavior of SQLite and not its implementation, they are best thought of as high-level requirements. Consistent with that view, most of the requirements numbers begin with the letter "H" (for "high-level"). A few of the requirements presented here specify broad objectives that SQLite strives to achieve. These broad requirements can be thought of as system requirements and are number with an initial letter "S".

These requirements are hierarchical in the sense that the more specific requirements are derived from broader and more general requirements. When requirement B is derived from requirement A, we say that A is the parent of B and that B is a child of A. The parent/child relationships of all requirements are tracked. All requirements presented here ultimately derive from a single very broad, very high-level, and very general system requirement called "S10000".

Some behaviors of SQLite are undefined. For example, the order in which result rows are returned from a SELECT statement is undefined if there is no ORDER BY clause. As another example, many of the C interfaces require a pointer to an open database connection as their first argument and the behavior of those interfaces is undefined (and probably undesirable) if a pointer to some other object is supplied instead. Some, but not all undefined behaviors are explicitly stated and number in this document with numbers beginning with the "U" for "Undefined". Applications that use SQLite should never depend on undefined behavior. If a behavior is not explicitly defined by a requirement, then the behavior is undefined, and so explicitly stating undefined behaviors in this document is technically redundant. Nevertheless, we find that explicitly stating some undefined behaviors helps application developers to better understand the boundaries of operation of SQLite and to generate safer and more accurate programs that use SQLite.

2.0 System Requirements

3.0 Application C-Language Interfaces

4.0 C-Language Interfaces For Extending SQLite

5.0 Database File Format

6.0 SQL Language Specification


User-agent: *
Disallow: /cvstrac/attach_add
Disallow: /cvstrac/attach_get
Disallow: /cvstrac/chngedit
Disallow: /cvstrac/chngview
Disallow: /cvstrac/dir
Disallow: /cvstrac/filediff
Disallow: /cvstrac/getfile
Disallow: /cvstrac/msedit
Disallow: /cvstrac/msnew
Disallow: /cvstrac/rlog
Disallow: /cvstrac/rptedit
Disallow: /cvstrac/rptnew
Disallow: /cvstrac/rptsql
Disallow: /cvstrac/timeline
Disallow: /cvstrac/tktedit
Disallow: /cvstrac/tktview
Disallow: /cvstrac/wikiedit
Disallow: /cvstrac/honeypot
Disallow: /cvstrac/wiki/attach_get
Disallow: /contrib/download


The SQLite R*Tree Module

Choose any three.
About Sitemap Documentation Download License News Support

1.0 Overview

An R-Tree is a special index that is designed for doing range queries. R-Trees are most commonly used in geospatial systems where each entry is a rectangle with minimum and maximum X and Y coordinates. Given a query rectangle, an R-Tree is able to quickly find all entries that are contained within the query rectangle or which overlap the query rectangle. This idea is easily extended to three dimensions for use in CAD systems. R-Trees also find use in time-domain range look-ups. For example, suppose a database records the starting and ending times for a large number of events. A R-Tree is able to quickly find all events, for example, that were active at any time during a given time interval, or all events that started during a particular time interval, or all events that both started and ended within a given time interval. And so forth.

The R-Tree concept originated with Toni Guttman: R-Trees: A Dynamic Index Structure for Spatial Searching, Proc. 1984 ACM SIGMOD International Conference on Management of Data, pp. 47-57. The implementation found in SQLite is a refinement of Guttman's original idea, commonly called "R*Trees", that was described by Norbert Beckmann, Hans-Peter Kriegel, Ralf Schneider, Bernhard Seeger: The R*-Tree: An Efficient and Robust Access Method for Points and Rectangles. SIGMOD Conference 1990: 322-331.

2.0 Compiling The R*Tree Module

The source code to the SQLite R*Tree module is included as part of the amalgamation but is disabled by default. To enable the R*Tree module, simply compile with the SQLITE_ENABLE_RTREE C-preprocessor macro defined. With many compilers, this is accomplished by adding the option "-DSQLITE_ENABLE_RTREE=1" to the compiler command-line.

3.0 Using the R*Tree Module

The SQLite R*Tree module is implemented as a virtual table. Each R*Tree index is a virtual table with an odd number of columns between 3 and 11. The first column is always a 64-bit signed integer primary key. The other columns are minimum- and maximum-value pairs (stored as 32-bit floating point numbers) for each dimension. A 1-dimensional R*Tree thus has 3 columns. A 2-dimensional R*Tree (the most common case) has 5 columns. A 5-dimensional R*Tree has 11 columns. The SQLite R*Tree implementation does not support R*Trees wider than 5 dimensions.

The first column of an SQLite R*Tree must always be an integer primary key. The min/max-value pair columns are always stored as 32-bit floating point values. Unlike regular SQLite tables which can store data in a variety of datatypes and formats, the R*Tree indices rigidly enforce these two storage types. Attempts to insert something other than an integer into the first column, or something other than a floating point value into the other columns, will result in an error.

3.1 Creating An R*Tree Index

A new R*Tree index is created as follows:

CREATE VIRTUAL TABLE <name> USING rtree(<column-names>);

The <name> is the name your application chooses for the R*Tree index and <column-names> is a comma separated list of between 3 and 11 columns. The virtual <name> table creates three "shadow" tables to actually store its content. The names of these shadow tables are:

<name>_node
<name>_rowid
<name>_parent

The shadow tables are ordinary SQLite data tables. You can query them directly if you like, though this unlikely to reveal anything particularly useful. And you can UPDATE, DELETE, INSERT or even DROP the shadow tables, though doing so will corrupt your R*Tree index. So it is best to simply ignore the shadow tables. Recognize that they are there to hold your R*Tree index information and let it go as that.

As an example, consider creating a two-dimensional R*Tree index for use in spatial queries:

CREATE VIRTUAL TABLE demo_index USING rtree(
   id,              -- Integer primary key
   minX, maxX,      -- Minimum and maximum X coordinate
   minY, maxY       -- Minimum and maximum Y coordinate
);

3.2 Populating An R*Tree Index

The usual INSERT, UPDATE, and DELETE commands work on an R*Tree index just like on regular tables. So to insert some data into our sample R*Tree index, we can do something like this:

INSERT INTO demo_index VALUES(
    1,                   -- Primary key
    -80.7749, -80.7747,  -- Longitude range
    30.3776, 30.3778     -- Latitude range
);
INSERT INTO demo_index VALUES(
    2,
    -81.0, -79.6,
    35.0, 36.2
);

The entries above might represent (for example) a bounding box around the offices for SQLite.org and bounding box around the 12th Congressional District of North Carolina in which SQLite.org is located.

3.3 Querying An R*Tree Index

Any valid query will work against an R*Tree index. But the R*Tree implementation is designed to make two kinds of queries especially efficient. First, queries against the primary key are efficient:

SELECT * FROM demo_index WHERE id=1;

Of course, an ordinary SQLite table will do a query against its integer primary key efficiently, so the previous is no big deal. The real reason for using an R*Tree in the first place is so that you can efficiently do inequality queries against the coordinate ranges. To find all elements of the index that are contained within the vicinity of Charlotte, North Carolina, one might do:

SELECT id FROM demo_index
 WHERE minX>=-81.08 AND maxX<=-80.58
   AND minY>=35.00  AND maxY<=35.44;

The query above would very quickly locate the id of 1 even if the R*Tree contained millions of entries. The previous is an example of a "contained-within" query. The R*Tree also supports "overlapping" queries. For example, to find all bounding boxes that overlap the Charlotte area:

SELECT id FROM demo_index
 WHERE maxX>=-81.08 AND minX<=-80.58
   AND maxY>=35.00  AND minY<=35.44;

This second query would find both entry 1 (the SQLite.org office) which is entirely contained within the query box and also the 12th Congressional District which extends well outside the query box but still overlaps the query box.

Note that is not necessary for all coordinates in an R*Tree index to be constrained in order for the index search to be efficient. One might, for example, want to query all objects that overlap with the 35th parallel:

SELECT id FROM demo_index
 WHERE maxY>=35.0  AND minY<=35.0;

But, generally speaking, the more constraints that the R*Tree module has to work with, and the smaller the bounding box, the faster the results will come back.

4.0 Using R*Trees Effectively

The only information that an R*Tree index stores about an object is its integer ID and its bounding box. Additional information needs to be stored in separate tables and related to the R*Tree index using the primary key. For the example above, one might create an auxiliary table as follows:

CREATE TABLE demo_data(
  id INTEGER PRIMARY KEY,  -- primary key
  objname TEXT,            -- name of the object
  objtype TEXT,            -- object type
  boundary BLOB            -- detailed boundary of object
);

In this example, the demo_data.boundary field is intended to hold some kind of binary representation of the precise boundaries of the object. The R*Tree index only holds an axis-aligned rectangular boundary for the object. The R*Tree boundary is just an approximation of the true object boundary. So what typically happens is that the R*Tree index is used to narrow a search down to a list of candidate objects and then more detailed and expensive computations are done on each candidate to find if the candidate truly meets the search criteria.

Key Point: An R*Tree index does not normally provide the exact answer but merely reduces the set of potential answers from millions to dozens.

Suppose the demo_data.boundary field holds some proprietary data description of a complex two-dimensional boundary for an object and suppose that the application has used the sqlite3_create_function() interface to created application-defined functions "contained_in" and "overlaps" accepting two demo_data.boundary objects and return true or false. One may assume that "contained_in" and "overlaps" are relatively slow functions that we do not want to invoke too frequently. Then an efficient way to find the name of all objects located within the North Carolina 12th District, one may be to run a query like this:

SELECT objname FROM demo_data, demo_index
 WHERE demo_data.id=demo_index.id
   AND contained_in(demo_data.boundary, :boundary)
   AND minX>=-81.0 AND maxX<=-79.6
   AND minY>=35.0 AND maxY<=36.2;

In the query above, one would presumably bind the binary BLOB description of the precise boundary of the 12th district to the ":boundary" parameter.

Notice how the query above works: The R*Tree index runs in the outer loop to find entries that are contained within the bounding box of longitude -81..-79.6 and latitude 35.0..36.2. For each object identifier found, SQLite looks up the corresponding entry in the demo_data table. It then uses the boundary field from the demo_data table as a parameter to the contained_in() function and if that function returns true, the objname field from the demo_data table is returned as the next row of query result.

One would get the same answer without the use of the R*Tree index using the following simpler query:

SELECT objname FROM demo_data
 WHERE contained_in(demo_data.boundary, :boundary);

The problem with this latter query is that it must apply the contained_in() function to millions of entries in the demo_data table. The use of the R*Tree in the penultimate query reduces the number of calls to contained_in() function to a small subset of the entire table. The R*Tree index did not find the exact answer itself, it merely limited the search space.

5.0 Custom R-Tree Queries

By using standard SQL expressions in the WHERE clause of a SELECT query, a user may query for all r-tree entries that intersect a specified bounding-box, or for all entries that are completely encapsulated by a specified bounding-box. Custom r-tree queries, which use the special MATCH operator in the WHERE clause of a SELECT, allow the user to query for the set of r-tree entries that intersect any arbitrarily defined region.

Regions for custom r-tree queries are defined by r-tree geometry callbacks implemented by the application and registered with SQLite via a call to the following API:

int sqlite3_rtree_geometry_callback(
  sqlite3 *db,
  const char *zGeom,
  int (*xGeom)(sqlite3_rtree_geometry *, int nCoord, double *aCoord, int *pRes),
  void *pContext
);

A call to the above API registers an r-tree geometry callback named zGeom. If an r-tree geometry callback or ordinary SQL user function named zGeom already exists when sqlite3_rtree_geometry_callback() is called, it is replaced by the new r-tree geometry callback. If the xGeom parameter is passed a NULL value, then any existing r-tree geometry callback or SQL user function is removed from the system, but no new r-tree geometry callback is registered.

When the r-tree geometry callback is used in a custom r-tree query, the registered callback is invoked one or more times by SQLite to test whether or not the user-defined region intersects with specific bounding boxes. The bounding box being tested is defined by the contents of the aCoord[] array (size nCoord) passed to the callback. The aCoord[] array always contains the same number of entries as there are coordinate columns in the r-tree table (one less than the total number of columns, since the object id column does not contain a coordinate). They define a bounding-box in the same way as each row of the r-tree table itself does - the first scalar coordinate contains the minimum value for the first dimension, followed by the maximum value for the first dimension, followed by the minimum value for the second dimension, and so on. If the specified bounding box intersects with the custom query region, then the implementation of the callback must set the output parameter *pRes to non-zero and return SQLITE_OK. If the specified bounding box does not intersect the queried region, *pRes should be set to zero before returning SQLITE_OK. If an error occurs, the callback may return an SQLite error code other than SQLITE_OK, in which case the value of *pRes is ignored by SQLite and the query abandoned.

A registered r-tree geometry callback is used in an r-tree query by adding a MATCH condition to the WHERE clause of a SELECT statement. For example, assuming a custom geometry callback named "circle" has been registered, it may be used in a query on the two-dimensional r-tree table "demo_index" defined in earlier examples as follows:

SELECT * FROM demo_index WHERE id MATCH circle(45.3, 22.9, 5.0)

The left-hand side of the MATCH operator may be any column from the r-tree table, including the object id column. It makes no difference which column is used. The right-hand side of the MATCH operator is passed the results of an SQL function with the same name as the r-tree geometry callback. Zero or more function parameters may be specified by the user. Parameters are always interpreted as 64-bit real values. If a text, integer or blob value is passed as a parameter to an r-tree geometry callback function, it is converted to a real value as if by a CAST expression. If an SQL NULL value is passed to an r-tree geometry callback function, it is converted to the value 0.0.

Parameters passed to r-tree geometry callback functions may be used by the implementation of the r-tree geometry callback to define the specified region in any way. For example, the three parameters passed to the "circle" geometry callback above could identify the center point and radius of the circular region of interest.

The first argument to each invocation of an r-tree geometry callback is a pointer to a structure of the following type. The contents of the structure are not modified between multiple calls to the r-tree geometry callback associated with a single query (unless the pUser or xDelUser member variables are modified by the callback implementation - see below).

typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
struct sqlite3_rtree_geometry {
  void *pContext;                 /* Copy of pContext passed to s_r_g_c() */
  int nParam;                     /* Size of array aParam */
  double *aParam;                 /* Parameters passed to SQL geom function */
  void *pUser;                    /* Callback implementation user data */
  void (*xDelUser)(void *);       /* Called by SQLite to clean up pUser */
};

The pContext member of the structure is always set to a copy of the pContext argument passed to sqlite3_rtree_geometry_callback() when the r-tree geometry callback is registered. The aParam[] array (size nParam) contains the parameter values passed to the r-tree geometry callback as part of the SQL query. In the example "circle" query above, nParam would be set to 3 and the aParam[] array would contain the three values 45.3, 22.9 and 5.0.

The pUser and xDelUser members of the sqlite3_rtree_geometry structure are initially set to NULL. The pUser variable may be set by the callback implementation to any arbitrary value that may be useful to subsequent invocations of the callback within the same custom r-tree query (for example, a pointer to a complicated data structure used to test for region intersection). If the xDelUser variable is set to a non-NULL value, then after the custom r-tree query has finished running SQLite automatically invokes it with the value of the pUser variable as the only argument. In other words, xDelUser may be set to a destructor function for the pUser value.

Example code implementing the "circle" r-tree geometry callback may be found in the file test_rtree.c.


SQLite Is Self-Contained

SQLite is largely self-contained. It requires very minimal support from external libraries or from the operating system. This makes it well suited for use in embedded devices that lack the support infrastructure of a desktop computer. This also makes SQLite appropriate for use within applications that need to run without modification on a wide variety of computers of varying configurations.

SQLite is written in ANSI-C and should be easily compiled by any standard C compiler. It makes minimal use of the standard C library. The only required C library functions called are:

  • memset()
  • memcpy()
  • memcmp()
  • strcmp()
  • malloc(), free(), and realloc()

SQLite can be configured at start-time to use a static buffer in place of calling malloc() for the memory it needs. The date and time SQL functions provided by SQLite require some additional C library support, but those functions can be also be omitted from the build using compile-time options.

Communications between SQLite and the operating system and disk are mediated through an interchangeable VFS layer. VFS modules for Unix (Linux and Mac OS X), OS/2, and Windows (Win32 and WinCE) are provided in the source tree. It is a simple matter to devise an alternative VFS for embedded devices.

For safe operation in multi-threaded environments, SQLite requires the use of mutexes. Appropriate mutex libraries are linked automatically for Win32 and POSIX platforms. For other systems, mutex primitives can be added at start-time using the sqlite3_config(SQLITE_CONFIG_MUTEX,...) interface. Mutexes are only required if SQLite is used by more than one thread at a time.

The SQLite source code is available as an "amalgamation" - a single large C source code file. Projects that want to include SQLite can do so simply by dropping this one source file (named "sqlite3.c") and its corresponding header ("sqlite3.h") into their source tree and compiling it together with the rest of the code. SQLite does not link against any external libraries (other than the C library, as described above) and does not require any special build support.


SQLite Is Serverless

Most SQL database engines are implemented as a separate server process. Programs that want to access the database communicate with the server using some kind of interprocess communication (typically TCP/IP) to send requests to the server and to receive back results. SQLite does not work this way. With SQLite, the process that wants to access the database reads and writes directly from the database files on disk. There is no intermediary server process.

There are advantages and disadvantages to being serverless. The main advantage is that there is no separate server process to install, setup, configure, initialize, manage, and troubleshoot. This is one reason why SQLite is a "zero-configuration" database engine. Programs that use SQLite require no administrative support for setting up the database engine before they are run. Any program that is able to access the disk is able to use an SQLite database.

On the other hand, a database engine that uses a server can provide better protection from bugs in the client application - stray pointers in a client cannot corrupt memory on the server. And because a server is a single persistent process, it is able to control database access with more precision, allowing for finer grain locking and better concurrency.

Most SQL database engines are client/server based. Of those that are serverless, SQLite is the only one known to this author that allows multiple applications to access the same database at the same time.


SQLite Session Module C/C++ Interface

This page defines the C-language interface to the SQLite session module. This is not a tutorial. These pages are designed to be precise, not easy to read. Unfortunately, there is currently no tutorial introduction to the session module.

This page contains all C-language interface information in a single HTML file. The same information is also available broken out into lots of small pages for easier viewing, if you prefer.

This document is created by a script which scans comments in the source code file sqlite3session.h.

Objects:

        Constants:

            Functions:


SQLite Shared-Cache Mode

Choose any three.
About Sitemap Documentation Download License News Support

1.0 SQLite Shared-Cache Mode

Starting with version 3.3.0, SQLite includes a special "shared-cache" mode (disabled by default) intended for use in embedded servers. If shared-cache mode is enabled and a thread establishes multiple connections to the same database, the connections share a single data and schema cache. This can significantly reduce the quantity of memory and IO required by the system.

In version 3.5.0, shared-cache mode was modified so that the same cache can be shared across an entire process rather than just within a single thread. Prior to this change, there were restrictions on passing database connections between threads. Those restrictions were dropped in 3.5.0 update. This document describes shared-cache mode as of version 3.5.0.

Shared-cache mode changes the semantics of the locking model in some cases. The details are described by this document. A basic understanding of the normal SQLite locking model (see File Locking And Concurrency In SQLite Version 3 for details) is assumed.

2.0 Shared-Cache Locking Model

Externally, from the point of view of another process or thread, two or more database connections using a shared-cache appear as a single connection. The locking protocol used to arbitrate between multiple shared-caches or regular database users is described elsewhere.

Figure 1

Figure 1 depicts an example runtime configuration where three database connections have been established. Connection 1 is a normal SQLite database connection. Connections 2 and 3 share a cache The normal locking protocol is used to serialize database access between connection 1 and the shared cache. The internal protocol used to serialize (or not, see "Read-Uncommitted Isolation Mode" below) access to the shared-cache by connections 2 and 3 is described in the remainder of this section.

There are three levels to the shared-cache locking model, transaction level locking, table level locking and schema level locking. They are described in the following three sub-sections.

2.1 Transaction Level Locking

SQLite connections can open two kinds of transactions, read and write transactions. This is not done explicitly, a transaction is implicitly a read-transaction until it first writes to a database table, at which point it becomes a write-transaction.

At most one connection to a single shared cache may open a write transaction at any one time. This may co-exist with any number of read transactions.

2.2 Table Level Locking

When two or more connections use a shared-cache, locks are used to serialize concurrent access attempts on a per-table basis. Tables support two types of locks, "read-locks" and "write-locks". Locks are granted to connections - at any one time, each database connection has either a read-lock, write-lock or no lock on each database table.

At any one time, a single table may have any number of active read-locks or a single active write lock. To read data a table, a connection must first obtain a read-lock. To write to a table, a connection must obtain a write-lock on that table. If a required table lock cannot be obtained, the query fails and SQLITE_LOCKED is returned to the caller.

Once a connection obtains a table lock, it is not released until the current transaction (read or write) is concluded.

2.2.1 Read-Uncommitted Isolation Mode

The behaviour described above may be modified slightly by using the read_uncommitted pragma to change the isolation level from serialized (the default), to read-uncommitted.

A database connection in read-uncommitted mode does not attempt to obtain read-locks before reading from database tables as described above. This can lead to inconsistent query results if another database connection modifies a table while it is being read, but it also means that a read-transaction opened by a connection in read-uncommitted mode can neither block nor be blocked by any other connection.

Read-uncommitted mode has no effect on the locks required to write to database tables (i.e. read-uncommitted connections must still obtain write-locks and hence database writes may still block or be blocked). Also, read-uncommitted mode has no effect on the sqlite_master locks required by the rules enumerated below (see section "Schema (sqlite_master) Level Locking").

  /* Set the value of the read-uncommitted flag:
  **
  **   True  -> Set the connection to read-uncommitted mode.
  **   False -> Set the connection to serialized (the default) mode.
  */
  PRAGMA read_uncommitted = <boolean>;

  /* Retrieve the current value of the read-uncommitted flag */
  PRAGMA read_uncommitted;

2.3 Schema (sqlite_master) Level Locking

The sqlite_master table supports shared-cache read and write locks in the same way as all other database tables (see description above). The following special rules also apply:

  • A connection must obtain a read-lock on sqlite_master before accessing any database tables or obtaining any other read or write locks.
  • Before executing a statement that modifies the database schema (i.e. a CREATE or DROP TABLE statement), a connection must obtain a write-lock on sqlite_master.
  • A connection may not compile an SQL statement if any other connection is holding a write-lock on the sqlite_master table of any attached database (including the default database, "main").

3.0 Thread Related Issues

In SQLite versions 3.3.0 through 3.4.2 when shared-cache mode is enabled, a database connection may only be used by the thread that called sqlite3_open() to create it. And a connection could only share cache with another connection in the same thread. These restrictions were dropped beginning with SQLite version 3.5.0.

4.0 Shared Cache And Virtual Tables

In older versions of SQLite, shared cache mode could not be used together with virtual tables. This restriction was removed in SQLite version 3.6.17.

5.0 Enabling Shared-Cache Mode

Shared-cache mode is enabled on a per-process basis. Using the C interface, the following API can be used to enable or disable shared-cache mode for the calling thread:

int sqlite3_enable_shared_cache(int);

Each call sqlite3_enable_shared_cache() effects subsequent database connections created using sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(). Database connections that already exist are unaffected. Each call to sqlite3_enable_shared_cache() overrides all previous calls within the same process.

Individual database connections created using sqlite3_open_v2() can choose to participate or not participate in shared cache mode by using the SQLITE_OPEN_SHAREDCACHE or SQLITE_OPEN_PRIVATECACHE flags the third parameter. The use of either of these flags overrides the global shared cache mode setting established by sqlite3_enable_shared_cache(). No more than one of the flags should be used; if both SQLITE_OPEN_SHAREDCACHE and SQLITE_OPEN_PRIVATECACHE flags are used in the third argument to sqlite3_open_v2() then the behavior is undefined.


8+3 Filenames

Choose any three.
About Sitemap Documentation Download License News Support

SQLite And 8+3 Filenames

The default configuration of SQLite assumes the underlying filesystem supports long filenames.

SQLite does not impose any naming requirements on database files. SQLite will happily work with a database file that has any filename extension or with no extension at all. When auxiliary files are needed for a rollback journal or a write-ahead log or for one of the other kinds of temporary disk files, then the name for the auxiliary file is normally constructed by appending a suffix onto the end of the database file name. For example, if the original database is call "app.db" then the rollback journal will be called "app.db-journal" and the write-ahead log will be called "app.db-wal". This approach to auxiliary file naming works great on systems that support long filenames. But on systems that impose 8+3 filename constraints, the auxiliary files do not fit the 8+3 format even though the original database file does.

Changing Filesystems

The recommended fix for this problem is to select a different filesystem. These days, there is a huge selection of high-performance, reliable, patent-free filesystems that support long filenames. Where possible, it is recommended that embedded devices use one of these other filesystems. This will avoid compatibility issues and the danger of database corruption caused by inconsistent use of 8+3 filenames.

Adjusting SQLite To Use 8+3 Filenames

Some devices are compelled to use an older filesystem with 8+3 filename restrictions for backwards compatibility, or due to other non-technical factors. In such situations, SQLite can be coerced into using auxiliary files that fit the 8+3 pattern as follows:

  1. Compile the SQLite library with the either the compile-time options SQLITE_ENABLE_8_3_NAMES=1 or SQLITE_ENABLE_8_3_NAMES=2. Support for 8+3 filenames is not included in SQLite by default because it does introduce some overhead. The overhead is tiny, but even so, we do not want to burden the billions of SQLite applications that do not need 8+3 filename support.

  2. If the SQLITE_ENABLE_8_3_NAMES=1 option is used, then SQLite is capable of using 8+3 filenames but that capabilities is disabled and must be enabled separately for each database connection by using using URI filenames when opening or ATTACH-ing the database files and include the "8_3_names=1" query parameter in the URI. If SQLite is compiled with SQLITE_ENABLE_8_3_NAMES=2 then 8+3 filenames are enabled by default and this step can be skipped.

  3. Make sure that database filenames follow the 8+3 filename format and that they do not have an empty name or extension. In other words, the database filename must contain between 1 and 8 characters in the base name and between 1 and 3 characters in the extension. Blank extensions are not allowed.

When the steps above are used, SQLite will shorten filename extensions by only using the last 3 characters of the extension. Thus, for example, a file that would normally be called "app.db-journal" is shortened to just "app.nal". Similarly, "app.db-wal" will become "app.wal" and "app.db-shm" becomes "app.shm".

Note that it is very important that the database filename have some kind of extension. If there is no extension, then SQLite creates auxiliary filenames by appending to the base name of the file. Thus, a database named "db01" would have a rollback journal file named "db01-journal". And as this filename has no extension to shorten to 3 characters, it will be used as-is, and will violate 8+3 naming rules.

Database Corruption Warning

If a database file is accessed using 8+3 naming rather than the default long filename, then it must be consistently accessed using 8+3 naming by every database connection every time it is opened, or else there is a risk of database corruption. The auxiliary rollback journal and write-ahead log files are essential to SQLite for being about to recover from a crash. If an application is using 8+3 names and crashes, then the information needed to safely recover from the crash is stored in files with the ".nal" or ".wal" extension. If the next application to open the database does not specify the "8_3_names=1" URI parameter, then SQLite will use the long filenames to try to locate the rollback journal or write-ahead log files. It will not find them, since they were saved using 8+3 names by the application that crashed, and hence the database will not be properly recovered and will likely go corrupt.

Using a database file with 8+3 filenames in some cases while in other cases using long filenames is equivalent to deleting a hot journal.


SQLite Site Map

Choose any three.
About Sitemap Documentation Download License News Support

Popular Pages:

  • Features
  • Frequently Asked Questions
  • Well-known Users
  • Getting Started
  • When To Use SQLite
  • Distinctive Features
  • Alphabetical list of docs
  • Books About SQLite
  • Website Keyword Index
  • SQL Syntax
    • Pragmas
    • SQL functions
    • Date & time functions
    • Aggregate functions
  • C/C++ Interface Spec
    • Introduction
    • List of C-language APIs
  • The TCL Interface Spec
  • Mailing Lists
  • Report a Bug
  • Version control
    • Source code timeline
    • Documentation timeline

Permuted Index: (what is this?)

Other Documentation Indices:
  • Categorical Document List
  • Books About SQLite
  • Alphabetical List Of Documents
  • Website Keyword Index
  • 8+3 Filenames
  • About SQLite
  • About SQLite — Books
  • Allocation In SQLite — Dynamic Memory
  • Alphabetical List Of SQLite Documents
  • Amalgamation — The SQLite
  • An Asynchronous I/O Module For SQLite
  • An Introduction To The SQLite C/C++ Interface
  • And Concurrency In SQLite Version 3 — File Locking
  • and FTS4 Extensions — SQLite FTS3
  • API — SQLite Backup
  • API — SQLite Unlock-Notify
  • Applications — Using SQLite In Multi-Threaded
  • Appropriate Uses For SQLite
  • Architecture of SQLite
  • Asked Questions — SQLite Frequently
  • Asynchronous I/O Module For SQLite — An
  • Atomic Commit In SQLite
  • Autoincrement — SQLite
  • Backend (VFS) To SQLite — The OS
  • Backup API — SQLite
  • BLOBs — Internal Versus External
  • Books About SQLite
  • Branches Of SQLite — Private
  • Builds Of SQLite — Custom
  • C/C++ Interface — An Introduction To The SQLite
  • C/C++ Interface — SQLite Session Module
  • C/C++ Interface For SQLite Version 3
  • C/C++ Interface For SQLite Version 3 (old)
  • Changes From Version 3.4.2 To 3.5.0 — SQLite
  • Changes From Version 3.5.9 To 3.6.0 — SQLite
  • Changes in SQLite — File Format
  • Command Line Shell For SQLite
  • Commit In SQLite — Atomic
  • Comparison — SQLite Database Speed
  • Compilation Options For SQLite
  • Compile SQLite — How To
  • Concurrency In SQLite Version 3 — File Locking And
  • Conflict Resolution in SQLite — Constraint
  • Consortium — SQLite
  • Constraint Conflict Resolution in SQLite
  • Copyright — SQLite
  • Corrupt An SQLite Database File — How To
  • Custom Builds Of SQLite
  • Database — SQLite: Single File
  • Database Engine — Most Widely Deployed SQL
  • Database Engine of SQLite — The Virtual
  • Database File — How To Corrupt An SQLite
  • Database Speed Comparison — SQLite
  • Databases — File Format For SQLite
  • Databases — In-Memory
  • Datatypes In SQLite version 2
  • Datatypes In SQLite Version 3
  • Deployed SQL Database Engine — Most Widely
  • Developer Links — SQLite
  • Developers — SQLite
  • Diagrams For SQLite — Syntax
  • Distinctive Features Of SQLite
  • Documentation — SQLite
  • Documents — Alphabetical List Of SQLite
  • Does Not Implement — SQL Features That SQLite
  • Download Page — SQLite
  • Dynamic Memory Allocation In SQLite
  • Engine — Most Widely Deployed SQL Database
  • Engine of SQLite — The Virtual Database
  • EXPLAIN QUERY PLAN
  • Extensions — SQLite FTS3 and FTS4
  • External BLOBs — Internal Versus
  • Features Of SQLite
  • Features Of SQLite — Distinctive
  • Features That SQLite Does Not Implement — SQL
  • File — How To Corrupt An SQLite Database
  • File Database — SQLite: Single
  • File Format Changes in SQLite
  • File Format For SQLite Databases
  • File Locking And Concurrency In SQLite Version 3
  • Filenames — 8+3
  • Files Used By SQLite — Temporary
  • Footprint — SQLite Library
  • Foreign Key Support — SQLite
  • Format Changes in SQLite — File
  • Format For SQLite Databases — File
  • Frequently Asked Questions — SQLite
  • From Version 3.4.2 To 3.5.0 — SQLite Changes
  • From Version 3.5.9 To 3.6.0 — SQLite Changes
  • FTS3 and FTS4 Extensions — SQLite
  • FTS4 Extensions — SQLite FTS3 and
  • Handling in SQLite — NULL
  • History Of SQLite — Release
  • Home Page — SQLite
  • How SQLite Is Tested
  • How To Compile SQLite
  • How To Corrupt An SQLite Database File
  • I/O Module For SQLite — An Asynchronous
  • Identifiers — Uniform Resource
  • Implement — SQL Features That SQLite Does Not
  • Implementation Limits For SQLite
  • In-Memory Databases
  • Index — Website Keyword
  • Interface — An Introduction To The SQLite C/C++
  • Interface — SQLite Session Module C/C++
  • Interface For SQLite Version 3 — C/C++
  • Interface For SQLite Version 3 (old) — C/C++
  • interface to SQLite Version 2 — The C language
  • interface to the SQLite library — The Tcl
  • Internal Versus External BLOBs
  • Introduction To The SQLite C/C++ Interface — An
  • Key Support — SQLite Foreign
  • Keyword Index — Website
  • language interface to SQLite Version 2 — The C
  • Language Understood by SQLite — Query
  • Less — SQLite In 5 Minutes Or
  • library — The Tcl interface to the SQLite
  • Library Footprint — SQLite
  • Limits For SQLite — Implementation
  • Line Shell For SQLite — Command
  • Links — SQLite Developer
  • List Of SQLite Documents — Alphabetical
  • Locking And Concurrency In SQLite Version 3 — File
  • Logging — Write-Ahead
  • Machine Opcodes — SQLite Virtual
  • Map — SQLite Site
  • Mechanism Of SQLite — The Virtual Table
  • Memory Allocation In SQLite — Dynamic
  • Minutes Or Less — SQLite In 5
  • Mode — SQLite Shared-Cache
  • Module — The SQLite R*Tree
  • Module C/C++ Interface — SQLite Session
  • Module For SQLite — An Asynchronous I/O
  • Most Widely Deployed SQL Database Engine
  • Multi-Threaded Applications — Using SQLite In
  • News — Recent SQLite
  • News — SQLite Older
  • Not Implement — SQL Features That SQLite Does
  • NULL Handling in SQLite
  • Older News — SQLite
  • Opcodes — SQLite Virtual Machine
  • Optimizer Overview — The SQLite Query
  • Options — SQLite Support
  • Options For SQLite — Compilation
  • Overview — SQLite Version 3
  • Overview — The SQLite Query Optimizer
  • Page — SQLite Download
  • Page — SQLite Home
  • PLAN — EXPLAIN QUERY
  • Planning — Query
  • Pragma statements supported by SQLite
  • Private Branches Of SQLite
  • Query Language Understood by SQLite
  • Query Optimizer Overview — The SQLite
  • QUERY PLAN — EXPLAIN
  • Query Planning
  • Questions — SQLite Frequently Asked
  • R*Tree Module — The SQLite
  • Recent SQLite News
  • Release History Of SQLite
  • Resolution in SQLite — Constraint Conflict
  • Resource Identifiers — Uniform
  • Self-Contained — SQLite Is
  • Serverless — SQLite Is
  • Session Module C/C++ Interface — SQLite
  • Shared-Cache Mode — SQLite
  • Shell For SQLite — Command Line
  • Single File Database — SQLite:
  • Site Map — SQLite
  • Speed Comparison — SQLite Database
  • SQL Database Engine — Most Widely Deployed
  • SQL Features That SQLite Does Not Implement
  • SQLite Autoincrement
  • SQLite Backup API
  • SQLite Changes From Version 3.4.2 To 3.5.0
  • SQLite Changes From Version 3.5.9 To 3.6.0
  • SQLite Consortium
  • SQLite Copyright
  • SQLite Database Speed Comparison
  • SQLite Developer Links
  • SQLite Developers
  • SQLite Documentation
  • SQLite Download Page
  • SQLite Foreign Key Support
  • SQLite Frequently Asked Questions
  • SQLite FTS3 and FTS4 Extensions
  • SQLite Home Page
  • SQLite In 5 Minutes Or Less
  • SQLite Is Self-Contained
  • SQLite Is Serverless
  • SQLite Is Transactional
  • SQLite Library Footprint
  • SQLite Older News
  • SQLite Session Module C/C++ Interface
  • SQLite Shared-Cache Mode
  • SQLite Site Map
  • SQLite Support Options
  • SQLite TH3
  • SQLite Unlock-Notify API
  • SQLite Version 3 Overview
  • SQLite Virtual Machine Opcodes
  • SQLite: Single File Database
  • statements supported by SQLite — Pragma
  • Support — SQLite Foreign Key
  • Support Options — SQLite
  • supported by SQLite — Pragma statements
  • Syntax Diagrams For SQLite
  • Table Mechanism Of SQLite — The Virtual
  • Tcl interface to the SQLite library — The
  • Temporary Files Used By SQLite
  • Tested — How SQLite Is
  • TH3 — SQLite
  • That SQLite Does Not Implement — SQL Features
  • The C language interface to SQLite Version 2
  • The OS Backend (VFS) To SQLite
  • The SQLite Amalgamation
  • The SQLite Query Optimizer Overview
  • The SQLite R*Tree Module
  • The Tcl interface to the SQLite library
  • The Virtual Database Engine of SQLite
  • The Virtual Table Mechanism Of SQLite
  • Transactional — SQLite Is
  • Understood by SQLite — Query Language
  • Uniform Resource Identifiers
  • Unlock-Notify API — SQLite
  • Used By SQLite — Temporary Files
  • Users Of SQLite — Well-Known
  • Uses For SQLite — Appropriate
  • Using SQLite In Multi-Threaded Applications
  • version 2 — Datatypes In SQLite
  • Version 2 — The C language interface to SQLite
  • Version 3 — C/C++ Interface For SQLite
  • Version 3 — Datatypes In SQLite
  • Version 3 — File Locking And Concurrency In SQLite
  • Version 3 (old) — C/C++ Interface For SQLite
  • Version 3 Overview — SQLite
  • Version 3.4.2 To 3.5.0 — SQLite Changes From
  • Version 3.5.9 To 3.6.0 — SQLite Changes From
  • Versus External BLOBs — Internal
  • Virtual Database Engine of SQLite — The
  • Virtual Machine Opcodes — SQLite
  • Virtual Table Mechanism Of SQLite — The
  • Website Keyword Index
  • Well-Known Users Of SQLite
  • Widely Deployed SQL Database Engine — Most
  • Write-Ahead Logging
  • Zero-Configuration


SQLite Database Speed Comparison

SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

Database Speed Comparison

Note: This document is very very old. It describes a speed comparison between archaic versions of SQLite, MySQL and PostgreSQL.

The numbers here are old enough to be nearly meaningless. Until it is updated, use this document only as proof that SQLite is not a sluggard.

Executive Summary

A series of tests were run to measure the relative performance of SQLite 2.7.6, PostgreSQL 7.1.3, and MySQL 3.23.41. The following are general conclusions drawn from these experiments:

  • SQLite 2.7.6 is significantly faster (sometimes as much as 10 or 20 times faster) than the default PostgreSQL 7.1.3 installation on RedHat 7.2 for most common operations.

  • SQLite 2.7.6 is often faster (sometimes more than twice as fast) than MySQL 3.23.41 for most common operations.

  • SQLite does not execute CREATE INDEX or DROP TABLE as fast as the other databases. But this is not seen as a problem because those are infrequent operations.

  • SQLite works best if you group multiple operations together into a single transaction.

The results presented here come with the following caveats:

  • These tests did not attempt to measure multi-user performance or optimization of complex queries involving multiple joins and subqueries.

  • These tests are on a relatively small (approximately 14 megabyte) database. They do not measure how well the database engines scale to larger problems.

Test Environment

The platform used for these tests is a 1.6GHz Athlon with 1GB or memory and an IDE disk drive. The operating system is RedHat Linux 7.2 with a stock kernel.

The PostgreSQL and MySQL servers used were as delivered by default on RedHat 7.2. (PostgreSQL version 7.1.3 and MySQL version 3.23.41.) No effort was made to tune these engines. Note in particular the default MySQL configuration on RedHat 7.2 does not support transactions. Not having to support transactions gives MySQL a big speed advantage, but SQLite is still able to hold its own on most tests.

I am told that the default PostgreSQL configuration in RedHat 7.3 is unnecessarily conservative (it is designed to work on a machine with 8MB of RAM) and that PostgreSQL could be made to run a lot faster with some knowledgeable configuration tuning. Matt Sergeant reports that he has tuned his PostgreSQL installation and rerun the tests shown below. His results show that PostgreSQL and MySQL run at about the same speed. For Matt's results, visit

http://www.sergeant.org/sqlite_vs_pgsync.html

SQLite was tested in the same configuration that it appears on the website. It was compiled with -O6 optimization and with the -DNDEBUG=1 switch which disables the many "assert()" statements in the SQLite code. The -DNDEBUG=1 compiler option roughly doubles the speed of SQLite.

All tests are conducted on an otherwise quiescent machine. A simple Tcl script was used to generate and run all the tests. A copy of this Tcl script can be found in the SQLite source tree in the file tools/speedtest.tcl.

The times reported on all tests represent wall-clock time in seconds. Two separate time values are reported for SQLite. The first value is for SQLite in its default configuration with full disk synchronization turned on. With synchronization turned on, SQLite executes an fsync() system call (or the equivalent) at key points to make certain that critical data has actually been written to the disk drive surface. Synchronization is necessary to guarantee the integrity of the database if the operating system crashes or the computer powers down unexpectedly in the middle of a database update. The second time reported for SQLite is when synchronization is turned off. With synchronization off, SQLite is sometimes much faster, but there is a risk that an operating system crash or an unexpected power failure could damage the database. Generally speaking, the synchronous SQLite times are for comparison against PostgreSQL (which is also synchronous) and the asynchronous SQLite times are for comparison against the asynchronous MySQL engine.

Test 1: 1000 INSERTs

CREATE TABLE t1(a INTEGER, b INTEGER, c VARCHAR(100));
INSERT INTO t1 VALUES(1,13153,'thirteen thousand one hundred fifty three');
INSERT INTO t1 VALUES(2,75560,'seventy five thousand five hundred sixty');
... 995 lines omitted
INSERT INTO t1 VALUES(998,66289,'sixty six thousand two hundred eighty nine');
INSERT INTO t1 VALUES(999,24322,'twenty four thousand three hundred twenty two');
INSERT INTO t1 VALUES(1000,94142,'ninety four thousand one hundred forty two');
PostgreSQL: | 4.373
MySQL: | 0.114
SQLite 2.7.6: | 13.061
SQLite 2.7.6 (nosync): | 0.223

Because it does not have a central server to coordinate access, SQLite must close and reopen the database file, and thus invalidate its cache, for each transaction. In this test, each SQL statement is a separate transaction so the database file must be opened and closed and the cache must be flushed 1000 times. In spite of this, the asynchronous version of SQLite is still nearly as fast as MySQL. Notice how much slower the synchronous version is, however. SQLite calls fsync() after each synchronous transaction to make sure that all data is safely on the disk surface before continuing. For most of the 13 seconds in the synchronous test, SQLite was sitting idle waiting on disk I/O to complete.

Test 2: 25000 INSERTs in a transaction

BEGIN;
CREATE TABLE t2(a INTEGER, b INTEGER, c VARCHAR(100));
INSERT INTO t2 VALUES(1,59672,'fifty nine thousand six hundred seventy two');
... 24997 lines omitted
INSERT INTO t2 VALUES(24999,89569,'eighty nine thousand five hundred sixty nine');
INSERT INTO t2 VALUES(25000,94666,'ninety four thousand six hundred sixty six');
COMMIT;
PostgreSQL: | 4.900
MySQL: | 2.184
SQLite 2.7.6: | 0.914
SQLite 2.7.6 (nosync): | 0.757

When all the INSERTs are put in a transaction, SQLite no longer has to close and reopen the database or invalidate its cache between each statement. It also does not have to do any fsync()s until the very end. When unshackled in this way, SQLite is much faster than either PostgreSQL and MySQL.

Test 3: 25000 INSERTs into an indexed table

BEGIN;
CREATE TABLE t3(a INTEGER, b INTEGER, c VARCHAR(100));
CREATE INDEX i3 ON t3(c);
... 24998 lines omitted
INSERT INTO t3 VALUES(24999,88509,'eighty eight thousand five hundred nine');
INSERT INTO t3 VALUES(25000,84791,'eighty four thousand seven hundred ninety one');
COMMIT;
PostgreSQL: | 8.175
MySQL: | 3.197
SQLite 2.7.6: | 1.555
SQLite 2.7.6 (nosync): | 1.402

There were reports that SQLite did not perform as well on an indexed table. This test was recently added to disprove those rumors. It is true that SQLite is not as fast at creating new index entries as the other engines (see Test 6 below) but its overall speed is still better.

Test 4: 100 SELECTs without an index

BEGIN;
SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<1000;
SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<1100;
... 96 lines omitted
SELECT count(*), avg(b) FROM t2 WHERE b>=9800 AND b<10800;
SELECT count(*), avg(b) FROM t2 WHERE b>=9900 AND b<10900;
COMMIT;
PostgreSQL: | 3.629
MySQL: | 2.760
SQLite 2.7.6: | 2.494
SQLite 2.7.6 (nosync): | 2.526

This test does 100 queries on a 25000 entry table without an index, thus requiring a full table scan. Prior versions of SQLite used to be slower than PostgreSQL and MySQL on this test, but recent performance enhancements have increased its speed so that it is now the fastest of the group.

Test 5: 100 SELECTs on a string comparison

BEGIN;
SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one%';
SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%two%';
... 96 lines omitted
SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%ninety nine%';
SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one hundred%';
COMMIT;
PostgreSQL: | 13.409
MySQL: | 4.640
SQLite 2.7.6: | 3.362
SQLite 2.7.6 (nosync): | 3.372

This test still does 100 full table scans but it uses uses string comparisons instead of numerical comparisons. SQLite is over three times faster than PostgreSQL here and about 30% faster than MySQL.

Test 6: Creating an index

CREATE INDEX i2a ON t2(a);
CREATE INDEX i2b ON t2(b);
PostgreSQL: | 0.381
MySQL: | 0.318
SQLite 2.7.6: | 0.777
SQLite 2.7.6 (nosync): | 0.659

SQLite is slower at creating new indices. This is not a huge problem (since new indices are not created very often) but it is something that is being worked on. Hopefully, future versions of SQLite will do better here.

Test 7: 5000 SELECTs with an index

SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<100;
SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<200;
SELECT count(*), avg(b) FROM t2 WHERE b>=200 AND b<300;
... 4994 lines omitted
SELECT count(*), avg(b) FROM t2 WHERE b>=499700 AND b<499800;
SELECT count(*), avg(b) FROM t2 WHERE b>=499800 AND b<499900;
SELECT count(*), avg(b) FROM t2 WHERE b>=499900 AND b<500000;
PostgreSQL: | 4.614
MySQL: | 1.270
SQLite 2.7.6: | 1.121
SQLite 2.7.6 (nosync): | 1.162

All three database engines run faster when they have indices to work with. But SQLite is still the fastest.

Test 8: 1000 UPDATEs without an index

BEGIN;
UPDATE t1 SET b=b*2 WHERE a>=0 AND a<10;
UPDATE t1 SET b=b*2 WHERE a>=10 AND a<20;
... 996 lines omitted
UPDATE t1 SET b=b*2 WHERE a>=9980 AND a<9990;
UPDATE t1 SET b=b*2 WHERE a>=9990 AND a<10000;
COMMIT;
PostgreSQL: | 1.739
MySQL: | 8.410
SQLite 2.7.6: | 0.637
SQLite 2.7.6 (nosync): | 0.638

For this particular UPDATE test, MySQL is consistently five or ten times slower than PostgreSQL and SQLite. I do not know why. MySQL is normally a very fast engine. Perhaps this problem has been addressed in later versions of MySQL.

Test 9: 25000 UPDATEs with an index

BEGIN;
UPDATE t2 SET b=468026 WHERE a=1;
UPDATE t2 SET b=121928 WHERE a=2;
... 24996 lines omitted
UPDATE t2 SET b=35065 WHERE a=24999;
UPDATE t2 SET b=347393 WHERE a=25000;
COMMIT;
PostgreSQL: | 18.797
MySQL: | 8.134
SQLite 2.7.6: | 3.520
SQLite 2.7.6 (nosync): | 3.104

As recently as version 2.7.0, SQLite ran at about the same speed as MySQL on this test. But recent optimizations to SQLite have more than doubled speed of UPDATEs.

Test 10: 25000 text UPDATEs with an index

BEGIN;
UPDATE t2 SET c='one hundred forty eight thousand three hundred eighty two' WHERE a=1;
UPDATE t2 SET c='three hundred sixty six thousand five hundred two' WHERE a=2;
... 24996 lines omitted
UPDATE t2 SET c='three hundred eighty three thousand ninety nine' WHERE a=24999;
UPDATE t2 SET c='two hundred fifty six thousand eight hundred thirty' WHERE a=25000;
COMMIT;
PostgreSQL: | 48.133
MySQL: | 6.982
SQLite 2.7.6: | 2.408
SQLite 2.7.6 (nosync): | 1.725

Here again, version 2.7.0 of SQLite used to run at about the same speed as MySQL. But now version 2.7.6 is over two times faster than MySQL and over twenty times faster than PostgreSQL.

In fairness to PostgreSQL, it started thrashing on this test. A knowledgeable administrator might be able to get PostgreSQL to run a lot faster here by tweaking and tuning the server a little.

Test 11: INSERTs from a SELECT

BEGIN;
INSERT INTO t1 SELECT b,a,c FROM t2;
INSERT INTO t2 SELECT b,a,c FROM t1;
COMMIT;
PostgreSQL: | 61.364
MySQL: | 1.537
SQLite 2.7.6: | 2.787
SQLite 2.7.6 (nosync): | 1.599

The asynchronous SQLite is just a shade slower than MySQL on this test. (MySQL seems to be especially adept at INSERT...SELECT statements.) The PostgreSQL engine is still thrashing - most of the 61 seconds it used were spent waiting on disk I/O.

Test 12: DELETE without an index

DELETE FROM t2 WHERE c LIKE '%fifty%';
PostgreSQL: | 1.509
MySQL: | 0.975
SQLite 2.7.6: | 4.004
SQLite 2.7.6 (nosync): | 0.560

The synchronous version of SQLite is the slowest of the group in this test, but the asynchronous version is the fastest. The difference is the extra time needed to execute fsync().

Test 13: DELETE with an index

DELETE FROM t2 WHERE a>10 AND a<20000;
PostgreSQL: | 1.316
MySQL: | 2.262
SQLite 2.7.6: | 2.068
SQLite 2.7.6 (nosync): | 0.752

This test is significant because it is one of the few where PostgreSQL is faster than MySQL. The asynchronous SQLite is, however, faster then both the other two.

Test 14: A big INSERT after a big DELETE

INSERT INTO t2 SELECT * FROM t1;
PostgreSQL: | 13.168
MySQL: | 1.815
SQLite 2.7.6: | 3.210
SQLite 2.7.6 (nosync): | 1.485

Some older versions of SQLite (prior to version 2.4.0) would show decreasing performance after a sequence of DELETEs followed by new INSERTs. As this test shows, the problem has now been resolved.

Test 15: A big DELETE followed by many small INSERTs

BEGIN;
DELETE FROM t1;
INSERT INTO t1 VALUES(1,10719,'ten thousand seven hundred nineteen');
... 11997 lines omitted
INSERT INTO t1 VALUES(11999,72836,'seventy two thousand eight hundred thirty six');
INSERT INTO t1 VALUES(12000,64231,'sixty four thousand two hundred thirty one');
COMMIT;
PostgreSQL: | 4.556
MySQL: | 1.704
SQLite 2.7.6: | 0.618
SQLite 2.7.6 (nosync): | 0.406

SQLite is very good at doing INSERTs within a transaction, which probably explains why it is so much faster than the other databases at this test.

Test 16: DROP TABLE

DROP TABLE t1;
DROP TABLE t2;
DROP TABLE t3;
PostgreSQL: | 0.135
MySQL: | 0.015
SQLite 2.7.6: | 0.939
SQLite 2.7.6 (nosync): | 0.254

SQLite is slower than the other databases when it comes to dropping tables. This probably is because when SQLite drops a table, it has to go through and erase the records in the database file that deal with that table. MySQL and PostgreSQL, on the other hand, use separate files to represent each table so they can drop a table simply by deleting a file, which is much faster.

On the other hand, dropping tables is not a very common operation so if SQLite takes a little longer, that is not seen as a big problem.


Command Line Shell For SQLite

The SQLite library includes a simple command-line utility named sqlite3 (or sqlite3.exe on windows) that allows the user to manually enter and execute SQL commands against an SQLite database. This document provides a brief introduction on how to use the sqlite3 program.

Getting Started

To start the sqlite3 program, just type "sqlite3" followed by the name the file that holds the SQLite database. If the file does not exist, a new one is created automatically. The sqlite3 program will then prompt you to enter SQL. Type in SQL statements (terminated by a semicolon), press "Enter" and the SQL will be executed.

For example, to create a new SQLite database named "ex1" with a single table named "tbl1", you might do this:

$ sqlite3 ex1
SQLite version 3.6.11
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> create table tbl1(one varchar(10), two smallint);
sqlite> insert into tbl1 values('hello!',10);
sqlite> insert into tbl1 values('goodbye', 20);
sqlite> select * from tbl1;
hello!|10
goodbye|20
sqlite>

You can terminate the sqlite3 program by typing your systems End-Of-File character (usually a Control-D). Use the interrupt character (usually a Control-C) to stop a long-running SQL statement.

Make sure you type a semicolon at the end of each SQL command! The sqlite3 program looks for a semicolon to know when your SQL command is complete. If you omit the semicolon, sqlite3 will give you a continuation prompt and wait for you to enter more text to be added to the current SQL command. This feature allows you to enter SQL commands that span multiple lines. For example:

sqlite> CREATE TABLE tbl2 (
   ...>   f1 varchar(30) primary key,
   ...>   f2 text,
   ...>   f3 real
   ...> );
sqlite>

Aside: Querying the SQLITE_MASTER table

The database schema in an SQLite database is stored in a special table named "sqlite_master". You can execute "SELECT" statements against the special sqlite_master table just like any other table in an SQLite database. For example:

$ sqlite3 ex1
SQLite version 3.6.11
Enter ".help" for instructions
sqlite> select * from sqlite_master;
    type = table
    name = tbl1
tbl_name = tbl1
rootpage = 3
     sql = create table tbl1(one varchar(10), two smallint)
sqlite>

But you cannot execute DROP TABLE, UPDATE, INSERT or DELETE against the sqlite_master table. The sqlite_master table is updated automatically as you create or drop tables and indices from the database. You can not make manual changes to the sqlite_master table.

The schema for TEMPORARY tables is not stored in the "sqlite_master" table since TEMPORARY tables are not visible to applications other than the application that created the table. The schema for TEMPORARY tables is stored in another special table named "sqlite_temp_master". The "sqlite_temp_master" table is temporary itself.

Special commands to sqlite3

Most of the time, sqlite3 just reads lines of input and passes them on to the SQLite library for execution. But if an input line begins with a dot ("."), then that line is intercepted and interpreted by the sqlite3 program itself. These "dot commands" are typically used to change the output format of queries, or to execute certain prepackaged query statements.

For a listing of the available dot commands, you can enter ".help" at any time. For example:

sqlite> .help
.backup ?DB? FILE      Backup DB (default "main") to FILE
.bail ON|OFF           Stop after hitting an error.  Default OFF
.databases             List names and files of attached databases
.dump ?TABLE? ...      Dump the database in an SQL text format
.echo ON|OFF           Turn command echo on or off
.exit                  Exit this program
.explain ON|OFF        Turn output mode suitable for EXPLAIN on or off.
.genfkey ?OPTIONS?     Options are:
                         --no-drop: Do not drop old fkey triggers.
                         --ignore-errors: Ignore tables with fkey errors
                         --exec: Execute generated SQL immediately
                       See file tool/genfkey.README in the source
                       distribution for further information.
.header(s) ON|OFF      Turn display of headers on or off
.help                  Show this message
.import FILE TABLE     Import data from FILE into TABLE
.indices TABLE         Show names of all indices on TABLE
.iotrace FILE          Enable I/O diagnostic logging to FILE
.load FILE ?ENTRY?     Load an extension library
.mode MODE ?TABLE?     Set output mode where MODE is one of:
                         csv      Comma-separated values
                         column   Left-aligned columns.  (See .width)
                         html     HTML <table> code
                         insert   SQL insert statements for TABLE
                         line     One value per line
                         list     Values delimited by .separator string
                         tabs     Tab-separated values
                         tcl      TCL list elements
.nullvalue STRING      Print STRING in place of NULL values
.output FILENAME       Send output to FILENAME
.output stdout         Send output to the screen
.prompt MAIN CONTINUE  Replace the standard prompts
.quit                  Exit this program
.read FILENAME         Execute SQL in FILENAME
.restore ?DB? FILE     Restore content of DB (default "main") from FILE
.schema ?TABLE?        Show the CREATE statements
.separator STRING      Change separator used by output mode and .import
.show                  Show the current values for various settings
.tables ?PATTERN?      List names of tables matching a LIKE pattern
.timeout MS            Try opening locked tables for MS milliseconds
.timer ON|OFF          Turn the CPU timer measurement on or off
.width NUM NUM ...     Set column widths for "column" mode
sqlite>

Changing Output Formats

The sqlite3 program is able to show the results of a query in eight different formats: "csv", "column", "html", "insert", "line", "list", "tabs", and "tcl". You can use the ".mode" dot command to switch between these output formats.

The default output mode is "list". In list mode, each record of a query result is written on one line of output and each column within that record is separated by a specific separator string. The default separator is a pipe symbol ("|"). List mode is especially useful when you are going to send the output of a query to another program (such as AWK) for additional processing.

sqlite> .mode list
sqlite> select * from tbl1;
hello|10
goodbye|20
sqlite>

You can use the ".separator" dot command to change the separator for list mode. For example, to change the separator to a comma and a space, you could do this:

sqlite> .separator ", "
sqlite> select * from tbl1;
hello, 10
goodbye, 20
sqlite>

In "line" mode, each column in a row of the database is shown on a line by itself. Each line consists of the column name, an equal sign and the column data. Successive records are separated by a blank line. Here is an example of line mode output:

sqlite> .mode line
sqlite> select * from tbl1;
one = hello
two = 10

one = goodbye
two = 20
sqlite>

In column mode, each record is shown on a separate line with the data aligned in columns. For example:

sqlite> .mode column
sqlite> select * from tbl1;
one         two
----------  ----------
hello       10
goodbye     20
sqlite>

By default, each column is at least 10 characters wide. Data that is too wide to fit in a column is truncated. You can adjust the column widths using the ".width" command. Like this:

sqlite> .width 12 6
sqlite> select * from tbl1;
one           two
------------  ------
hello         10
goodbye       20
sqlite>

The ".width" command in the example above sets the width of the first column to 12 and the width of the second column to 6. All other column widths were unaltered. You can gives as many arguments to ".width" as necessary to specify the widths of as many columns as are in your query results.

If you specify a column a width of 0, then the column width is automatically adjusted to be the maximum of three numbers: 10, the width of the header, and the width of the first row of data. This makes the column width self-adjusting. The default width setting for every column is this auto-adjusting 0 value.

The column labels that appear on the first two lines of output can be turned on and off using the ".header" dot command. In the examples above, the column labels are on. To turn them off you could do this:

sqlite> .header off
sqlite> select * from tbl1;
hello         10
goodbye       20
sqlite>

Another useful output mode is "insert". In insert mode, the output is formatted to look like SQL INSERT statements. You can use insert mode to generate text that can later be used to input data into a different database.

When specifying insert mode, you have to give an extra argument which is the name of the table to be inserted into. For example:

sqlite> .mode insert new_table
sqlite> select * from tbl1;
INSERT INTO 'new_table' VALUES('hello',10);
INSERT INTO 'new_table' VALUES('goodbye',20);
sqlite>

The last output mode is "html". In this mode, sqlite3 writes the results of the query as an XHTML table. The beginning <TABLE> and the ending </TABLE> are not written, but all of the intervening <TR>s, <TH>s, and <TD>s are. The html output mode is envisioned as being useful for CGI.

Writing results to a file

By default, sqlite3 sends query results to standard output. You can change this using the ".output" command. Just put the name of an output file as an argument to the .output command and all subsequent query results will be written to that file. Use ".output stdout" to begin writing to standard output again. For example:

sqlite> .mode list
sqlite> .separator |
sqlite> .output test_file_1.txt
sqlite> select * from tbl1;
sqlite> .exit
$ cat test_file_1.txt
hello|10
goodbye|20
$

Querying the database schema

The sqlite3 program provides several convenience commands that are useful for looking at the schema of the database. There is nothing that these commands do that cannot be done by some other means. These commands are provided purely as a shortcut.

For example, to see a list of the tables in the database, you can enter ".tables".

sqlite> .tables
tbl1
tbl2
sqlite>

The ".tables" command is similar to setting list mode then executing the following query:

SELECT name FROM sqlite_master
WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
UNION ALL
SELECT name FROM sqlite_temp_master
WHERE type IN ('table','view')
ORDER BY 1

In fact, if you look at the source code to the sqlite3 program (found in the source tree in the file src/shell.c) you'll find exactly the above query.

The ".indices" command works in a similar way to list all of the indices for a particular table. The ".indices" command takes a single argument which is the name of the table for which the indices are desired. Last, but not least, is the ".schema" command. With no arguments, the ".schema" command shows the original CREATE TABLE and CREATE INDEX statements that were used to build the current database. If you give the name of a table to ".schema", it shows the original CREATE statement used to make that table and all if its indices. We have:

sqlite> .schema
create table tbl1(one varchar(10), two smallint)
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
  f3 real
)
sqlite> .schema tbl2
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
  f3 real
)
sqlite>

The ".schema" command accomplishes the same thing as setting list mode, then entering the following query:

SELECT sql FROM
   (SELECT * FROM sqlite_master UNION ALL
    SELECT * FROM sqlite_temp_master)
WHERE type!='meta'
ORDER BY tbl_name, type DESC, name

Or, if you give an argument to ".schema" because you only want the schema for a single table, the query looks like this:

SELECT sql FROM
   (SELECT * FROM sqlite_master UNION ALL
    SELECT * FROM sqlite_temp_master)
WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
ORDER BY substr(type,2,1), name

You can supply an argument to the .schema command. If you do, the query looks like this:

SELECT sql FROM
   (SELECT * FROM sqlite_master UNION ALL
    SELECT * FROM sqlite_temp_master)
WHERE tbl_name LIKE '%s'
  AND type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
ORDER BY substr(type,2,1), name

The "%s" in the query is replace by your argument. This allows you to view the schema for some subset of the database.

sqlite> .schema %abc%

Along these same lines, the ".table" command also accepts a pattern as its first argument. If you give an argument to the .table command, a "%" is both appended and prepended and a LIKE clause is added to the query. This allows you to list only those tables that match a particular pattern.

The ".databases" command shows a list of all databases open in the current connection. There will always be at least 2. The first one is "main", the original database opened. The second is "temp", the database used for temporary tables. There may be additional databases listed for databases attached using the ATTACH statement. The first output column is the name the database is attached with, and the second column is the filename of the external file.

sqlite> .databases

Converting An Entire Database To An ASCII Text File

Use the ".dump" command to convert the entire contents of a database into a single ASCII text file. This file can be converted back into a database by piping it back into sqlite3.

A good way to make an archival copy of a database is this:

$ echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz

This generates a file named ex1.dump.gz that contains everything you need to reconstruct the database at a later time, or on another machine. To reconstruct the database, just type:

$ zcat ex1.dump.gz | sqlite3 ex2

The text format is pure SQL so you can also use the .dump command to export an SQLite database into other popular SQL database engines. Like this:

$ createdb ex2
$ sqlite3 ex1 .dump | psql ex2

Other Dot Commands

The ".explain" dot command can be used to set the output mode to "column" and to set the column widths to values that are reasonable for looking at the output of an EXPLAIN command. The EXPLAIN command is an SQLite-specific SQL extension that is useful for debugging. If any regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and analyzed but is not executed. Instead, the sequence of virtual machine instructions that would have been used to execute the SQL command are returned like a query result. For example:

sqlite> .explain
sqlite> explain delete from tbl1 where two<20;
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -------------------------------------
0     ListOpen      0      0
1     Open          0      1      tbl1
2     Next          0      9
3     Field         0      1
4     Integer       20     0
5     Ge            0      2
6     Key           0      0
7     ListWrite     0      0
8     Goto          0      2
9     Noop          0      0
10    ListRewind    0      0
11    ListRead      0      14
12    Delete        0      0
13    Goto          0      11
14    ListClose     0      0

The ".timeout" command sets the amount of time that the sqlite3 program will wait for locks to clear on files it is trying to access before returning an error. The default value of the timeout is zero so that an error is returned immediately if any needed database table or index is locked.

And finally, we mention the ".exit" command which causes the sqlite3 program to exit.

Using sqlite3 in a shell script

One way to use sqlite3 in a shell script is to use "echo" or "cat" to generate a sequence of commands in a file, then invoke sqlite3 while redirecting input from the generated command file. This works fine and is appropriate in many circumstances. But as an added convenience, sqlite3 allows a single SQL command to be entered on the command line as a second argument after the database name. When the sqlite3 program is launched with two arguments, the second argument is passed to the SQLite library for processing, the query results are printed on standard output in list mode, and the program exits. This mechanism is designed to make sqlite3 easy to use in conjunction with programs like "awk". For example:

$ sqlite3 ex1 'select * from tbl1' |
>  awk '{printf "<tr><td>%s<td>%s\n",$1,$2 }'
<tr><td>hello<td>10
<tr><td>goodbye<td>20
$

Ending shell commands

SQLite commands are normally terminated by a semicolon. In the shell you can also use the word "GO" (case-insensitive) or a slash character "/" on a line by itself to end a command. These are used by SQL Server and Oracle, respectively. These won't work in sqlite3_exec(), because the shell translates these into a semicolon before passing them to that function.

Compiling the sqlite3 program from sources

The source code to the sqlite3 command line interface is in a single file named "shell.c" which you can download from the SQLite website. Compile this file (together with the sqlite3 library source code to generate the executable. For example:

gcc -o sqlite3 shell.c sqlite3.c -ldl -lpthread


SQLite Support Options

Professional Support

If you would like professional support for SQLite or if you want custom modifications performed by the original author of SQLite, these services are available for a modest fee. For additional information visit http://www.hwaci.com/sw/sqlite/prosupport.html or contact:

D. Richard Hipp
Hwaci - Applied Software Research
704.948.4565
drh@hwaci.com

Proprietary SQLite Extensions

The core SQLite library found on this website is in the public domain. But there also exist proprietary, licensed extensions to SQLite, written and maintained by the original developer.

  • The SQLite Encryption Extension (SEE) will read and write database file encrypted using 128-bit or 256-bit AES.

  • The SQLite Compressed and Encrypted Read-Only Database (CEROD) Extension will read a database file that is both compressed and encrypted.

  • The Test Harness #3 (TH3) is an alternative set of test vectors for SQLite that verify the operation of SQLite in an as-deployed configuration on embedded platforms with 100% branch test coverage.

Mailing Lists

Three separate mailing lists have been established to help support SQLite:

  • sqlite-announce - announcements of new releases or significant developments.
  • sqlite-users - general user discussion; most postings belong here.
  • sqlite-dev - developer conversations; for people who have or aspire to have write permission on the SQLite source code repository.

Most users of SQLite will want to join the sqlite-announce list and many will want to join the sqlite-users list. The sqlite-dev list is more specialized and appeals to a narrower audience. Off-site archives of the sqlite-users list are available at:

http://www.mail-archive.com/sqlite-users%40sqlite.org/
http://marc.info/?l=sqlite-users&r=1&w=2
http://news.gmane.org/gmane.comp.db.sqlite.general

Direct E-Mail To The Author

Use the mailing list. Please do not send email directly to the author of SQLite unless:

  • You have or intend to acquire a professional support contract as described above, or
  • You are working on an open source project.
You are welcomed to use SQLite in closed source, proprietary, and/or commercial projects and to ask questions about such use on the public mailing list. But please do not ask to receive free direct technical support. The software is free; direct technical support is not.


Syntax Diagrams For SQLite

sql-stmt-list:

References: sql-stmt

See also: lang.html

sql-stmt:

Used by: sql-stmt-list

References: alter-table-stmt analyze-stmt attach-stmt begin-stmt commit-stmt create-index-stmt create-table-stmt create-trigger-stmt create-view-stmt create-virtual-table-stmt delete-stmt delete-stmt-limited detach-stmt drop-index-stmt drop-table-stmt drop-trigger-stmt drop-view-stmt insert-stmt pragma-stmt reindex-stmt release-stmt rollback-stmt savepoint-stmt select-stmt update-stmt update-stmt-limited vacuum-stmt

See also: lang.html lang_explain.html

alter-table-stmt:

Used by: sql-stmt

References: column-def

See also: lang_altertable.html

analyze-stmt:

Used by: sql-stmt

See also: lang_analyze.html

attach-stmt:

Used by: sql-stmt

See also: lang_attach.html

begin-stmt:

Used by: sql-stmt

See also: lang_transaction.html

commit-stmt:

Used by: sql-stmt

See also: lang_transaction.html

rollback-stmt:

Used by: sql-stmt

See also: lang_savepoint.html lang_transaction.html

savepoint-stmt:

Used by: sql-stmt

See also: lang_savepoint.html

release-stmt:

Used by: sql-stmt

See also: lang_savepoint.html

create-index-stmt:

Used by: sql-stmt

References: indexed-column

See also: lang_createindex.html

indexed-column:

Used by: create-index-stmt table-constraint

See also: lang_createindex.html

create-table-stmt:

Used by: sql-stmt

References: column-def select-stmt table-constraint

See also: lang_createtable.html

column-def:

Used by: alter-table-stmt create-table-stmt

References: column-constraint type-name

See also: lang_altertable.html lang_createtable.html lang_createtable.html#tablecoldef

type-name:

Used by: column-def expr

References: signed-number

See also: lang_createtable.html

column-constraint:

Used by: column-def

References: conflict-clause expr foreign-key-clause literal-value signed-number

See also: lang_createtable.html lang_createtable.html#tablecoldef

signed-number:

Used by: column-constraint pragma-value type-name

See also: lang_expr.html

table-constraint:

Used by: create-table-stmt

References: conflict-clause expr foreign-key-clause indexed-column

See also: lang_createtable.html lang_createtable.html#constraints lang_createtable.html#tablecoldef

foreign-key-clause:

Used by: column-constraint table-constraint

See also: lang_altertable.html lang_createtable.html

conflict-clause:

Used by: column-constraint table-constraint

See also: lang_conflict.html lang_createtable.html#ckconst

create-trigger-stmt:

Used by: sql-stmt

References: delete-stmt expr insert-stmt select-stmt update-stmt

See also: lang_createtrigger.html

create-view-stmt:

Used by: sql-stmt

References: select-stmt

See also: lang_createview.html

create-virtual-table-stmt:

Used by: sql-stmt

See also: lang_createvtab.html

delete-stmt:

Used by: create-trigger-stmt sql-stmt

References: expr qualified-table-name

See also: lang_delete.html

delete-stmt-limited:

Used by: sql-stmt

References: expr ordering-term qualified-table-name

See also: lang_delete.html

detach-stmt:

Used by: sql-stmt

See also: lang_detach.html

drop-index-stmt:

Used by: sql-stmt

See also: lang_dropindex.html

drop-table-stmt:

Used by: sql-stmt

See also: lang_droptable.html

drop-trigger-stmt:

Used by: sql-stmt

See also: lang_droptrigger.html

drop-view-stmt:

Used by: sql-stmt

See also: lang_dropview.html

expr:

Used by: column-constraint create-trigger-stmt delete-stmt delete-stmt-limited insert-stmt join-constraint ordering-term result-column select-core table-constraint update-stmt update-stmt-limited

References: literal-value raise-function select-stmt type-name

See also: lang_expr.html

raise-function:

Used by: expr

See also: lang_createtrigger.html#undef_before lang_expr.html

literal-value:

Used by: column-constraint expr

See also: lang_expr.html

numeric-literal:

See also: lang_expr.html#litvalue

insert-stmt:

Used by: create-trigger-stmt sql-stmt

References: expr select-stmt

See also: lang_insert.html

pragma-stmt:

Used by: sql-stmt

References: pragma-value

See also: pragma.html#syntax

pragma-value:

Used by: pragma-stmt

References: signed-number

See also: pragma.html#syntax

reindex-stmt:

Used by: sql-stmt

See also: lang_reindex.html

select-stmt:

Used by: create-table-stmt create-trigger-stmt create-view-stmt expr insert-stmt single-source sql-stmt

References: compound-operator ordering-term select-core

See also: lang_select.html

select-core:

Used by: select-stmt

References: expr join-source ordering-term result-column

See also: lang_select.html

result-column:

Used by: select-core

References: expr

See also: lang_select.html

join-source:

Used by: select-core single-source

References: join-constraint join-op single-source

See also: lang_select.html

single-source:

Used by: join-source

References: join-source select-stmt

See also: lang_indexedby.html lang_select.html

join-op:

Used by: join-source

See also: lang_select.html lang_select.html#fromclause

join-constraint:

Used by: join-source

References: expr

See also: lang_select.html lang_select.html#fromclause

ordering-term:

Used by: delete-stmt-limited select-core select-stmt update-stmt-limited

References: expr

See also: lang_select.html

compound-operator:

Used by: select-stmt

See also: lang_select.html

update-stmt:

Used by: create-trigger-stmt sql-stmt

References: expr qualified-table-name

See also: lang_update.html

update-stmt-limited:

Used by: sql-stmt

References: expr ordering-term qualified-table-name

See also: lang_update.html

qualified-table-name:

Used by: delete-stmt delete-stmt-limited update-stmt update-stmt-limited

See also: lang_delete.html lang_indexedby.html lang_update.html

vacuum-stmt:

Used by: sql-stmt

See also: lang_vacuum.html

comment-syntax:

See also: lang_comment.html


The Tcl interface to the SQLite library

The SQLite library is designed to be very easy to use from a Tcl or Tcl/Tk script. SQLite began as a Tcl extension and the primary test suite for SQLite is written in TCL. SQLite can be used with any programming language, but its connections to TCL run deep.

This document gives an overview of the Tcl programming interface for SQLite.

The API

The interface to the SQLite library consists of single tcl command named sqlite3 Because there is only this one command, the interface is not placed in a separate namespace.

The sqlite3 command is used as follows:

sqlite3 dbcmd database-name

The sqlite3 command opens the database named in the second argument. If the database does not already exist, it is automatically created. The sqlite3 command also creates a new Tcl command to control the database. The name of the new Tcl command is given by the first argument. This approach is similar to the way widgets are created in Tk.

The name of the database is just the name of a disk file in which the database is stored. If the name of the database is the special name ":memory:" then a new database is created in memory. If the name of the database is an empty string, then the database is created in an empty file that is automatically deleted when the database connection closes.

Once an SQLite database is open, it can be controlled using methods of the dbcmd. There are currently 22 methods defined.

  • authorizer
  • backup
  • busy
  • cache
  • changes
  • close
  • collate
  • collation_needed
  • commit_hook
  • complete
  • copy
  • enable_load_extension
  • errorcode
  • eval
  • exists
  • function
  • incrblob
  • last_insert_rowid
  • nullvalue
  • onecolumn
  • profile
  • progress
  • restore
  • rollback_hook
  • status
  • timeout
  • total_changes
  • trace
  • transaction
  • unlock_notify
  • update_hook
  • version

The use of each of these methods will be explained in the sequel, though not in the order shown above.

The "eval" method

The most useful dbcmd method is "eval". The eval method is used to execute SQL on the database. The syntax of the eval method looks like this:

dbcmd eval sql ?array-name ? ?script?

The job of the eval method is to execute the SQL statement or statements given in the second argument. For example, to create a new table in a database, you can do this:

sqlite3 db1 ./testdb
db1 eval {CREATE TABLE t1(a int, b text)}

The above code creates a new table named t1 with columns a and b. What could be simpler?

Query results are returned as a list of column values. If a query requests 2 columns and there are 3 rows matching the query, then the returned list will contain 6 elements. For example:

db1 eval {INSERT INTO t1 VALUES(1,'hello')}
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
set x [db1 eval {SELECT * FROM t1 ORDER BY a}]

The variable $x is set by the above code to

1 hello 2 goodbye 3 howdy!

You can also process the results of a query one row at a time by specifying the name of an array variable and a script following the SQL code. For each row of the query result, the values of all columns will be inserted into the array variable and the script will be executed. For instance:

db1 eval {SELECT * FROM t1 ORDER BY a} values {
parray values
puts ""
}

This last code will give the following output:

values(*) = a b
values(a) = 1
values(b) = hello

values(*) = a b
values(a) = 2
values(b) = goodbye

values(*) = a b
values(a) = 3
values(b) = howdy!

For each column in a row of the result, the name of that column is used as an index in to array. The value of the column is stored in the corresponding array entry. The special array index * is used to store a list of column names in the order that they appear.

If the array variable name is omitted or is the empty string, then the value of each column is stored in a variable with the same name as the column itself. For example:

db1 eval {SELECT * FROM t1 ORDER BY a} {
puts "a=$a b=$b"
}

From this we get the following output

a=1 b=hello
a=2 b=goodbye
a=3 b=howdy!

Tcl variable names can appear in the SQL statement of the second argument in any position where it is legal to put a string or number literal. The value of the variable is substituted for the variable name. If the variable does not exist a NULL values is used. For example:

db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}

Note that it is not necessary to quote the $bigstring value. That happens automatically. If $bigstring is a large string or binary object, this technique is not only easier to write, it is also much more efficient since it avoids making a copy of the content of $bigstring.

If the $bigstring variable has both a string and a "bytearray" representation, then TCL inserts the value as a string. If it has only a "bytearray" representation, then the value is inserted as a BLOB. To force a value to be inserted as a BLOB even if it also has a text representation, us a "@" character to in place of the "$". Like this:

db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}

If the variable does not have a bytearray representation, then "@" works just like "$". Note that ":" works like "$" in all cases so the following is another way to express the same statement:

db1 eval {INSERT INTO t1 VALUES(5,:bigstring)}

The use of ":" instead of "$" before the name of a variable can sometimes be useful if the SQL text is enclosed in "..." instead of {...}. When the SQL is contained within "..." then TCL will do the substitution of $-variables, which can lead to SQL injection if extreme care is not used. But TCL will never substitute a :-variable regardless of whether "..." or {...} are used to enclose the SQL, so the use of :-variables adds an extra measure of defense against SQL injection.

The "close" method

As its name suggests, the "close" method to an SQLite database just closes the database. This has the side-effect of deleting the dbcmd Tcl command. Here is an example of opening and then immediately closing a database:

sqlite3 db1 ./testdb
db1 close

If you delete the dbcmd directly, that has the same effect as invoking the "close" method. So the following code is equivalent to the previous:

sqlite3 db1 ./testdb
rename db1 {}

The "transaction" method

The "transaction" method is used to execute a TCL script inside an SQLite database transaction. The transaction is committed when the script completes, or it rolls back if the script fails. If the transaction occurs within another transaction (even one that is started manually using BEGIN) it is a no-op.

The transaction command can be used to group together several SQLite commands in a safe way. You can always start transactions manually using BEGIN, of course. But if an error occurs so that the COMMIT or ROLLBACK are never run, then the database will remain locked indefinitely. Also, BEGIN does not nest, so you have to make sure no other transactions are active before starting a new one. The "transaction" method takes care of all of these details automatically.

The syntax looks like this:

dbcmd transaction ?transaction-type? SCRIPT,

The transaction-type can be one of deferred, exclusive or immediate. The default is deferred.

The "cache" method

The "eval" method described above keeps a cache of prepared statements for recently evaluated SQL commands. The "cache" method is used to control this cache. The first form of this command is:

dbcmd cache size N

This sets the maximum number of statements that can be cached. The upper limit is 100. The default is 10. If you set the cache size to 0, no caching is done.

The second form of the command is this:

dbcmd cache flush

The cache-flush method finalizes all prepared statements currently in the cache.

The "complete" method

The "complete" method takes a string of supposed SQL as its only argument. It returns TRUE if the string is a complete statement of SQL and FALSE if there is more to be entered.

The "complete" method is useful when building interactive applications in order to know when the user has finished entering a line of SQL code. This is really just an interface to the sqlite3_complete() C function.

The "copy" method

The "copy" method copies data from a file into a table. It returns the number of rows processed successfully from the file. The syntax of the copy method looks like this:

dbcmd copy conflict-algorithm table-name file-name ?column-separator ? ?null-indicator?

Conflict-algorithm must be one of the SQLite conflict algorithms for the INSERT statement: rollback, abort, fail,ignore, or replace. See the SQLite Language section for ON CONFLICT for more information. The conflict-algorithm must be specified in lower case.

Table-name must already exists as a table. File-name must exist, and each row must contain the same number of columns as defined in the table. If a line in the file contains more or less than the number of columns defined, the copy method rollbacks any inserts, and returns an error.

Column-separator is an optional column separator string. The default is the ASCII tab character \t.

Null-indicator is an optional string that indicates a column value is null. The default is an empty string. Note that column-separator and null-indicator are optional positional arguments; if null-indicator is specified, a column-separator argument must be specified and precede the null-indicator argument.

The copy method implements similar functionality to the .import SQLite shell command. The SQLite 2.x COPY statement (using the PostgreSQL COPY file format) can be implemented with this method as:

dbcmd copy $conflictalgo $tablename $filename \t \\N

The "timeout" method

The "timeout" method is used to control how long the SQLite library will wait for locks to clear before giving up on a database transaction. The default timeout is 0 millisecond. (In other words, the default behavior is not to wait at all.)

The SQLite database allows multiple simultaneous readers or a single writer but not both. If any process is writing to the database no other process is allows to read or write. If any process is reading the database other processes are allowed to read but not write. The entire database shared a single lock.

When SQLite tries to open a database and finds that it is locked, it can optionally delay for a short while and try to open the file again. This process repeats until the query times out and SQLite returns a failure. The timeout is adjustable. It is set to 0 by default so that if the database is locked, the SQL statement fails immediately. But you can use the "timeout" method to change the timeout value to a positive number. For example:

db1 timeout 2000

The argument to the timeout method is the maximum number of milliseconds to wait for the lock to clear. So in the example above, the maximum delay would be 2 seconds.

The "busy" method

The "busy" method, like "timeout", only comes into play when the database is locked. But the "busy" method gives the programmer much more control over what action to take. The "busy" method specifies a callback Tcl procedure that is invoked whenever SQLite tries to open a locked database. This callback can do whatever is desired. Presumably, the callback will do some other useful work for a short while (such as service GUI events) then return so that the lock can be tried again. The callback procedure should return "0" if it wants SQLite to try again to open the database and should return "1" if it wants SQLite to abandon the current operation.

The "enable_load_extension" method

The extension loading mechanism of SQLite (accessed using the load_extension() SQL function) is turned off by default. This is a security precaution. If an application wants to make use of the load_extension() function it must first turn the capability on using this method.

This method takes a single boolean argument which will turn the extension loading functionality on or off.

This method maps to the sqlite3_enable_load_extension() C/C++ interface.

The "exists" method

The "exists" method is similar to "onecolumn" and "eval" in that it executes SQL statements. The difference is that the "exists" method always returns a boolean value which is TRUE if a query in the SQL statement it executes returns one or more rows and FALSE if the SQL returns an empty set.

The "exists" method is often used to test for the existence of rows in a table. For example:

if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {
# Processing if $user exists
} else {
# Processing if $user does not exist
}

The "last_insert_rowid" method

The "last_insert_rowid" method returns an integer which is the ROWID of the most recently inserted database row.

The "function" method

The "function" method registers new SQL functions with the SQLite engine. The arguments are the name of the new SQL function and a TCL command that implements that function. Arguments to the function are appended to the TCL command before it is invoked.

The following example creates a new SQL function named "hex" that converts its numeric argument in to a hexadecimal encoded string:

db function hex {format 0x%X}

The "nullvalue" method

The "nullvalue" method changes the representation for NULL returned as result of the "eval" method.

db1 nullvalue NULL

The "nullvalue" method is useful to differ between NULL and empty column values as Tcl lacks a NULL representation. The default representation for NULL values is an empty string.

The "onecolumn" method

The "onecolumn" method works like "eval" in that it evaluates the SQL query statement given as its argument. The difference is that "onecolumn" returns a single element which is the first column of the first row of the query result.

This is a convenience method. It saves the user from having to do a "[lindex ... 0]" on the results of an "eval" in order to extract a single column result.

The "changes" method

The "changes" method returns an integer which is the number of rows in the database that were inserted, deleted, and/or modified by the most recent "eval" method.

The "total_changes" method

The "total_changes" method returns an integer which is the number of rows in the database that were inserted, deleted, and/or modified since the current database connection was first opened.

The "authorizer" method

The "authorizer" method provides access to the sqlite3_set_authorizer C/C++ interface. The argument to authorizer is the name of a procedure that is called when SQL statements are being compiled in order to authorize certain operations. The callback procedure takes 5 arguments which describe the operation being coded. If the callback returns the text string "SQLITE_OK", then the operation is allowed. If it returns "SQLITE_IGNORE", then the operation is silently disabled. If the return is "SQLITE_DENY" then the compilation fails with an error.

If the argument is an empty string then the authorizer is disabled. If the argument is omitted, then the current authorizer is returned.

The "progress" method

This method registers a callback that is invoked periodically during query processing. There are two arguments: the number of SQLite virtual machine opcodes between invocations, and the TCL command to invoke. Setting the progress callback to an empty string disables it.

The progress callback can be used to display the status of a lengthy query or to process GUI events during a lengthy query.

The "collate" method

This method registers new text collating sequences. There are two arguments: the name of the collating sequence and the name of a TCL procedure that implements a comparison function for the collating sequence.

For example, the following code implements a collating sequence called "NOCASE" that sorts in text order without regard to case:

proc nocase_compare {a b} {
return [string compare [string tolower $a] [string tolower $b]]
}
db collate NOCASE nocase_compare

The "collation_needed" method

This method registers a callback routine that is invoked when the SQLite engine needs a particular collating sequence but does not have that collating sequence registered. The callback can register the collating sequence. The callback is invoked with a single parameter which is the name of the needed collating sequence.

The "commit_hook" method

This method registers a callback routine that is invoked just before SQLite tries to commit changes to a database. If the callback throws an exception or returns a non-zero result, then the transaction rolls back rather than commit.

The "rollback_hook" method

This method registers a callback routine that is invoked just before SQLite tries to do a rollback. The script argument is run without change.

The "status" method

This method returns status information from the most recently evaluated SQL statement. The status method takes a single argument which should be either "steps" or "sorts". If the argument is "steps", then the method returns the number of full table scan steps that the previous SQL statement evaluated. If the argument is "sorts", the method returns the number of sort operations. This information can be used to detect queries that are not using indices to speed search or sorting.

The status method is basically a wrapper on the sqlite3_stmt_status() C-language interface.

The "update_hook" method

This method registers a callback routine that is invoked just before each row is modified by an UPDATE, INSERT, or DELETE statement. Four arguments are appended to the callback before it is invoked:

  • The keyword "INSERT", "UPDATE", or "DELETE", as appropriate
  • The name of the database which is being changed
  • The table that is being changed
  • The rowid of the row in the table being changed

The "incrblob" method

This method opens a TCL channel that can be used to read or write into a preexisting BLOB in the database. The syntax is like this:

dbcmd incrblob ?-readonly?? ?DB? TABLE COLUMN ROWID

The command returns a new TCL channel for reading or writing to the BLOB. The channel is opened using the underlying sqlite3_blob_open() C-language interface. Close the channel using the close command of TCL.

The "errorcode" method

This method returns the numeric error code that resulted from the most recent SQLite operation.

The "trace" method

The "trace" method registers a callback that is invoked as each SQL statement is compiled. The text of the SQL is appended as a single string to the command before it is invoked. This can be used (for example) to keep a log of all SQL operations that an application performs.

The "backup" method

The "backup" method makes a backup copy of a live database. The command syntax is like this:

dbcmd backup ?source-database? backup-filename

The optional source-database argument tells which database in the current connection should be backed up. The default value is main (or, in other words, the primary database file). To back up TEMP tables use temp. To backup an auxiliary database added to the connection using the ATTACH command, use the name of that database as it was assigned in the ATTACH command.

The backup-filename is the name of a file into which the backup is written. Backup-filename does not have to exist ahead of time, but if it does, it must be a well-formed SQLite database.

The "restore" method

The "restore" method copies the content a separate database file into the current database connection, overwriting any preexisting content. The command syntax is like this:

dbcmd restore ?target-database? source-filename

The optional target-database argument tells which database in the current connection should be overwritten with new content. The default value is main (or, in other words, the primary database file). To repopulate the TEMP tables use temp. To overwrite an auxiliary database added to the connection using the ATTACH command, use the name of that database as it was assigned in the ATTACH command.

The source-filename is the name of an existing well-formed SQLite database file from which the content is extracted.

The "version" method

Return the current library version. For example, "3.6.17".

The "profile" method

This method is used to profile the execution of SQL statements run by the application. The syntax is as follows:

dbcmd profile ?script

Unless script is an empty string, this method arranges for the script to be evaluated after the execution of each SQL statement. Two arguments are appended to script before it is invoked: the text of the SQL statement executed and the time elapsed while executing the statement, in nanoseconds.

A database handle may only have a single profile script registered at any time. If there is already a script registered when the profile method is invoked, the previous profile script is replaced by the new one. If the script argument is an empty string, any previously registered profile callback is canceled but no new profile script is registered.


Temporary Files Used By SQLite

Choose any three.
About Sitemap Documentation Download License News Support

SQLite's Use Of Temporary Disk Files

1.0 Introduction

On of the distinctive features of SQLite is that a database consists of a single disk file. This simplifies the use of SQLite since moving or backing up a database is a simple as copying a single file. It also makes SQLite appropriate for use as an application file format. But while a complete database is held in a single disk file, SQLite does make use of many temporary files during the course of processing a database.

This article describes the various temporary files that SQLite creates and uses. It describes when the files are created, when they are deleted, what they are used for, why they are important, and how to avoid them on systems where creating temporary files is expensive.

The manner in which SQLite uses temporary files is not considered part of the contract that SQLite makes with applications. The information in this document is a correct description of how SQLite operates at the time that this document was written or last updated. But there is no guarantee that future versions of SQLite will use temporary files in the same way. New kinds of temporary files might be employed and some of the current temporary file uses might be discontinued in future releases of SQLite.

2.0 Seven Kinds Of Temporary Files

SQLite currently uses seven distinct types of temporary files:

  1. Rollback journals
  2. Master journals
  3. Statement journals
  4. TEMP databases
  5. Materializations of views and subqueries
  6. Transient indices
  7. Transient databases used by VACUUM

Additional information about each of these temporary file types is in the sequel.

2.1 Rollback Journals

A rollback journal is a temporary file used to implement atomic commit and rollback capabilities in SQLite. (For a detailed discussion of how this works, see the separate document titled Atomic Commit In SQLite.) The rollback journal is always located in the same directory as the database file and has the same name as the database file except with the 8 characters "-journal" appended. The rollback journal is usually created when a transaction is first started and is usually deleted when a transaction commits or rolls back. The rollback journal file is essential for implementing the atomic commit and rollback capabilities of SQLite. Without a rollback journal, SQLite would be unable to rollback an incomplete transaction, and if a crash or power loss occurred in the middle of a transaction the entire database would likely go corrupt without a rollback journal.

The rollback journal is usually created and destroyed at the start and end of a transaction, respectively. But there are exceptions to this rule.

If a crash or power loss occurs in the middle of a transaction, then the rollback journal file is left on disk. The next time another application attempts to open the database file, it notices the presence of the abandoned rollback journal (we call it a "hot journal" in this circumstance) and uses the information in the journal to restore the database to its state prior to the start of the incomplete transaction. This is how SQLite implements atomic commit.

If an application puts SQLite in exclusive locking mode using the pragma:

PRAGMA locking_mode=EXCLUSIVE;

SQLite creates a new rollback journal at the start of the first transaction within an exclusive locking mode session. But at the conclusion of the transaction, it does not delete the rollback journal. The rollback journal might be truncated, or its header might be zeroed (depending on what version of SQLite you are using) but the rollback journal is not deleted. The rollback journal is not deleted until exclusive access mode is exited.

Rollback journal creation and deletion is also changed by the journal_mode pragma. The default journaling mode is DELETE, which is the default behavior of deleting the rollback journal file at the end of each transaction, as described above. The PERSIST journal mode foregoes the deletion of the journal file and instead overwrites the rollback journal header with zeros, which prevents other processes from rolling back the journal and thus has the same effect as deleting the journal file, though without the expense of actually removing the file from disk. In other words, journal mode PERSIST exhibits the same behavior as is seen in EXCLUSIVE locking mode. The OFF journal mode causes SQLite to forego creating a rollback journal in the first place. The OFF journal mode disables the atomic commit and rollback capabilities of SQLite. The ROLLBACK command is not available when OFF journal mode is set. And if a crash or power loss occurs in the middle of a transaction that uses the OFF journal mode, no recovery is possible and the database file will likely go corrupt.

2.2 Master Journal Files

The master journal file is used as part of the atomic commit process when a single transaction makes changes to multiple databases that have been added to a single database connection using the ATTACH statement. The master journal file is always located in the same directory as the main database file (the main database file is the database that is identified in the original sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() call that created the database connection) with a randomized suffix. The master journal file contains the names of all of the various attached auxiliary databases that were changed during the transaction. The multi-database transaction commits when the master journal file is deleted. See the documentation titled Atomic Commit In SQLite for additional detail.

The master journal file is only created in cases where a single database connection is talking with two or more databases files as a result of using ATTACH to connection to auxiliary databases, and where a single transaction modifies more than one of those database files. Without the master journal, the transaction commit on a multi-database transaction would be atomic for each database individually, but it would not be atomic across all databases. In other words, if the commit were interrupted in the middle by a crash or power loss, then the changes to one of the databases might complete while the changes to another database might roll back. The master journal causes all changes in all databases to either rollback or commit together.

2.3 Statement Journal Files

A statement journal file is used to rollback partial results of a single statement within a larger transaction. For example, suppose an UPDATE statement will attempt to modify 100 rows in the database. But after modifying the first 50 rows, the UPDATE hits a constraint violation which should block the entire statement. The statement journal is used to undo the first 50 row changes so that the database is restored to the state it was in at the start of the statement.

A statement journal is only created for an UPDATE or INSERT statement that might change multiple rows of a database and which might hit a constraint or a RAISE exception within a trigger and thus need to undo partial results. If the UPDATE or INSERT is not contained within BEGIN...COMMIT and if there are no other active statements on the same database connection then no statement journal is created since the ordinary rollback journal can be used instead. The statement journal is also omitted if an alternative conflict resolution algorithm is used. For example:

UPDATE OR FAIL ...
UPDATE OR IGNORE ...
UPDATE OR REPLACE ...
INSERT OR FAIL ...
INSERT OR IGNORE ...
INSERT OR REPLACE ...
REPLACE INTO ....

The statement journal is given a randomized name, not necessarily in the same directory as the main database, and is automatically deleted at the conclusion of the transaction. The size of the statement journal is proportional to the size of the change implemented by the UPDATE or INSERT statement that caused the statement journal to be created.

2.4 TEMP Databases

Tables created using the "CREATE TEMP TABLE" syntax are only visible to the database connection in which the "CREATE TEMP TABLE" statement is originally evaluated. These TEMP tables, together with any associated indices, triggers, and views, are collectively stored in a separate temporary database file that is created as soon as the first "CREATE TEMP TABLE" statement is seen. This separate temporary database file also has an associated rollback journal. The temporary database file used to store TEMP tables is deleted automatically when the database connection is closed using sqlite3_close().

The TEMP database file is very similar to auxiliary database files added using the ATTACH statement, though with a few special properties. The TEMP database is always automatically deleted when the database connection is closed. The TEMP database always uses the synchronous=OFF and journal_mode=PERSIST PRAGMA settings. And, the TEMP database cannot be used with DETACH nor can another process ATTACH the TEMP database.

The temporary files associated with the TEMP database and its rollback journal are only created if the application makes use of the "CREATE TEMP TABLE" statement.

2.5 Materializations Of Views And Subqueries

Queries that contain subqueries must sometime evaluate the subqueries separately and store the results in a temporary table, then use the content of the temporary table to evaluate the outer query. We call this "materializing" the subquery. The query optimizer in SQLite attempts to avoid materializing, but sometimes it is not easily avoidable. The temporary tables created by materialization are each stored in their own separate temporary file, which is automatically deleted at the conclusion of the query. The size of these temporary tables depends on the amount of data in the materialization of the subquery, of course.

A subquery on the right-hand side of IN operator must often be materialized. For example:

SELECT * FROM ex1 WHERE ex1.a IN (SELECT b FROM ex2);

In the query above, the subquery "SELECT b FROM ex2" is evaluated and its results are stored in a temporary table (actually a temporary index) that allows one to determine whether or not a value ex2.b exists using a simple binary search. Once this table is constructed, the outer query is run and for each prospective result row a check is made to see if ex1.a is contained within the temporary table. The row is output only if the check is true.

To avoid creating the temporary table, the query might be rewritten as follows:

SELECT * FROM ex1 WHERE EXISTS(SELECT 1 FROM ex2 WHERE ex2.b=ex1.a);

Recent versions of SQLite (version 3.5.4 and later) will do this rewrite automatically if an index exists on the column ex2.b.

If the right-hand side of an IN operator can be list of values as in the following:

SELECT * FROM ex1 WHERE a IN (1,2,3);

List values on the right-hand side of IN are treated as a subquery that must be materialized. In other words, the previous statement acts as if it were:

SELECT * FROM ex1 WHERE a IN (SELECT 1 UNION ALL
                              SELECT 2 UNION ALL
                              SELECT 3);

A temporary index is always used to hold the values of the right-hand side of an IN operator when that right-hand side is a list of values.

Subqueries might also need to be materialized when they appear in the FROM clause of a SELECT statement. For example:

SELECT * FROM ex1 JOIN (SELECT b FROM ex2) AS t ON t.b=ex1.a;

Depending on the query, SQLite might need to materialize the "(SELECT b FROM ex2)" subquery into a temporary table, then perform the join between ex1 and the temporary table. The query optimizer tries to avoid this by "flattening" the query. In the previous example the query can be flattened, and SQLite will automatically transform the query into

SELECT ex1.*, ex2.b FROM ex1 JOIN ex2 ON ex2.b=ex1.a;

More complex queries may or may not be able to employ query flattening to avoid the temporary table. Whether or not the query can be flattened depends on such factors as whether or not the subquery or outer query contain aggregate functions, ORDER BY or GROUP BY clauses, LIMIT clauses, and so forth. The rules for when a query and cannot be flattened are very complex and are beyond the scope of this document.

2.6 Transient Indices

SQLite may make use of transient indices to implement SQL language features such as:

  • An ORDER BY or GROUP BY clause
  • The DISTINCT keyword in an aggregate query
  • Compound SELECT statements joined by UNION, EXCEPT, or INTERSECT

Each transient index is stored in its own temporary file. The temporary file for a transient index is automatically deleted at the end of the statement that uses it.

SQLite strives to implement ORDER BY clauses using a preexisting index. If an appropriate index already exists, SQLite will walk the index, rather than the underlying table, to extract the requested information, and thus cause the rows to come out in the desired order. But if SQLite cannot find an appropriate index it will evaluate the query and store each row in a transient index whose data is the row data and whose key is the ORDER BY terms. After the query is evaluated, SQLite goes back and walks the transient index from beginning to end in order to output the rows in the desired order.

SQLite implements GROUP BY by ordering the output rows in the order suggested by the GROUP BY terms. Each output row is compared to the previous to see if it starts a new "group". The ordering by GROUP BY terms is done in exactly the same way as the ordering by ORDER BY terms. A preexisting index is used if possible, but if no suitable index is available, a transient index is created.

The previous two paragraphs describe the implementation of SQLite as of version 3.5.8. There are known problems with this approach for very large results sets - result sets that are larger than the available disk cache. Future versions of SQLite will likely address this deficiency by completely reworking the sort algorithm for cases when no suitable preexisting sort index is available. The new sort algorithm will also use temporary files, but not in the same way as the current implementation, the temporary files for the new implementation will probably not be index files.

The DISTINCT keyword on an aggregate query is implemented by creating a transient index in a temporary file and storing each result row in that index. As new result rows are computed a check is made to see if they already exist in the transient index and if they do the new result row is discarded.

The UNION operator for compound queries is implemented by creating a transient index in a temporary file and storing the results of the left and right subquery in the transient index, discarding duplicates. After both subqueries have been evaluated, the transient index is walked from beginning to end to generate the final output.

The EXCEPT operator for compound queries is implemented by creating a transient index in a temporary file, storing the results of the left subquery in this transient index, then removing the result from right subquery from the transient index, and finally walking the index from beginning to end to obtain the final output.

The INTERSECT operator for compound queries is implemented by creating two separate transient indices, each in a separate temporary file. The left and right subqueries are evaluated each into a separate transient index. Then the two indices are walked together and entries that appear in both indices are output.

Note that the UNION ALL operator for compound queries does not use transient indices by itself (though of course the right and left subqueries of the UNION ALL might use transient indices depending on how they are composed.)

2.7 Transient Database Used By VACUUM

The VACUUM command works by creating a temporary file and then rebuilding the entire database into that temporary file. Then the content of the temporary file is copied back into the original database file and the temporary file is deleted.

The temporary file created by the VACUUM command exists only for the duration of the command itself. The size of the temporary file will be no larger than the original database.

3.0 The SQLITE_TEMP_STORE Compile-Time Parameter and Pragma

The rollback journal, master journal, and statement journal files are always written to disk. But the other kinds of temporary files might be stored in memory only and never written to disk. Whether or not temporary files other than the rollback, master, and statement journals are written to disk or stored only in memory depends on the SQLITE_TEMP_STORE compile-time parameter, the temp_store pragma, and on the size of the temporary file.

The SQLITE_TEMP_STORE compile-time parameter is a #define whose value is an integer between 0 and 3, inclusive. The meaning of the SQLITE_TEMP_STORE compile-time parameter is as follows:

  1. Temporary files are always stored on disk regardless of the setting of the temp_store pragma.
  2. Temporary files are stored on disk by default but this can be overridden by the temp_store pragma.
  3. Temporary files are stored in memory by default but this can be overridden by the temp_store pragma.
  4. Temporary files are always stored in memory regardless of the setting of the temp_store pragma.

The default value of the SQLITE_TEMP_STORE compile-time parameter is 1, which means to store temporary files on disk but provide the option of overriding the behavior using the temp_store pragma.

The temp_store pragma has an integer value which also influences the decision of where to store temporary files. The values of the temp_store pragma have the following meanings:

  1. Use either disk or memory storage for temporary files as determined by the SQLITE_TEMP_STORE compile-time parameter.
  2. If the SQLITE_TEMP_STORE compile-time parameter specifies memory storage for temporary files, then override that decision and use disk storage instead. Otherwise follow the recommendation of the SQLITE_TEMP_STORE compile-time parameter.
  3. If the SQLITE_TEMP_STORE compile-time parameter specifies disk storage for temporary files, then override that decision and use memory storage instead. Otherwise follow the recommendation of the SQLITE_TEMP_STORE compile-time parameter.

The default setting for the temp_store pragma is 0, which means to following the recommendation of SQLITE_TEMP_STORE compile-time parameter.

To reiterate, the SQLITE_TEMP_STORE compile-time parameter and the temp_store pragma only influence the temporary files other than the rollback journal and the master journal. The rollback journal and the master journal are always written to disk regardless of the settings of the SQLITE_TEMP_STORE compile-time parameter and the temp_store pragma.

4.0 Other Temporary File Optimizations

SQLite uses a page cache of recently read and written database pages. This page cache is used not just for the main database file but also for transient indices and tables stored in temporary files. If SQLite needs to use a temporary index or table and the SQLITE_TEMP_STORE compile-time parameter and the temp_store pragma are set to store temporary tables and index on disk, the information is still initially stored in memory in the page cache. The temporary file is not opened and the information is not truly written to disk until the page cache is full.

This means that for many common cases where the temporary tables and indices are small (small enough to fit into the page cache) no temporary files are created and no disk I/O occurs. Only when the temporary data becomes too large to fit in RAM does the information spill to disk.

Each temporary table and index is given its own page cache which can store a maximum number of database pages determined by the SQLITE_DEFAULT_TEMP_CACHE_SIZE compile-time parameter. (The default value is 500 pages.) The maximum number of database pages in the page cache is the same for every temporary table and index. The value cannot be changed at run-time or on a per-table or per-index basis. Each temporary file gets its own private page cache with its own SQLITE_DEFAULT_TEMP_CACHE_SIZE page limit.


How SQLite Is Tested

1.0 Introduction

The reliability and robustness of SQLite is achieved in part by thorough and careful testing.

As of version 3.7.8 (all statistics in the report are against that release of SQLite), the SQLite library consists of approximately 77.6 KSLOC of C code. (KSLOC means thousands of "Source Lines Of Code" or, in other words, lines of code excluding blank lines and comments.) By comparison, the project has 1177 times as much test code and test scripts - 91392.4 KSLOC.

1.1 Executive Summary

  • Three independently developed test harnesses
  • 100% branch test coverage in an as-deployed configuration
  • Millions and millions of test cases
  • Out-of-memory tests
  • I/O error tests
  • Crash and power loss tests
  • Fuzz tests
  • Boundary value tests
  • Disabled optimization tests
  • Regression tests
  • Malformed database tests
  • Extensive use of assert() and run-time checks
  • Valgrind analysis
  • Signed-integer overflow checks

2.0 Test Harnesses

There are three independent test harnesses used for testing the core SQLite library. Each test harness is designed, maintained, and managed separately from the others.

  1. The TCL Tests are the oldest set of tests for SQLite. They are contained in the same source tree as the SQLite core and like the SQLite core are in the public domain. The TCL tests are the primary tests used during development. The TCL tests are written using the TCL scripting language. The TCL test harness itself consists of 21.6 KSLOC of C code used to create the TCL interface. The test scripts are contained in 661 files totaling 9.6MB in size. There are 28278 distinct test cases, but many of the test cases are parameterized and run multiple times (with different parameters) so that on a full test run, about 1.7 million separate tests are performed.

  2. The TH3 test harness is a set of proprietary tests, written in C that provide 100% branch test coverage (and 100% MC/DC test coverage) to the core SQLite library. The TH3 tests are designed to run on embedded and specialized platforms that would not easily support TCL or other workstation services. TH3 tests use only the published SQLite interfaces. TH3 is free to SQLite Consortium members and is available by license to others. TH3 consists of about 48.9 MB or 650.5 KSLOC of C code implementing 33595 distinct test cases. TH3 tests are heavily parameterized, though, so a full-coverage test runs about 0.8 million different test instances. The cases that provide 100% branch test coverage constitute a subset of the total TH3 test suite. A soak test prior to release does hundreds of millions of tests. Additional information on TH3 is available separately.

  3. The SQL Logic Test or SLT test harness is used to run huge numbers of SQL statements against both SQLite and several other SQL database engines and verify that they all get the same answers. SLT currently compares SQLite against PostgreSQL, MySQL, Microsoft SQL Server, and Oracle 10g. SLT runs 7.2 million queries comprising 1.12GB of test data.

All of the tests above must run successfully, on multiple platforms and under multiple compile-time configurations, before each release of SQLite.

Prior to each check-in to the SQLite source tree, developers typically run a subset (called "veryquick") of the Tcl tests consisting of about 132.2 thousand test cases. The veryquick tests include everything except the anomaly, fuzz, and soak tests. The idea behind the veryquick tests are that they are sufficient to catch most errors, but also run in only a few minutes instead of a few hours.

3.0 Anomaly Testing

Anomaly tests are tests designed to verify the correct behavior of SQLite when something goes wrong. It is (relatively) easy to build an SQL database engine that behaves correctly on well-formed inputs on a fully functional computer. It is more difficult to build a system that responds sanely to invalid inputs and continues to function following system malfunctions. The anomaly tests are designed to verify the latter behavior.

3.1 Out-Of-Memory Testing

SQLite, like all SQL database engines, makes extensive use of malloc() (See the separate report on dynamic memory allocation in SQLite for additional detail.) On servers and workstations, malloc() never fails in practice and so correct handling of out-of-memory (OOM) errors is not particularly important. But on embedded devices, OOM errors are frighteningly common and since SQLite is frequently used on embedded devices, it is important that SQLite be able to gracefully handle OOM errors.

OOM testing is accomplished by simulating OOM errors. SQLite allows an application to substitute an alternative malloc() implementation using the sqlite3_config(SQLITE_CONFIG_MALLOC,...) interface. The TCL and TH3 test harnesses are both capable of inserting a modified version of malloc() that can be rigged to fail after a certain number of allocations. These instrumented mallocs can be set to fail only once and then start working again, or to continue failing after the first failure. OOM tests are done in a loop. On the first iteration of the loop, the instrumented malloc is rigged to fail on the first allocation. Then some SQLite operation is carried out and checks are done to make sure SQLite handled the OOM error correctly. Then the time-to-failure counter on the instrumented malloc is increased by one and the test is repeated. The loop continues until the entire operation runs to completion without ever encountering a simulated OOM failure. Tests like this are run twice, once with the instrumented malloc set to fail only once, and again with the instrumented malloc set to fail continuously after the first failure.

3.2 I/O Error Testing

I/O error testing seeks to verify that SQLite responds sanely to failed I/O operations. I/O errors might result from a full disk drive, malfunctioning disk hardware, network outages when using a network file system, system configuration or permission changes that occur in the middle of an SQL operation, or other hardware or operating system malfunctions. Whatever the cause, it is important that SQLite be able to respond correctly to these errors and I/O error testing seeks to verify that it does.

I/O error testing is similar in concept to OOM testing; I/O errors are simulated and checks are made to verify that SQLite responds correctly to the simulated errors. I/O errors are simulated in both the TCL and TH3 test harnesses by inserting a new Virtual File System object that is specially rigged to simulate an I/O error after a set number of I/O operations. As with OOM error testing, the I/O error simulators can be set to fail just once, or to fail continuously after the first failure. Tests are run in a loop, slowly increasing the point of failure until the test case runs to completion without error. The loop is run twice, once with the I/O error simulator set to simulate only a single failure and a second time with it set to fail all I/O operations after the first failure.

In I/O error tests, after the I/O error simulation failure mechanism is disabled, the database is examined using PRAGMA integrity_check to make sure that the I/O error has not introduced database corruption.

3.3 Crash Testing

Crash testing seeks to demonstrate that an SQLite database will not go corrupt if the application or operating system crashes or if there is a power failure in the middle of a database update. A separate white-paper titled Atomic Commit in SQLite describes the defensive measure SQLite takes to prevent database corruption following a crash. Crash tests strive to verify that those defensive measures are working correctly.

It is impractical to do crash testing using real power failures, of course, and so crash testing is done in simulation. An alternative Virtual File System is inserted that allows the test harness to simulate the state of the database file following a crash.

In the TCL test harness, the crash simulation is done in a separate process. The main testing process spawns a child process which runs some SQLite operation and randomly crashes somewhere in the middle of a write operation. A special VFS randomly reorders and corrupts the unsynchronized write operations to simulate the effect of buffered filesystems. After the child dies, the original test process opens and reads the test database and verifies that the changes attempted by the child either completed successfully or else were completely rolled back. The integrity_check PRAGMA is used to make sure no database corruption occurs.

The TH3 test harness needs to run on embedded systems that do not necessarily have the ability to spawn child processes, so it uses an in-memory VFS to simulate crashes. The in-memory VFS can be rigged to make a snapshot of the entire filesystem after a set number of I/O operations. Crash tests run in a loop. On each iteration of the loop, the point at which a snapshot is made is advanced until the SQLite operations being tested run to completion without ever hitting a snapshot. Within the loop, after the SQLite operation under test has completed, the filesystem is reverted to the snapshot and random file damage is introduced that is characteristic of the kinds of damage one expects to see following a power loss. Then the database is opened and checks are made to ensure that it is well-formed and that the transaction either ran to completion or was completely rolled back. The interior of the loop is repeated multiple times for each snapshot with different random damage each time.

3.4 Compound failure tests

The test suites for SQLite also explore the result of stacking multiple failures. For example, tests are run to ensure correct behavior when an I/O error or OOM fault occurs while trying to recover from a prior crash.

4.0 Fuzz Testing

Fuzz testing seeks to establish that SQLite responds correctly to invalid, out-of-range, or malformed inputs.

4.1 SQL Fuzz

SQL fuzz testing consists of creating syntactically correct yet wildly nonsensical SQL statements and feeding them to SQLite to see what it will do with them. Usually some kind of error is returned (such as "no such table"). Sometimes, purely by chance, the SQL statement also happens to be semantically correct. In that case, the resulting prepared statement is run to make sure it gives a reasonable result.

The SQL fuzz generator tests are part of the TCL test suite. During a full test run, about 102.1 thousand fuzz SQL statements are generated and tested.

4.2 Malformed Database Files

There are numerous test cases that verify that SQLite is able to deal with malformed database files. These tests first build a well-formed database file, then add corruption by changing one or more bytes in the file by some means other than SQLite. Then SQLite is used to read the database. In some cases, the bytes changes are in the middle of data. This causes the content of the database to change while keeping the database well-formed. In other cases, unused bytes of the file are modified, which has no effect on the integrity of the database. The interesting cases are when bytes of the file that define database structure get changed. The malformed database tests verify that SQLite finds the file format errors and reports them using the SQLITE_CORRUPT return code without overflowing buffers, dereferencing NULL pointers, or performing other unwholesome actions.

4.3 Boundary Value Tests

SQLite defines certain limits on its operation, such as the maximum number of columns in a table, the maximum length of an SQL statement, or the maximum value of an integer. The TCL and TH3 test suites both contains numerous tests that push SQLite right to the edge of its defined limits and verify that it performs correctly for all allowed values. Additional tests go beyond the defined limits and verify that SQLite correctly returns errors. The source code contains testcase macros to verify that both sides of each boundary have been tested.

5.0 Regression Testing

Whenever a bug is reported against SQLite, that bug is not considered fixed until new test cases have been added to the TCL test suite which would exhibit the bug in an unpatched version of SQLite. Over the years, this has resulted in thousands and thousands of new tests being added to the TCL test suite. These regression tests ensure that bugs that have been fixed in the past are not reintroduced into future versions of SQLite.

6.0 Automatic Resource Leak Detection

Resource leak occurs when system resources are allocated and never freed. The most troublesome resource leaks in many applications are memory leaks - when memory is allocated using malloc() but never released using free(). But other kinds of resources can also be leaked: file descriptors, threads, mutexes, etc.

Both the TCL and TH3 test harnesses automatically track system resources and report resource leaks on every test run. No special configuration or setup is required. The test harnesses are especially vigilant with regard to memory leaks. If a change causes a memory leak, the test harnesses will recognize this quickly. SQLite is designed to never leak memory, even after an exception such as an OOM error or disk I/O error. The test harnesses are zealous to enforce this.

7.0 Test Coverage

The SQLite core has 100% branch test coverage under TH3 as of 2009-07-25, in its default configuration as measured by gcov utility on SuSE Linux 10.1 on x86 hardware with the GCC 4.0.1 compiler.

The "SQLite core" in the previous paragraph excludes the operating-system dependent VFS backends, since it is not possible to write cross-platform tests for those modules. Extensions such as FTS3 and RTree are also excluded from the analysis.

7.1 Statement versus branch coverage

There are many ways to measure test coverage. The most popular metric is "statement coverage". When you hear someone say that their program as "XX% test coverage" without further explanation, they usually mean statement coverage. Statement coverage measures what percentage of lines of code are executed at least once by the test suite.

Branch coverage is more rigorous than statement coverage. Branch coverage measures the number of machine-code branch instructions that are evaluated at least once on both directions.

To illustrate the difference between statement coverage and branch coverage, consider the following hypothetical line of C code:

if( a>b && c!=25 ){ d++; }

Such a line of C code might generate a dozen separate machine code instructions. If any one of those instructions is ever evaluated, then we say that the statement has been tested. So, for example, it might be the case that the conditional expression is always false and the "d" variable is never incremented. Even so, statement coverage counts this line of code as having been tested.

Branch coverage is more strict. With branch coverage, each test and each subblock within the statement is considered separately. In order to achieve 100% branch coverage in the example above, there must be at least three test cases:

  • a<=b
  • a>b && c==25
  • a>b && c!=25

Any one of the above test cases would provide 100% statement coverage but all three are required for 100% branch coverage. Generally speaking, 100% branch coverage implies 100% statement coverage, but the converse is not true. To reemphasize, the TH3 test harness for SQLite provides the stronger form of test coverage - 100% branch test coverage.

7.2 Coverage testing of defensive code

A well-written C program will typically contain some defensive tests which in practice are always true or always false. This leads to a programming dilemma: Does one remove defensive code in order to obtain 100% branch coverage?

In SQLite, the answer to the previous question is "no". For testing purposes, the SQLite source code defines macros called ALWAYS() and NEVER(). The ALWAYS() macro surrounds conditions which are expected to always evaluate as true and NEVER() surrounds conditions that are always evaluated to false. These macros serve as comments to indicate that the conditions are defensive code. For standard builds, these macros are pass-throughs:

#define ALWAYS(X)  (X)
#define NEVER(X)   (X)

During most testing, however, these macros will throw an assertion fault if their argument does not have the expected truth value. This alerts the developers quickly to incorrect design assumptions.

#define ALWAYS(X)  ((X)?1:assert(0),0)
#define NEVER(X)   ((X)?assert(0),1:0)

When measuring test coverage, these macros are defined to be constant truth values so that they do not generate assembly language branch instructions, and hence do not come into play when calculating the branch coverage:

#define ALWAYS(X)  (1)
#define NEVER(X)   (0)

The test suite is designed to be run three times, once for each of the ALWAYS() and NEVER() definitions shown above. All three test runs should yield exactly the same result. There is a run-time test using the sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, ...) interface that can be used to verify that the macros are correctly set to the first form (the pass-through form) for deployment.

7.3 Forcing coverage of boundary values and boolean vector tests

Another macro used in conjunction with test coverage measurement is the testcase() macro. The argument is a condition for which we want test cases that evaluate to both true and false. In non-coverage builds (that is to say, in release builds) the testcase() macro is a no-op:

#define testcase(X)

But in a coverage measuring build, the testcase() macro generates code that evaluates the conditional expression in its argument. Then during analysis, a check is made to ensure tests exist that evaluate the conditional to both true and false. Testcase() macros are used, for example, to help verify that boundary values are tested. For example:

testcase( a==b );
testcase( a==b+1 );
if( a>b && c!=25 ){ d++; }

Testcase macros are also used when two or more cases of a switch statement go to the same block of code, to make sure that the code was reached for all cases:

switch( op ){
  case OP_Add:
  case OP_Subtract: {
    testcase( op==OP_Add );
    testcase( op==OP_Subtract );
    /* ... */
    break;
  }
  /* ... */
}

For bitmask tests, testcase() macros are used to verify that every bit of the bitmask affects the test. For example, in the following block of code, the condition is true if the mask contains either of two bits indicating either a MAIN_DB or a TEMP_DB is being opened. The testcase() macros that precede the if statement verify that both cases are tested:

testcase( mask & SQLITE_OPEN_MAIN_DB );
testcase( mask & SQLITE_OPEN_TEMP_DB );
if( (mask & (SQLITE_OPEN_MAIN_DB|SQLITE_OPEN_TEMP_DB))!=0 ){ ... }

The SQLite source code contains 669 uses of the testcase() macro.

7.4 Branch coverage versus MC/DC

Two methods of measuring test coverage were described above: "statement" and "branch" coverage. There are many other test coverage metrics besides these two. Another popular metric is "Modified Condition/Decision Coverage" or MC/DC. Wikipedia defines MC/DC as follows:

  • Each decision tries every possible outcome.
  • Each condition in a decision takes on every possible outcome.
  • Each entry and exit point is invoked.
  • Each condition in a decision is shown to independently affect the outcome of the decision.

In the C programming language where && and || are "short-circuit" operators, MC/DC and branch coverage are very nearly the same thing. The primary difference is in boolean vector tests. One can test for any of several bits in bit-vector and still obtain 100% branch test coverage even though the second element of MC/DC - the requirement that each condition in a decision take on every possible outcome - might not be satisfied.

SQLite uses testcase() macros as described in the previous subsection to make sure that every condition in a bit-vector decision takes on every possible outcome. In this way, SQLite also achieves 100% MC/DC in addition to 100% branch coverage.

7.5 Experience with full test coverage

The developers of SQLite have found that full coverage testing is an extremely productive method for preventing the introduction of new bugs as the system evolves. Because every single branch instruction in SQLite core code is covered by test cases, the developers can be confident that changes they make in one part of the code do not have unintended consequences in other parts of the code. It would be extremely difficult maintain the quality of SQLite without such assurances.

8.0 Dynamic Analysis

Dynamic analysis refers to internal and external checks on the SQLite code which are performed while the code is live and running. Dynamic analysis has proven to be a great help in maintaining the quality of SQLite.

8.1 Assert

The SQLite core contains 3432 assert() statements that verify function preconditions and postconditions and loop invariants. Assert() is a macro which is a standard part of ANSI-C. The argument is a boolean value that is assumed to always be true. If the assertion is false, the program prints an error message and halts.

Assert() macros are disabled by compiling with the NDEBUG macro defined. In most systems, asserts are enabled by default. But in SQLite, the asserts are so numerous and are in such performance critical places, that the database engine runs about three times slower when asserts are enabled. Hence, the default (production) build of SQLite disables asserts. Assert statements are only enabled when SQLite is compiled with the SQLITE_DEBUG preprocessor macro defined.

8.2 Valgrind

Valgrind is perhaps the most amazing and useful developer tool in the world. Valgrind is a simulator - it simulates an x86 running a Linux binary. (Ports of Valgrind for platforms other than Linux are in development, but as of this writing, Valgrind only works reliably on Linux, which in the opinion of the SQLite developers means that Linux should be the preferred platform for all software development.) As Valgrind runs a Linux binary, it looks for all kinds of interesting errors such as array overruns, reading from uninitialized memory, stack overflows, memory leaks, and so forth. Valgrind finds problems that can easily slip through all of the other tests run against SQLite. And, when Valgrind does find an error, it can dump the developer directly into a symbolic debugger at the exact point where the error occur, to facilitate a quick fix.

Because it is a simulator, running a binary in Valgrind is slower than running it on native hardware. (To a first approximation, an application running in Valgrind on a workstation will perform about the same as it would running natively on a smartphone.) So it is impractical to run the full SQLite test suite through Valgrind. However, the veryquick tests and the coverage of the TH3 tests are run through Valgrind prior to every release.

8.3 Memsys2

SQLite contains a pluggable memory allocation subsystem. The default implementation uses system malloc() and free(). However, if SQLite is compiled with SQLITE_MEMDEBUG, an alternative memory allocation wrapper (memsys2) is inserted that looks for memory allocation errors at run-time. The memsys2 wrapper checks for memory leaks, of course, but also looks for buffer overruns, uses of uninitialized memory, and attempts to use memory after it has been freed. These same checks are also done by valgrind (and, indeed, Valgrind does them better) but memsys2 has the advantage of being much faster than Valgrind, which means the checks can be done more often and for longer tests.

8.4 Mutex Asserts

SQLite contains a pluggable mutex subsystem. Depending on compile-time options, the default mutex system contains interfaces sqlite3_mutex_held() and sqlite3_mutex_notheld() that detect whether or not a particular mutex is held by the calling thread. These two interfaces are used extensively within assert() statements in SQLite to verify mutexes are held and released at all the right moments, in order to double-check that SQLite does work correctly in multi-threaded applications.

8.5 Journal Tests

One of the things that SQLite does to ensure that transactions are atomic across system crashes and power failures is to write all changes into the rollback journal file prior to changing the database. The TCL test harness contains an alternative OS backend implementation that helps to verify this is occurring correctly. The "journal-test VFS" monitors all disk I/O traffic between the database file and rollback journal, checking to make sure that nothing is written into the database file which has not first been written and synced to the rollback journal. If any discrepancies are found, an assertion fault is raised.

The journal tests are an additional double-check over and above the crash tests to make sure that SQLite transactions will be atomic across system crashes and power failures.

8.6 Signed-Integer Overflow Checks

The various C language standards say that the signed-integer overflow behavior is undefined. In other words, when you add a value to a signed integer such that the result is too large to fit in that integer, the value does not necessarily wrap around to a negative number, as most programmers expect. It might do that. But it might do something completely different. See, for example, here and here. Even the same compiler might do something different with signed integer overflow in different places in the code or at different optimizations settings.

SQLite never overflows a signed integer. To verify this, the test suites are run at least once when compiled with the -ftrapv option to GCC. The -ftrapv option causes GCC to generate code that will panic() on a signed integer overflow. In addition, there are many test cases the strive to provoke integer overflows using boundary value calculations such as "SELECT -1*(-9223372036854775808);".

9.0 Disabled Optimization Tests

The sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS, ...) interface allows selected SQL statement optimizations to be disabled at run-time. SQLite should always generate exactly the same answer with optimizations enabled and with optimizations disabled; the answer simply arrives quicker with the optimizations turned on. So in a production environment, one always leaves the optimizations turned on (the default setting).

One verification technique used on SQLite is to run an entire test suite twice, once with optimizations left on and a second time with optimizations turned off, and verify that the same output is obtained both times. This shows that the optimizations do not introduce errors.

Not all test cases can be handled this way. Some test cases check to verify that the optimizations really are reducing the amount of computation by counting the number of disk accesses, sort operations, full-scan steps, or other processing steps that occur during queries. Those test cases will appear to fail when optimizations are disabled. But the majority of test cases simply check that the correct answer was obtained, and all of those cases can be run successfully with and without the optimizations, in order to show that the optimizations do not cause malfunctions.

10.0 Static Analysis

Static analysis means analyzing code at or before compile-time to check for correctness. Static analysis includes looking at compiler warning messages and running the code through more in-depth analysis engines such as the Clang Static Analyzer. SQLite is developed primarily using GCC and it does compile without warnings on GCC using the -Wall and -Wextra flags. The SQLite source code is also run through Clang from time to time as well, though most of the warnings there are false-positives. VC++ often will generate a number of warnings from SQLite source code, but the experience of SQLite developers is that VC++ warnings are of lower quality and can be safely ignored. Users are encouraged not to stress over VC++ warnings.

Static analysis has not proven to be helpful in finding bugs in SQLite. We cannot call to mind a single problem in SQLite that was detected by static analysis that was not first seen by one of the other testing methods described above. On the other hand, we have on occasion introduced new bugs in our efforts to get SQLite to compile without warnings.

Our experience, then, is that static analysis is not helpful to maintaining high code quality and it is therefore deemphasized in SQLite development and maintenance.

11.0 Summary

SQLite is open source. This gives many people the idea that it is not well tested as commercial software and is perhaps unreliable. But that impression is false. SQLite has exhibited very high reliability in the field and a very low defect rate, especially considering how rapidly it is evolving. The quality of SQLite is achieved in part by careful code design and implementation. But extensive testing also plays a vital role in maintaining and improving the quality of SQLite. This document has summarized the testing procedures that every release of SQLite undergoes with the hopes of inspiring the reader to understand that SQLite is suitable for use in mission-critical applications.


SQLite TH3

Choose any three.
About Sitemap Documentation Download License News Support

TH3: SQLite Test Harness #3

1.0 Overview

SQLite Test Harness #3 (hereafter "TH3") is one of three test harnesses used for testing SQLite. TH3 is designed to meet the following objectives:

  • TH3 runs on embedded platforms that lack the support infrastructure of workstations.

  • TH3 tests SQLite in an as-deployed configuration using only published and documented interfaces. In other words, TH3 tests the compiled object code, not the source code, thus verifying that no problems were introduced by compiler bugs.

  • TH3 checks SQLite's response to out-of-memory errors, disk I/O errors, and power loss during transaction commit.

  • TH3 exercises SQLite in a variety of run-time configurations (UTF8 vs UTF16, different pages sizes, varying journal modes, etc.)

  • TH3 achieves 100% branch test coverage over SQLite core. (Test coverage of the operating-system specific VFSes and extensions such as FTS and RTREE is less than 100%).

TH3 was originally written for validation testing only, but has subsequently been used for development testing and debugging as well, and has proven very helpful in those roles. A full-coverage test run for TH3 takes less than 10 minutes on a workstation and hence serves as a fast but effect regression test during day-to-day maintenance of the SQLite code base.

2.0 Operation

TH3 is a test program generator. The output of TH3 is a program written in ANSI-C and intended to be linked against the SQLite library under test. The generated test program is compiled and run on the target platform in order to verify correct operation of SQLite on that platform.

The inputs to TH3 are test modules written in C or SQL and small configuration files that determine how to initialize SQLite. The TH3 package includes hundreds of test modules and dozens of configuration files. New modules and configurations can be added to customize TH3 for specialized applications. Each time TH3 is run, it reads a subset of the available test modules and configuration files to generate a custom C program that performs all of the specified tests under all configurations. A complete test of SQLite normally involves running TH3 multiple times to generate multiple test programs covering different aspects of SQLite's operation, then linking all test programs against a common SQLite library and running them separately on the target platform. SQLite will be found to work if all test programs pass.

There are no arbitrary limits in TH3. One could generate a single test program that contained all test modules and configuration files. However, such a test program might be too large to deploy on embedded platforms. Hence, TH3 provides the ability to break the library of test modules up into smaller, more easily digested pieces.

Each individual test module might contain dozens, hundreds, or thousands of separate tests. The test modules can be written in C or as scripts of SQL. Test modules done in SQL are very easy to write and the test modules written in C are not as nearly as cumbersome to write as one might suppose. The TH3 system provides high-level interfaces that simplify test writing. A typical C-language test case in TH3 might contains slightly more syntax that the corresponding TCL-script test, but the difference is not that great. The test modules written as SQL contain special comments that define the boundaries and operation of each test case and the expected results.

Each test module file contains a header which describes the circumstances under which the test is valid. For a particular configuration, only those modules that are compatible with the configuration are run.

3.0 Generating A Test Program

The TH3 program generator is a TCL script named "mkth3.tcl". To generate a test program, one has merely to run this script and supply the names of files containing test modules and configurations on the command line. TH3 does not force any specific names for test modules or configuration files, but it is customary to use suffixes ".test" and ".cfg". With these conventions, one might generate a test program as follows:

tclsh mkth3.tcl *.test *.cfg >testprog1.c

The output from the mkth3.tcl script is a C program that contains everything needed to run the tests - everything that is except for the SQLite library itself. The generated test program contains implementations for all of the support interfaces used by the test modules and it contains the main() routine that drives the tests. To convert the test program into a working executable, simply compile it against SQLite:

cc -o testprog1 testprog1.c sqlite3.c

The compilation step shown immediately above is merely representative. In a working installation, one would normally want to specify optimization parameters and compile-time switches on the compiler command line.

Once the test program is generated, it is run with no arguments to perform the tests. Progress information as well as error diagnostics appear on standard output. The program returns zero if there are no errors and non-zero if any problems were detected.

4.0 Test Coverage

Using one particular subset of the available TH3 test modules (the "cov1" tests) SQLite obtained 100% branch test coverage and 100% MC/DC as measured by gcov on SuSE Linux 10.1 on x86 hardware on 2009-07-25. The SQLite developers are committed to maintaining 100% branch coverage and MC/DC for all future releases of SQLite.

The cov1 test set used to obtain 100% branch test coverage are only a subset of the tests currently implemented using TH3. New test modules are added on a regular basis.

5.0 TH3 License

SQLite itself is in the public domain and can be used for any purpose. But TH3 is proprietary and requires a license. Members of the SQLite Consortium get free and unlimited access to TH3. Others can contact the SQLite developers for information on how to obtain a license to access and use TH3.

Licensees of TH3 are given read access to the software configuration management system used to manage TH3 and so can download the latest version of TH3 (or any historical version) whenever they like.

Even though open-source users do not have direct access to TH3, all users of SQLite benefit from TH3 indirectly since each version of SQLite is validated by TH3 prior to release. So anyone using an official release of SQLite can deploy their application with the confidence of knowing that it has been tested using TH3. They simply cannot rerun those tests themselves without purchasing a TH3 license.


Using SQLite In Multi-Threaded Applications

Choose any three.
About Sitemap Documentation Download License News Support

SQLite And Multiple Threads

SQLite support three different threading modes:

  1. Single-thread. In this mode, all mutexes are disabled and SQLite is unsafe to use in more than a single thread at once.

  2. Multi-thread. In this mode, SQLite can be safely used by multiple threads provided that no single database connection is used simultaneously in two or more threads.

  3. Serialized. In serialized mode, SQLite can be safely used by multiple threads with no restriction.

The threading mode can be selected at compile-time (when the SQLite library is being compiled from source code) or at start-time (when the application that intends to use SQLite is initializing) or at run-time (when a new SQLite database connection is being created). Generally speaking, run-time overrides start-time and start-time overrides compile-time. Except, single-thread mode cannot be overridden once selected.

The default mode is serialized.

Compile-time selection of threading mode

Use the SQLITE_THREADSAFE compile-time parameter to selected the threading mode. If no SQLITE_THREADSAFE compile-time parameter is present, then serialized mode is used. This can be made explicit with -DSQLITE_THREADSAFE=1. With -DSQLITE_THREADSAFE=0 the threading mode is single-thread. With -DSQLITE_THREADSAFE=2 the threading mode is multi-thread.

The return value of the sqlite3_threadsafe() interface is determined by the compile-time threading mode selection. If single-thread mode is selected at compile-time, then sqlite3_threadsafe() returns false. If either the multi-thread or serialized modes are selected, then sqlite3_threadsafe() returns true. The sqlite3_threadsafe() interface predates the multi-thread mode and start-time and run-time mode selection and so is unable to distinguish between multi-thread and serialized mode nor is it able to report start-time or run-time mode changes.

If single-thread mode is selected at compile-time, then critical mutexing logic is omitted from the build and it is impossible to enable either multi-thread or serialized modes at start-time or run-time.

Start-time selection of threading mode

Assuming that the compile-time threading mode is not single-thread, then the threading mode can be changed during initialization using the sqlite3_config() interface. The SQLITE_CONFIG_SINGLETHREAD verb puts SQLite into single-thread mode, the SQLITE_CONFIG_MULTITHREAD verb sets multi-thread mode, and the SQLITE_CONFIG_SERIALIZED verb sets serialized mode.

Run-time selection of threading mode

If single-thread mode has not been selected at compile-time or start-time, then individual database connections can be created as either multi-thread or serialized. It is not possible to downgrade an individual database connection to single-thread mode. Nor is it possible to escalate an individual database connection if the compile-time or start-time mode is single-thread.

The threading mode for an individual database connection is determined by flags given as the third argument to sqlite3_open_v2(). The SQLITE_OPEN_NOMUTEX flag causes the database connection to be in the multi-thread mode and the SQLITE_OPEN_FULLMUTEX flag causes the connection to be in serialized mode. If neither flag is specified or if sqlite3_open() or sqlite3_open16() are used instead of sqlite3_open_v2(), then the default mode determined by the compile-time and start-time settings is used.


SQLite is Transactional

A transactional database is one in which all changes and queries appear to be Atomic, Consistent, Isolated, and Durable (ACID). SQLite implements serializable transactions that are atomic, consistent, isolated, and durable, even if the transaction is interrupted by a program crash, an operating system crash, or a power failure to the computer.

We here restate and amplify the previous sentence for emphasis: All changes within a single transaction in SQLite either occur completely or not at all, even if the act of writing the change out to the disk is interrupted by

  • a program crash,
  • an operating system crash, or
  • a power failure.

The claim of the previous paragraph is extensively checked in the SQLite regression test suite using a special test harness that simulates the effects on a database file of operating system crashes and power failures.

Additional informaton


SQLite Unlock-Notify API

Choose any three.
About Sitemap Documentation Download License News Support

Using the sqlite3_unlock_notify() API

/* This example uses the pthreads API */
#include <pthread.h>

/*
** A pointer to an instance of this structure is passed as the user-context
** pointer when registering for an unlock-notify callback.
*/
typedef struct UnlockNotification UnlockNotification;
struct UnlockNotification {
  int fired;                         /* True after unlock event has occurred */
  pthread_cond_t cond;               /* Condition variable to wait on */
  pthread_mutex_t mutex;             /* Mutex to protect structure */
};

/*
** This function is an unlock-notify callback registered with SQLite.
*/
static void unlock_notify_cb(void **apArg, int nArg){
  int i;
  for(i=0; i<nArg; i++){
    UnlockNotification *p = (UnlockNotification *)apArg[i];
    pthread_mutex_lock(&p->mutex);
    p->fired = 1;
    pthread_cond_signal(&p->cond);
    pthread_mutex_unlock(&p->mutex);
  }
}

/*
** This function assumes that an SQLite API call (either sqlite3_prepare_v2()
** or sqlite3_step()) has just returned SQLITE_LOCKED. The argument is the
** associated database connection.
**
** This function calls sqlite3_unlock_notify() to register for an
** unlock-notify callback, then blocks until that callback is delivered
** and returns SQLITE_OK. The caller should then retry the failed operation.
**
** Or, if sqlite3_unlock_notify() indicates that to block would deadlock
** the system, then this function returns SQLITE_LOCKED immediately. In
** this case the caller should not retry the operation and should roll
** back the current transaction (if any).
*/
static int wait_for_unlock_notify(sqlite3 *db){
  int rc;
  UnlockNotification un;

  /* Initialize the UnlockNotification structure. */
  un.fired = 0;
  pthread_mutex_init(&un.mutex, 0);
  pthread_cond_init(&un.cond, 0);

  /* Register for an unlock-notify callback. */
  rc = sqlite3_unlock_notify(db, unlock_notify_cb, (void *)&un);
  assert( rc==SQLITE_LOCKED || rc==SQLITE_OK );

  /* The call to sqlite3_unlock_notify() always returns either SQLITE_LOCKED
  ** or SQLITE_OK.
  **
  ** If SQLITE_LOCKED was returned, then the system is deadlocked. In this
  ** case this function needs to return SQLITE_LOCKED to the caller so
  ** that the current transaction can be rolled back. Otherwise, block
  ** until the unlock-notify callback is invoked, then return SQLITE_OK.
  */
  if( rc==SQLITE_OK ){
    pthread_mutex_lock(&un.mutex);
    if( !un.fired ){
      pthread_cond_wait(&un.cond, &un.mutex);
    }
    pthread_mutex_unlock(&un.mutex);
  }

  /* Destroy the mutex and condition variables. */
  pthread_cond_destroy(&un.cond);
  pthread_mutex_destroy(&un.mutex);

  return rc;
}

/*
** This function is a wrapper around the SQLite function sqlite3_step().
** It functions in the same way as step(), except that if a required
** shared-cache lock cannot be obtained, this function may block waiting for
** the lock to become available. In this scenario the normal API step()
** function always returns SQLITE_LOCKED.
**
** If this function returns SQLITE_LOCKED, the caller should rollback
** the current transaction (if any) and try again later. Otherwise, the
** system may become deadlocked.
*/
int sqlite3_blocking_step(sqlite3_stmt *pStmt){
  int rc;
  while( SQLITE_LOCKED==(rc = sqlite3_step(pStmt)) ){
    rc = wait_for_unlock_notify(sqlite3_db_handle(pStmt));
    if( rc!=SQLITE_OK ) break;
    sqlite3_reset(pStmt);
  }
  return rc;
}

/*
** This function is a wrapper around the SQLite function sqlite3_prepare_v2().
** It functions in the same way as prepare_v2(), except that if a required
** shared-cache lock cannot be obtained, this function may block waiting for
** the lock to become available. In this scenario the normal API prepare_v2()
** function always returns SQLITE_LOCKED.
**
** If this function returns SQLITE_LOCKED, the caller should rollback
** the current transaction (if any) and try again later. Otherwise, the
** system may become deadlocked.
*/
int sqlite3_blocking_prepare_v2(
  sqlite3 *db,              /* Database handle. */
  const char *zSql,         /* UTF-8 encoded SQL statement. */
  int nSql,                 /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
  const char **pz           /* OUT: End of parsed string */
){
  int rc;
  while( SQLITE_LOCKED==(rc = sqlite3_prepare_v2(db, zSql, nSql, ppStmt, pz)) ){
    rc = wait_for_unlock_notify(db);
    if( rc!=SQLITE_OK ) break;
  }
  return rc;
}

When two or more connections access the same database in shared-cache mode, read and write (shared and exclusive) locks on individual tables are used to ensure that concurrently executing transactions are kept isolated. Before writing to a table, a write (exclusive) lock must be obtained on that table. Before reading, a read (shared) lock must be obtained. A connection releases all held table locks when it concludes its transaction. If a connection cannot obtain a required lock, then the call to sqlite3_step() returns SQLITE_LOCKED.

Although it is less common, a call to sqlite3_prepare() or sqlite3_prepare_v2() may also return SQLITE_LOCKED if it cannot obtain a read-lock on the sqlite_master table of each attached database. These APIs need to read the schema data contained in the sqlite_master table in order to compile SQL statements to sqlite3_stmt* objects.

This article presents a technique using the SQLite sqlite3_unlock_notify() interface such that calls to sqlite3_step() and sqlite3_prepare_v2() block until the required locks are available instead of returning SQLITE_LOCKED immediately. If the sqlite3_blocking_step() or sqlite3_blocking_prepare_v2() functions presented to the left return SQLITE_LOCKED, this indicates that to block would deadlock the system.

The sqlite3_unlock_notify() API, which is only available if the library is compiled with the pre-processor symbol SQLITE_ENABLE_UNLOCK_NOTIFY defined, is documented here. This article is not a substitute for reading the full API documentation!

The sqlite3_unlock_notify() interface is designed for use in systems that have a separate thread assigned to each database connection. There is nothing in the implementation that prevents a single thread from running multiple database connections. However, the sqlite3_unlock_notify() interface only works on a single connection at a time, so the lock resolution logic presented here will only work for a single database connection per thread.

The sqlite3_unlock_notify() API

After a call to sqlite3_step() or sqlite3_prepare_v2() returns SQLITE_LOCKED, the sqlite3_unlock_notify() API may be invoked to register for an unlock-notify callback. The unlock-notify callback is invoked by SQLite after the database connection holding the table-lock that prevented the call to sqlite3_step() or sqlite3_prepare_v2() from succeeding has finished its transaction and released all locks. For example, if a call to sqlite3_step() is an attempt to read from table X, and some other connection Y is holding a write-lock on table X, then sqlite3_step() will return SQLITE_LOCKED. If sqlite3_unlock_notify() is then called, the unlock-notify callback will be invoked after connection Y's transaction is concluded. The connection that the unlock-notify callback is waiting on, in this case connection Y, is known as the "blocking connection".

If a call to sqlite3_step() that attempts to write to a database table returns SQLITE_LOCKED, then more than one other connection may be holding a read-lock on the database table in question. In this case SQLite simply selects one of those other connections arbitrarily and issues the unlock-notify callback when that connection's transaction is finished. Whether the call to sqlite3_step() was blocked by one or many connections, when the corresponding unlock-notify callback is issued it is not guaranteed that the required lock is available, only that it may be.

When the unlock-notify callback is issued, it is issued from within a call to sqlite3_step() (or sqlite3_close()) associated with the blocking connection. It is illegal to invoke any sqlite3_XXX() API functions from within an unlock-notify callback. The expected use is that the unlock-notify callback will signal some other waiting thread or schedule some action to take place later.

The algorithm used by the sqlite3_blocking_step() function is as follows:

  1. Call sqlite3_step() on the supplied statement handle. If the call returns anything other than SQLITE_LOCKED, then return this value to the caller. Otherwise, continue.

  2. Invoke sqlite3_unlock_notify() on the database connection handle associated with the supplied statement handle to register for an unlock-notify callback. If the call to unlock_notify() returns SQLITE_LOCKED, then return this value to the caller.

  3. Block until the unlock-notify callback is invoked by another thread.

  4. Call sqlite3_reset() on the statement handle. Since an SQLITE_LOCKED error may only occur on the first call to sqlite3_step() (it is not possible for one call to sqlite3_step() to return SQLITE_ROW and then the next SQLITE_LOCKED), the statement handle may be reset at this point without affecting the results of the query from the point of view of the caller. If sqlite3_reset() were not called at this point, the next call to sqlite3_step() would return SQLITE_MISUSE.

  5. Return to step 1.

The algorithm used by the sqlite3_blocking_prepare_v2() function is similar, except that step 4 (resetting the statement handle) is omitted.

Writer Starvation

Multiple connections may hold a read-lock simultaneously. If many threads are acquiring overlapping read-locks, it might be the case that at least one thread is always holding a read lock. Then a table waiting for a write-lock will wait forever. This scenario is called "writer starvation."

SQLite helps applications avoid writer starvation. After any attempt to obtain a write-lock on a table fails (because one or more other connections are holding read-locks), all attempts to open new transactions on the shared-cache fail until one of the following is true:

  • The current writer concludes its transaction, OR
  • The number of open read-transactions on the shared-cache drops to zero.

Failed attempts to open new read-transactions return SQLITE_LOCKED to the caller. If the caller then calls sqlite3_unlock_notify() to register for an unlock-notify callback, the blocking connection is the connection that currently has an open write-transaction on the shared-cache. This prevents writer-starvation since if no new read-transactions may be opened and assuming all existing read-transactions are eventually concluded, the writer will eventually have an opportunity to obtain the required write-lock.

The pthreads API

By the time sqlite3_unlock_notify() is invoked by wait_for_unlock_notify(), it is possible that the blocking connection that prevented the sqlite3_step() or sqlite3_prepare_v2() call from succeeding has already finished its transaction. In this case, the unlock-notify callback is invoked immediately, before sqlite3_unlock_notify() returns. Or, it is possible that the unlock-notify callback is invoked by a second thread after sqlite3_unlock_notify() is called but before the thread starts waiting to be asynchronously signaled.

Exactly how such a potential race-condition is handled depends on the threads and synchronization primitives interface used by the application. This example uses pthreads, the interface provided by modern UNIX-like systems, including Linux.

The pthreads interface provides the pthread_cond_wait() function. This function allows the caller to simultaneously release a mutex and start waiting for an asynchronous signal. Using this function, a "fired" flag and a mutex, the race-condition described above may be eliminated as follows:

When the unlock-notify callback is invoked, which may be before the thread that called sqlite3_unlock_notify() begins waiting for the asynchronous signal, it does the following:

  1. Obtains the mutex.
  2. Sets the "fired" flag to true.
  3. Attempts to signal a waiting thread.
  4. Releases the mutex.

When the wait_for_unlock_notify() thread is ready to begin waiting for the unlock-notify callback to arrive, it:

  1. Obtains the mutex.
  2. Checks if the "fired" flag has been set. If so, the unlock-notify callback has already been invoked. Release the mutex and continue.
  3. aAtomically releases the mutex and begins waiting for the asynchronous signal. When the signal arrives, continue.

This way, it doesn't matter if the unlock-notify callback has already been invoked, or is being invoked, when the wait_for_unlock_notify() thread begins blocking.

Possible Enhancements

The code in this article could be improved in at least two ways:

  • It could manage thread priorities.
  • It could handle a special case of SQLITE_LOCKED that can occur when dropping a table or index.

Even though the sqlite3_unlock_notify() function only allows the caller to specify a single user-context pointer, an unlock-notify callback is passed an array of such context pointers. This is because if when a blocking connection concludes its transaction, if there is more than one unlock-notify registered to call the same C function, the context-pointers are marshaled into an array and a single callback issued. If each thread were assigned a priority, then instead of just signaling the threads in arbitrary order as this implementation does, higher priority threads could be signaled before lower priority threads.

If a "DROP TABLE" or "DROP INDEX" SQL command is executed, and the same database connection currently has one or more actively executing SELECT statements, then SQLITE_LOCKED is returned. If sqlite3_unlock_notify() is called in this case, then the specified callback will be invoked immediately. Re-attempting the "DROP TABLE" or "DROP INDEX" statement will return another SQLITE_LOCKED error. In the implementation of sqlite3_blocking_step() shown to the left, this could cause an infinite loop.

The caller could distinguish between this special "DROP TABLE|INDEX" case and other cases by using extended error codes. When it is appropriate to call sqlite3_unlock_notify(), the extended error code is SQLITE_LOCKED_SHAREDCACHE. Otherwise, in the "DROP TABLE|INDEX" case, it is just plain SQLITE_LOCKED. Another solution might be to limit the number of times that any single query could be reattempted (to say 100). Although this might be less efficient than one might wish, the situation in question is not likely to occur often.


Uniform Resource Identifiers

Choose any three.
About Sitemap Documentation Download License News Support

1.0 URI Filenames In SQLite

Beginning with version 3.7.7, the SQLite database file argument to the sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces and to the ATTACH command can be specified either as an ordinary filename or as a Uniform Resource Identifier or URI. The advantage of using a URI filename is that query parameters on the URI can be used to control details of the newly created database connection. For example, an alternative VFS can be specified using a "vfs=" query parameter. Or the database can be opened read-only by using "mode=ro" as a query parameter.

2.0 Backwards Compatibility

In order to maintain full backwards compatibility for legacy applications, the URI filename capability is disabled by default. In order for URI filenames to work, one or more of the following must be true:

  1. The SQLite library is compiled with the SQLITE_USE_URI compile-time option.

  2. The sqlite3_config(SQLITE_CONFIG_URI, 1); configuration option is set at application start-time.

  3. The SQLITE_OPEN_URI bit is OR-ed in with the set bits passed in as the 3rd parameter to the sqlite3_open_v2() interface.

If URI filenames are recognized when the database connection is originally opened, then URI filenames will also be recognized on ATTACH statements. Similarly, if URI filenames are not recognized when the database connection is first opened, they will not be recognized by ATTACH.

Since SQLite always interprets any filename that does not begins with "file:" as an ordinary filename regardless of the URI setting, and because it is very unusual to have an actual file begin with "file:", it is safe for most applications to enable URI processing even if URI filenames are not currently being used.

3.0 URI Format

According to RFC 3986, a URI consists of a scheme, an authority, a path, a query string, and a fragment. The scheme is always required. One of either the authority or the path is also always required. The query string and fragment are optional.

SQLite uses the "file:" URI syntax to identify database files. SQLite strives to interpret file: URIs in exactly the same way as popular web-browsers such as Firefox, Chrome, Safari, Internet Explorer, and Opera, and command-line programs such as Windows "start" and the Mac OS-X "open" command. A succinct summary of the URI parsing rules follows:

  • The scheme of the URI must be "file:". Any other scheme results in the input being treated as an ordinary filename.
  • The authority may be omitted, may be blank, or may be "localhost". Any other authority results in an error.
  • The path is optional if the authority is present. If the authority is omitted then the path is required.
  • The query string is optional. If the query string is present, then all query parameters are passed through into the xOpen method of the underlying VFS.
  • The fragment is optional. If present, it is ignored.

Zero or more escape sequences of the form "%HH" (where H represents any hexadecimal digit) can occur in the path, query string, or fragment.

A filename that is not a well-formed URI is interpreted as an ordinary filename.

URIs are processed as UTF8 text. The filename argument sqlite3_open16() is converted from UTF16 native byte order into UTF8 prior to processing.

3.1 The URI Path

The path component of the URI specifies the disk file that is the SQLite database to be opened. If the path component is omitted, then the database is stored in a temporary file that will be automatically deleted when the database connection closes. If the authority section is present, then the path is always an absolute pathname. If the authority section is omitted, then the path is an absolute pathname if it begins with the "/" character (ASCII code 0x2f) and is a relative pathname otherwise. On windows, if the absolute path begins with "/X:/" where X is any single ASCII alphabetic character ("a" through "z" or "A" through "Z") then the "X:" is understood to be the drive letter of the volume containing the file, not the toplevel directory.

An ordinary filename can usually be converted into an equivalent URI by the steps shown below. The one exception is that a relative windows pathname with a drive letter cannot be converted directly into a URI; it must be changed into an absolute pathname first.

  1. Convert all "?" characters into "%3f".
  2. Convert all "#" characters into "%23".
  3. On windows only, convert all "\" characters into "/".
  4. Convert all sequences of two or more "/" characters into a single "/" character.
  5. On windows only, if the filename begins with a drive letter, prepend a single "/" character.
  6. Prepend the "file:" scheme.

3.2 Query String

A URI filename can optionally be followed by a query string. The query string consists of text following the first "?" character but excluding the optional fragment that begins with with "#". The query string is divided into key/value pairs. We usually refer to these key/value pairs as "query parameters". Key/value pairs are separated by a single "&" character. The key comes first and is separated from the value by a single "=" character. Both key and value may contain %HH escape sequences.

The text of query parameters is appended to the filename argument of the xOpen method of the VFS. Any %HH escape sequences in the query parameters are resolved prior to being appended to the xOpen filename. A single zero-byte separates the xOpen filename argument from the key of the first query parameters, each key and value, and each subsequent key from the prior value. The list of query parameters parameters appended to the xOpen filename is terminated by a single zero-length key. Note that the value of a query parameter can be an empty string.

3.3 Recognized Query Parameters

Some query parameters are interpreted by the SQLite core and used to modify the characteristics of the new connection. All query parameters are always passed through into the xOpen method of the VFS even if they are previously read and interpreted by the SQLite core.

The following query parameters are recognized by SQLite as of version 3.7.7. Other query parameters might be added to this set in future releases.

vfs=NAME

This query parameter causes the database connection to be opened using the VFS called NAME. The open attempt fails if NAME is not the name of a VFS that is built into SQLite or that has been previously registered using sqlite3_vfs_register().

mode=ro
mode=rw
mode=rwc

These query parameters determine if the new database is opened read-only, read-write, or read-write and created if it does not exist, respectively.

cache=shared
cache=private

These query parameters determine if the new database is opened using shared cache mode or with a private cache, respectively.

4.0 See Also

  • URI filenames in sqlite3_open()
  • URI filename examples


The Virtual Database Engine of SQLite

This document describes the virtual machine used in SQLite version 2.8.0. The virtual machine in SQLite version 3.0 and 3.1 is very similar in concept but many of the opcodes have changed and the algorithms are somewhat different. Use this document as a rough guide to the idea behind the virtual machine in SQLite version 3, not as a reference on how the virtual machine works.

If you want to know how the SQLite library works internally, you need to begin with a solid understanding of the Virtual Database Engine or VDBE. The VDBE occurs right in the middle of the processing stream (see the architecture diagram) and so it seems to touch most parts of the library. Even parts of the code that do not directly interact with the VDBE are usually in a supporting role. The VDBE really is the heart of SQLite.

This article is a brief introduction to how the VDBE works and in particular how the various VDBE instructions (documented here) work together to do useful things with the database. The style is tutorial, beginning with simple tasks and working toward solving more complex problems. Along the way we will visit most submodules in the SQLite library. After completing this tutorial, you should have a pretty good understanding of how SQLite works and will be ready to begin studying the actual source code.

Preliminaries

The VDBE implements a virtual computer that runs a program in its virtual machine language. The goal of each program is to interrogate or change the database. Toward this end, the machine language that the VDBE implements is specifically designed to search, read, and modify databases.

Each instruction of the VDBE language contains an opcode and three operands labeled P1, P2, and P3. Operand P1 is an arbitrary integer. P2 is a non-negative integer. P3 is a pointer to a data structure or null-terminated string, possibly null. Only a few VDBE instructions use all three operands. Many instructions use only one or two operands. A significant number of instructions use no operands at all but instead take their data and store their results on the execution stack. The details of what each instruction does and which operands it uses are described in the separate opcode description document.

A VDBE program begins execution on instruction 0 and continues with successive instructions until it either (1) encounters a fatal error, (2) executes a Halt instruction, or (3) advances the program counter past the last instruction of the program. When the VDBE completes execution, all open database cursors are closed, all memory is freed, and everything is popped from the stack. So there are never any worries about memory leaks or undeallocated resources.

If you have done any assembly language programming or have worked with any kind of abstract machine before, all of these details should be familiar to you. So let's jump right in and start looking as some code.

Inserting Records Into The Database

We begin with a problem that can be solved using a VDBE program that is only a few instructions long. Suppose we have an SQL table that was created like this:

CREATE TABLE examp(one text, two int);

In words, we have a database table named "examp" that has two columns of data named "one" and "two". Now suppose we want to insert a single record into this table. Like this:

INSERT INTO examp VALUES('Hello, World!',99);

We can see the VDBE program that SQLite uses to implement this INSERT using the sqlite command-line utility. First start up sqlite on a new, empty database, then create the table. Next change the output format of sqlite to a form that is designed to work with VDBE program dumps by entering the ".explain" command. Finally, enter the [INSERT] statement shown above, but precede the [INSERT] with the special keyword [EXPLAIN]. The [EXPLAIN] keyword will cause sqlite to print the VDBE program rather than execute it. We have:

$ sqlite test_database_1
sqlite> CREATE TABLE examp(one text, two int);
sqlite> .explain
sqlite> EXPLAIN INSERT INTO examp VALUES('Hello, World!',99);
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     Transaction   0      0
1     VerifyCookie  0      81
2     Transaction   1      0
3     Integer       0      0
4     OpenWrite     0      3      examp
5     NewRecno      0      0
6     String        0      0      Hello, World!
7     Integer       99     0      99
8     MakeRecord    2      0
9     PutIntKey     0      1
10    Close         0      0
11    Commit        0      0
12    Halt          0      0

As you can see above, our simple insert statement is implemented in 12 instructions. The first 3 and last 2 instructions are a standard prologue and epilogue, so the real work is done in the middle 7 instructions. There are no jumps, so the program executes once through from top to bottom. Let's now look at each instruction in detail.

0     Transaction   0      0
1     VerifyCookie  0      81
2     Transaction   1      0

The instruction Transaction begins a transaction. The transaction ends when a Commit or Rollback opcode is encountered. P1 is the index of the database file on which the transaction is started. Index 0 is the main database file. A write lock is obtained on the database file when a transaction is started. No other process can read or write the file while the transaction is underway. Starting a transaction also creates a rollback journal. A transaction must be started before any changes can be made to the database.

The instruction VerifyCookie checks cookie 0 (the database schema version) to make sure it is equal to P2 (the value obtained when the database schema was last read). P1 is the database number (0 for the main database). This is done to make sure the database schema hasn't been changed by another thread, in which case it has to be reread.

The second Transaction instruction begins a transaction and starts a rollback journal for database 1, the database used for temporary tables.

3     Integer       0      0
4     OpenWrite     0      3      examp

The instruction Integer pushes the integer value P1 (0) onto the stack. Here 0 is the number of the database to use in the following OpenWrite instruction. If P3 is not NULL then it is a string representation of the same integer. Afterwards the stack looks like this:

(integer) 0

The instruction OpenWrite opens a new read/write cursor with handle P1 (0 in this case) on table "examp", whose root page is P2 (3, in this database file). Cursor handles can be any non-negative integer. But the VDBE allocates cursors in an array with the size of the array being one more than the largest cursor. So to conserve memory, it is best to use handles beginning with zero and working upward consecutively. Here P3 ("examp") is the name of the table being opened, but this is unused, and only generated to make the code easier to read. This instruction pops the database number to use (0, the main database) from the top of the stack, so afterwards the stack is empty again.

5     NewRecno      0      0

The instruction NewRecno creates a new integer record number for the table pointed to by cursor P1. The record number is one not currently used as a key in the table. The new record number is pushed onto the stack. Afterwards the stack looks like this:

(integer) new record key
6     String        0      0      Hello, World!

The instruction String pushes its P3 operand onto the stack. Afterwards the stack looks like this:

(string) "Hello, World!"
(integer) new record key
7     Integer       99     0      99

The instruction Integer pushes its P1 operand (99) onto the stack. Afterwards the stack looks like this:

(integer) 99
(string) "Hello, World!"
(integer) new record key
8     MakeRecord    2      0

The instruction MakeRecord pops the top P1 elements off the stack (2 in this case) and converts them into the binary format used for storing records in a database file. (See the file format description for details.) The new record generated by the MakeRecord instruction is pushed back onto the stack. Afterwards the stack looks like this:

(record) "Hello, World!", 99
(integer) new record key
9     PutIntKey     0      1

The instruction PutIntKey uses the top 2 stack entries to write an entry into the table pointed to by cursor P1. A new entry is created if it doesn't already exist or the data for an existing entry is overwritten. The record data is the top stack entry, and the key is the next entry down. The stack is popped twice by this instruction. Because operand P2 is 1 the row change count is incremented and the rowid is stored for subsequent return by the sqlite_last_insert_rowid() function. If P2 is 0 the row change count is unmodified. This instruction is where the insert actually occurs.

10    Close         0      0

The instruction Close closes a cursor previously opened as P1 (0, the only open cursor). If P1 is not currently open, this instruction is a no-op.

11    Commit        0      0

The instruction Commit causes all modifications to the database that have been made since the last Transaction to actually take effect. No additional modifications are allowed until another transaction is started. The Commit instruction deletes the journal file and releases the write lock on the database. A read lock continues to be held if there are still cursors open.

12    Halt          0      0

The instruction Halt causes the VDBE engine to exit immediately. All open cursors, Lists, Sorts, etc are closed automatically. P1 is the result code returned by sqlite_exec(). For a normal halt, this should be SQLITE_OK (0). For errors, it can be some other value. The operand P2 is only used when there is an error. There is an implied "Halt 0 0 0" instruction at the end of every program, which the VDBE appends when it prepares a program to run.

Tracing VDBE Program Execution

If the SQLite library is compiled without the NDEBUG preprocessor macro, then the PRAGMA vdbe_trace causes the VDBE to trace the execution of programs. Though this feature was originally intended for testing and debugging, it can also be useful in learning about how the VDBE operates. Use "PRAGMA vdbe_trace=ON;" to turn tracing on and "PRAGMA vdbe_trace=OFF" to turn tracing back off. Like this:

sqlite> PRAGMA vdbe_trace=ON;
   0 Halt            0    0
sqlite> INSERT INTO examp VALUES('Hello, World!',99);
   0 Transaction     0    0
   1 VerifyCookie    0   81
   2 Transaction     1    0
   3 Integer         0    0
Stack: i:0
   4 OpenWrite       0    3 examp
   5 NewRecno        0    0
Stack: i:2
   6 String          0    0 Hello, World!
Stack: t[Hello,.World!] i:2
   7 Integer        99    0 99
Stack: si:99 t[Hello,.World!] i:2
   8 MakeRecord      2    0
Stack: s[...Hello,.World!.99] i:2
   9 PutIntKey       0    1
  10 Close           0    0
  11 Commit          0    0
  12 Halt            0    0

With tracing mode on, the VDBE prints each instruction prior to executing it. After the instruction is executed, the top few entries in the stack are displayed. The stack display is omitted if the stack is empty.

On the stack display, most entries are shown with a prefix that tells the datatype of that stack entry. Integers begin with "i:". Floating point values begin with "r:". (The "r" stands for "real-number".) Strings begin with either "s:", "t:", "e:" or "z:". The difference among the string prefixes is caused by how their memory is allocated. The z: strings are stored in memory obtained from malloc(). The t: strings are statically allocated. The e: strings are ephemeral. All other strings have the s: prefix. This doesn't make any difference to you, the observer, but it is vitally important to the VDBE since the z: strings need to be passed to free() when they are popped to avoid a memory leak. Note that only the first 10 characters of string values are displayed and that binary values (such as the result of the MakeRecord instruction) are treated as strings. The only other datatype that can be stored on the VDBE stack is a NULL, which is display without prefix as simply "NULL". If an integer has been placed on the stack as both an integer and a string, its prefix is "si:".

Simple Queries

At this point, you should understand the basics of how the VDBE writes to a database. Now let's look at how it does queries. We will use the following simple SELECT statement as our example:

SELECT * FROM examp;

The VDBE program generated for this SQL statement is as follows:

sqlite> EXPLAIN SELECT * FROM examp;
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      one
1     ColumnName    1      0      two
2     Integer       0      0
3     OpenRead      0      3      examp
4     VerifyCookie  0      81
5     Rewind        0      10
6     Column        0      0
7     Column        0      1
8     Callback      2      0
9     Next          0      6
10    Close         0      0
11    Halt          0      0

Before we begin looking at this problem, let's briefly review how queries work in SQLite so that we will know what we are trying to accomplish. For each row in the result of a query, SQLite will invoke a callback function with the following prototype:

int Callback(void *pUserData, int nColumn, char *azData[], char *azColumnName[]);

The SQLite library supplies the VDBE with a pointer to the callback function and the pUserData pointer. (Both the callback and the user data were originally passed in as arguments to the sqlite_exec() API function.) The job of the VDBE is to come up with values for nColumn, azData[], and azColumnName[]. nColumn is the number of columns in the results, of course. azColumnName[] is an array of strings where each string is the name of one of the result columns. azData[] is an array of strings holding the actual data.

0     ColumnName    0      0      one
1     ColumnName    1      0      two

The first two instructions in the VDBE program for our query are concerned with setting up values for azColumn. The ColumnName instructions tell the VDBE what values to fill in for each element of the azColumnName[] array. Every query will begin with one ColumnName instruction for each column in the result, and there will be a matching Column instruction for each one later in the query.

2     Integer       0      0
3     OpenRead      0      3      examp
4     VerifyCookie  0      81

Instructions 2 and 3 open a read cursor on the database table that is to be queried. This works the same as the OpenWrite instruction in the INSERT example except that the cursor is opened for reading this time instead of for writing. Instruction 4 verifies the database schema as in the INSERT example.

5     Rewind        0      10

The Rewind instruction initializes a loop that iterates over the "examp" table. It rewinds the cursor P1 to the first entry in its table. This is required by the Column and Next instructions, which use the cursor to iterate through the table. If the table is empty, then jump to P2 (10), which is the instruction just past the loop. If the table is not empty, fall through to the following instruction at 6, which is the beginning of the loop body.

6     Column        0      0
7     Column        0      1
8     Callback      2      0

The instructions 6 through 8 form the body of the loop that will execute once for each record in the database file. The Column instructions at addresses 6 and 7 each take the P2-th column from the P1-th cursor and push it onto the stack. In this example, the first Column instruction is pushing the value for the column "one" onto the stack and the second Column instruction is pushing the value for column "two". The Callback instruction at address 8 invokes the callback() function. The P1 operand to Callback becomes the value for nColumn. The Callback instruction pops P1 values from the stack and uses them to fill the azData[] array.

9     Next          0      6

The instruction at address 9 implements the branching part of the loop. Together with the Rewind at address 5 it forms the loop logic. This is a key concept that you should pay close attention to. The Next instruction advances the cursor P1 to the next record. If the cursor advance was successful, then jump immediately to P2 (6, the beginning of the loop body). If the cursor was at the end, then fall through to the following instruction, which ends the loop.

10    Close         0      0
11    Halt          0      0

The Close instruction at the end of the program closes the cursor that points into the table "examp". It is not really necessary to call Close here since all cursors will be automatically closed by the VDBE when the program halts. But we needed an instruction for the Rewind to jump to so we might as well go ahead and have that instruction do something useful. The Halt instruction ends the VDBE program.

Note that the program for this SELECT query didn't contain the Transaction and Commit instructions used in the INSERT example. Because the SELECT is a read operation that doesn't alter the database, it doesn't require a transaction.

A Slightly More Complex Query

The key points of the previous example were the use of the Callback instruction to invoke the callback function, and the use of the Next instruction to implement a loop over all records of the database file. This example attempts to drive home those ideas by demonstrating a slightly more complex query that involves more columns of output, some of which are computed values, and a WHERE clause that limits which records actually make it to the callback function. Consider this query:

SELECT one, two, one || two AS 'both'
FROM examp
WHERE one LIKE 'H%'

This query is perhaps a bit contrived, but it does serve to illustrate our points. The result will have three column with names "one", "two", and "both". The first two columns are direct copies of the two columns in the table and the third result column is a string formed by concatenating the first and second columns of the table. Finally, the WHERE clause says that we will only chose rows for the results where the "one" column begins with an "H". Here is what the VDBE program looks like for this query:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      one
1     ColumnName    1      0      two
2     ColumnName    2      0      both
3     Integer       0      0
4     OpenRead      0      3      examp
5     VerifyCookie  0      81
6     Rewind        0      18
7     String        0      0      H%
8     Column        0      0
9     Function      2      0      ptr(0x7f1ac0)
10    IfNot         1      17
11    Column        0      0
12    Column        0      1
13    Column        0      0
14    Column        0      1
15    Concat        2      0
16    Callback      3      0
17    Next          0      7
18    Close         0      0
19    Halt          0      0

Except for the WHERE clause, the structure of the program for this example is very much like the prior example, just with an extra column. There are now 3 columns, instead of 2 as before, and there are three ColumnName instructions. A cursor is opened using the OpenRead instruction, just like in the prior example. The Rewind instruction at address 6 and the Next at address 17 form a loop over all records of the table. The Close instruction at the end is there to give the Rewind instruction something to jump to when it is done. All of this is just like in the first query demonstration.

The Callback instruction in this example has to generate data for three result columns instead of two, but is otherwise the same as in the first query. When the Callback instruction is invoked, the left-most column of the result should be the lowest in the stack and the right-most result column should be the top of the stack. We can see the stack being set up this way at addresses 11 through 15. The Column instructions at 11 and 12 push the values for the first two columns in the result. The two Column instructions at 13 and 14 pull in the values needed to compute the third result column and the Concat instruction at 15 joins them together into a single entry on the stack.

The only thing that is really new about the current example is the WHERE clause which is implemented by instructions at addresses 7 through 10. Instructions at address 7 and 8 push onto the stack the value of the "one" column from the table and the literal string "H%". The Function instruction at address 9 pops these two values from the stack and pushes the result of the LIKE() function back onto the stack. The IfNot instruction pops the top stack value and causes an immediate jump forward to the Next instruction if the top value was false (not not like the literal string "H%"). Taking this jump effectively skips the callback, which is the whole point of the WHERE clause. If the result of the comparison is true, the jump is not taken and control falls through to the Callback instruction below.

Notice how the LIKE operator is implemented. It is a user-defined function in SQLite, so the address of its function definition is specified in P3. The operand P1 is the number of function arguments for it to take from the stack. In this case the LIKE() function takes 2 arguments. The arguments are taken off the stack in reverse order (right-to-left), so the pattern to match is the top stack element, and the next element is the data to compare. The return value is pushed onto the stack.

A Template For SELECT Programs

The first two query examples illustrate a kind of template that every SELECT program will follow. Basically, we have:

  1. Initialize the azColumnName[] array for the callback.
  2. Open a cursor into the table to be queried.
  3. For each record in the table, do:
    1. If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.
    2. Compute all columns for the current row of the result.
    3. Invoke the callback function for the current row of the result.
  4. Close the cursor.

This template will be expanded considerably as we consider additional complications such as joins, compound selects, using indices to speed the search, sorting, and aggregate functions with and without GROUP BY and HAVING clauses. But the same basic ideas will continue to apply.

UPDATE And DELETE Statements

The UPDATE and DELETE statements are coded using a template that is very similar to the SELECT statement template. The main difference, of course, is that the end action is to modify the database rather than invoke a callback function. Because it modifies the database it will also use transactions. Let's begin by looking at a DELETE statement:

DELETE FROM examp WHERE two<50;

This DELETE statement will remove every record from the "examp" table where the "two" column is less than 50. The code generated to do this is as follows:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     Transaction   1      0
1     Transaction   0      0
2     VerifyCookie  0      178
3     Integer       0      0
4     OpenRead      0      3      examp
5     Rewind        0      12
6     Column        0      1
7     Integer       50     0      50
8     Ge            1      11
9     Recno         0      0
10    ListWrite     0      0
11    Next          0      6
12    Close         0      0
13    ListRewind    0      0
14    Integer       0      0
15    OpenWrite     0      3
16    ListRead      0      20
17    NotExists     0      19
18    Delete        0      1
19    Goto          0      16
20    ListReset     0      0
21    Close         0      0
22    Commit        0      0
23    Halt          0      0

Here is what the program must do. First it has to locate all of the records in the table "examp" that are to be deleted. This is done using a loop very much like the loop used in the SELECT examples above. Once all records have been located, then we can go back through and delete them one by one. Note that we cannot delete each record as soon as we find it. We have to locate all records first, then go back and delete them. This is because the SQLite database backend might change the scan order after a delete operation. And if the scan order changes in the middle of the scan, some records might be visited more than once and other records might not be visited at all.

So the implementation of DELETE is really in two loops. The first loop (instructions 5 through 11) locates the records that are to be deleted and saves their keys onto a temporary list, and the second loop (instructions 16 through 19) uses the key list to delete the records one by one.

0     Transaction   1      0
1     Transaction   0      0
2     VerifyCookie  0      178
3     Integer       0      0
4     OpenRead      0      3      examp

Instructions 0 though 4 are as in the INSERT example. They start transactions for the main and temporary databases, verify the database schema for the main database, and open a read cursor on the table "examp". Notice that the cursor is opened for reading, not writing. At this stage of the program we are only going to be scanning the table, not changing it. We will reopen the same table for writing later, at instruction 15.

5     Rewind        0      12

As in the SELECT example, the Rewind instruction rewinds the cursor to the beginning of the table, readying it for use in the loop body.

6     Column        0      1
7     Integer       50     0      50
8     Ge            1      11

The WHERE clause is implemented by instructions 6 through 8. The job of the where clause is to skip the ListWrite if the WHERE condition is false. To this end, it jumps ahead to the Next instruction if the "two" column (extracted by the Column instruction) is greater than or equal to 50.

As before, the Column instruction uses cursor P1 and pushes the data record in column P2 (1, column "two") onto the stack. The Integer instruction pushes the value 50 onto the top of the stack. After these two instructions the stack looks like:

(integer) 50
(record) current record for column "two"

The Ge operator compares the top two elements on the stack, pops them, and then branches based on the result of the comparison. If the second element is >= the top element, then jump to address P2 (the Next instruction at the end of the loop). Because P1 is true, if either operand is NULL (and thus the result is NULL) then take the jump. If we don't jump, just advance to the next instruction.

9     Recno         0      0
10    ListWrite     0      0

The Recno instruction pushes onto the stack an integer which is the first 4 bytes of the key to the current entry in a sequential scan of the table pointed to by cursor P1. The ListWrite instruction writes the integer on the top of the stack into a temporary storage list and pops the top element. This is the important work of this loop, to store the keys of the records to be deleted so we can delete them in the second loop. After this ListWrite instruction the stack is empty again.

11    Next          0      6
12    Close         0      0

The Next instruction increments the cursor to point to the next element in the table pointed to by cursor P0, and if it was successful branches to P2 (6, the beginning of the loop body). The Close instruction closes cursor P1. It doesn't affect the temporary storage list because it isn't associated with cursor P1; it is instead a global working list (which can be saved with ListPush).

13    ListRewind    0      0

The ListRewind instruction rewinds the temporary storage list to the beginning. This prepares it for use in the second loop.

14    Integer       0      0
15    OpenWrite     0      3

As in the INSERT example, we push the database number P1 (0, the main database) onto the stack and use OpenWrite to open the cursor P1 on table P2 (base page 3, "examp") for modification.

16    ListRead      0      20
17    NotExists     0      19
18    Delete        0      1
19    Goto          0      16

This loop does the actual deleting. It is organized differently from the one in the UPDATE example. The ListRead instruction plays the role that the Next did in the INSERT loop, but because it jumps to P2 on failure, and Next jumps on success, we put it at the start of the loop instead of the end. This means that we have to put a Goto at the end of the loop to jump back to the loop test at the beginning. So this loop has the form of a C while(){...} loop, while the loop in the INSERT example had the form of a do{...}while() loop. The Delete instruction fills the role that the callback function did in the preceding examples.

The ListRead instruction reads an element from the temporary storage list and pushes it onto the stack. If this was successful, it continues to the next instruction. If this fails because the list is empty, it branches to P2, which is the instruction just after the loop. Afterwards the stack looks like:

(integer) key for current record

Notice the similarity between the ListRead and Next instructions. Both operations work according to this rule:

Push the next "thing" onto the stack and fall through OR jump to P2, depending on whether or not there is a next "thing" to push.

One difference between Next and ListRead is their idea of a "thing". The "things" for the Next instruction are records in a database file. "Things" for ListRead are integer keys in a list. Another difference is whether to jump or fall through if there is no next "thing". In this case, Next falls through, and ListRead jumps. Later on, we will see other looping instructions (NextIdx and SortNext) that operate using the same principle.

The NotExists instruction pops the top stack element and uses it as an integer key. If a record with that key does not exist in table P1, then jump to P2. If a record does exist, then fall through to the next instruction. In this case P2 takes us to the Goto at the end of the loop, which jumps back to the ListRead at the beginning. This could have been coded to have P2 be 16, the ListRead at the start of the loop, but the SQLite parser which generated this code didn't make that optimization.

The Delete does the work of this loop; it pops an integer key off the stack (placed there by the preceding ListRead) and deletes the record of cursor P1 that has that key. Because P2 is true, the row change counter is incremented.

The Goto jumps back to the beginning of the loop. This is the end of the loop.

20    ListReset     0      0
21    Close         0      0
22    Commit        0      0
23    Halt          0      0

This block of instruction cleans up the VDBE program. Three of these instructions aren't really required, but are generated by the SQLite parser from its code templates, which are designed to handle more complicated cases.

The ListReset instruction empties the temporary storage list. This list is emptied automatically when the VDBE program terminates, so it isn't necessary in this case. The Close instruction closes the cursor P1. Again, this is done by the VDBE engine when it is finished running this program. The Commit ends the current transaction successfully, and causes all changes that occurred in this transaction to be saved to the database. The final Halt is also unnecessary, since it is added to every VDBE program when it is prepared to run.

UPDATE statements work very much like DELETE statements except that instead of deleting the record they replace it with a new one. Consider this example:

UPDATE examp SET one= '(' || one || ')' WHERE two < 50;

Instead of deleting records where the "two" column is less than 50, this statement just puts the "one" column in parentheses The VDBE program to implement this statement follows:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     Transaction   1      0
1     Transaction   0      0
2     VerifyCookie  0      178
3     Integer       0      0
4     OpenRead      0      3      examp
5     Rewind        0      12
6     Column        0      1
7     Integer       50     0      50
8     Ge            1      11
9     Recno         0      0
10    ListWrite     0      0
11    Next          0      6
12    Close         0      0
13    Integer       0      0
14    OpenWrite     0      3
15    ListRewind    0      0
16    ListRead      0      28
17    Dup           0      0
18    NotExists     0      16
19    String        0      0      (
20    Column        0      0
21    Concat        2      0
22    String        0      0      )
23    Concat        2      0
24    Column        0      1
25    MakeRecord    2      0
26    PutIntKey     0      1
27    Goto          0      16
28    ListReset     0      0
29    Close         0      0
30    Commit        0      0
31    Halt          0      0

This program is essentially the same as the DELETE program except that the body of the second loop has been replace by a sequence of instructions (at addresses 17 through 26) that update the record rather than delete it. Most of this instruction sequence should already be familiar to you, but there are a couple of minor twists so we will go over it briefly. Also note that the order of some of the instructions before and after the 2nd loop has changed. This is just the way the SQLite parser chose to output the code using a different template.

As we enter the interior of the second loop (at instruction 17) the stack contains a single integer which is the key of the record we want to modify. We are going to need to use this key twice: once to fetch the old value of the record and a second time to write back the revised record. So the first instruction is a Dup to make a duplicate of the key on the top of the stack. The Dup instruction will duplicate any element of the stack, not just the top element. You specify which element to duplication using the P1 operand. When P1 is 0, the top of the stack is duplicated. When P1 is 1, the next element down on the stack duplication. And so forth.

After duplicating the key, the next instruction, NotExists, pops the stack once and uses the value popped as a key to check the existence of a record in the database file. If there is no record for this key, it jumps back to the ListRead to get another key.

Instructions 19 through 25 construct a new database record that will be used to replace the existing record. This is the same kind of code that we saw in the description of INSERT and will not be described further. After instruction 25 executes, the stack looks like this:

(record) new data record
(integer) key

The PutIntKey instruction (also described during the discussion about INSERT) writes an entry into the database file whose data is the top of the stack and whose key is the next on the stack, and then pops the stack twice. The PutIntKey instruction will overwrite the data of an existing record with the same key, which is what we want here. Overwriting was not an issue with INSERT because with INSERT the key was generated by the NewRecno instruction which is guaranteed to provide a key that has not been used before.

CREATE and DROP

Using CREATE or DROP to create or destroy a table or index is really the same as doing an INSERT or DELETE from the special "sqlite_master" table, at least from the point of view of the VDBE. The sqlite_master table is a special table that is automatically created for every SQLite database. It looks like this:

CREATE TABLE sqlite_master (
  type      TEXT,    -- either "table" or "index"
  name      TEXT,    -- name of this table or index
  tbl_name  TEXT,    -- for indices: name of associated table
  sql       TEXT     -- SQL text of the original CREATE statement
)

Every table (except the "sqlite_master" table itself) and every named index in an SQLite database has an entry in the sqlite_master table. You can query this table using a SELECT statement just like any other table. But you are not allowed to directly change the table using UPDATE, INSERT, or DELETE. Changes to sqlite_master have to occur using the CREATE and DROP commands because SQLite also has to update some of its internal data structures when tables and indices are added or destroyed.

But from the point of view of the VDBE, a CREATE works pretty much like an INSERT and a DROP works like a DELETE. When the SQLite library opens to an existing database, the first thing it does is a SELECT to read the "sql" columns from all entries of the sqlite_master table. The "sql" column contains the complete SQL text of the CREATE statement that originally generated the index or table. This text is fed back into the SQLite parser and used to reconstruct the internal data structures describing the index or table.

Using Indexes To Speed Searching

In the example queries above, every row of the table being queried must be loaded off of the disk and examined, even if only a small percentage of the rows end up in the result. This can take a long time on a big table. To speed things up, SQLite can use an index.

An SQLite file associates a key with some data. For an SQLite table, the database file is set up so that the key is an integer and the data is the information for one row of the table. Indices in SQLite reverse this arrangement. The index key is (some of) the information being stored and the index data is an integer. To access a table row that has some particular content, we first look up the content in the index table to find its integer index, then we use that integer to look up the complete record in the table.

Note that SQLite uses b-trees, which are a sorted data structure, so indices can be used when the WHERE clause of the SELECT statement contains tests for equality or inequality. Queries like the following can use an index if it is available:

SELECT * FROM examp WHERE two==50;
SELECT * FROM examp WHERE two<50;
SELECT * FROM examp WHERE two IN (50, 100);

If there exists an index that maps the "two" column of the "examp" table into integers, then SQLite will use that index to find the integer keys of all rows in examp that have a value of 50 for column two, or all rows that are less than 50, etc. But the following queries cannot use the index:

SELECT * FROM examp WHERE two%50 == 10;
SELECT * FROM examp WHERE two&127 == 3;

Note that the SQLite parser will not always generate code to use an index, even if it is possible to do so. The following queries will not currently use the index:

SELECT * FROM examp WHERE two+10 == 50;
SELECT * FROM examp WHERE two==50 OR two==100;

To understand better how indices work, lets first look at how they are created. Let's go ahead and put an index on the two column of the examp table. We have:

CREATE INDEX examp_idx1 ON examp(two);

The VDBE code generated by the above statement looks like the following:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     Transaction   1      0
1     Transaction   0      0
2     VerifyCookie  0      178
3     Integer       0      0
4     OpenWrite     0      2
5     NewRecno      0      0
6     String        0      0      index
7     String        0      0      examp_idx1
8     String        0      0      examp
9     CreateIndex   0      0      ptr(0x791380)
10    Dup           0      0
11    Integer       0      0
12    OpenWrite     1      0
13    String        0      0      CREATE INDEX examp_idx1 ON examp(tw
14    MakeRecord    5      0
15    PutIntKey     0      0
16    Integer       0      0
17    OpenRead      2      3      examp
18    Rewind        2      24
19    Recno         2      0
20    Column        2      1
21    MakeIdxKey    1      0      n
22    IdxPut        1      0      indexed columns are not unique
23    Next          2      19
24    Close         2      0
25    Close         1      0
26    Integer       333    0
27    SetCookie     0      0
28    Close         0      0
29    Commit        0      0
30    Halt          0      0

Remember that every table (except sqlite_master) and every named index has an entry in the sqlite_master table. Since we are creating a new index, we have to add a new entry to sqlite_master. This is handled by instructions 3 through 15. Adding an entry to sqlite_master works just like any other INSERT statement so we will not say any more about it here. In this example, we want to focus on populating the new index with valid data, which happens on instructions 16 through 23.

16    Integer       0      0
17    OpenRead      2      3      examp

The first thing that happens is that we open the table being indexed for reading. In order to construct an index for a table, we have to know what is in that table. The index has already been opened for writing using cursor 0 by instructions 3 and 4.

18    Rewind        2      24
19    Recno         2      0
20    Column        2      1
21    MakeIdxKey    1      0      n
22    IdxPut        1      0      indexed columns are not unique
23    Next          2      19

Instructions 18 through 23 implement a loop over every row of the table being indexed. For each table row, we first extract the integer key for that row using Recno in instruction 19, then get the value of the "two" column using Column in instruction 20. The MakeIdxKey instruction at 21 converts data from the "two" column (which is on the top of the stack) into a valid index key. For an index on a single column, this is basically a no-op. But if the P1 operand to MakeIdxKey had been greater than one multiple entries would have been popped from the stack and converted into a single index key. The IdxPut instruction at 22 is what actually creates the index entry. IdxPut pops two elements from the stack. The top of the stack is used as a key to fetch an entry from the index table. Then the integer which was second on stack is added to the set of integers for that index and the new record is written back to the database file. Note that the same index entry can store multiple integers if there are two or more table entries with the same value for the two column.

Now let's look at how this index will be used. Consider the following query:

SELECT * FROM examp WHERE two==50;

SQLite generates the following VDBE code to handle this query:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      one
1     ColumnName    1      0      two
2     Integer       0      0
3     OpenRead      0      3      examp
4     VerifyCookie  0      256
5     Integer       0      0
6     OpenRead      1      4      examp_idx1
7     Integer       50     0      50
8     MakeKey       1      0      n
9     MemStore      0      0
10    MoveTo        1      19
11    MemLoad       0      0
12    IdxGT         1      19
13    IdxRecno      1      0
14    MoveTo        0      0
15    Column        0      0
16    Column        0      1
17    Callback      2      0
18    Next          1      11
19    Close         0      0
20    Close         1      0
21    Halt          0      0

The SELECT begins in a familiar fashion. First the column names are initialized and the table being queried is opened. Things become different beginning with instructions 5 and 6 where the index file is also opened. Instructions 7 and 8 make a key with the value of 50. The MemStore instruction at 9 stores the index key in VDBE memory location 0. The VDBE memory is used to avoid having to fetch a value from deep in the stack, which can be done, but makes the program harder to generate. The following instruction MoveTo at address 10 pops the key off the stack and moves the index cursor to the first row of the index with that key. This initializes the cursor for use in the following loop.

Instructions 11 through 18 implement a loop over all index records with the key that was fetched by instruction 8. All of the index records with this key will be contiguous in the index table, so we walk through them and fetch the corresponding table key from the index. This table key is then used to move the cursor to that row in the table. The rest of the loop is the same as the loop for the non-indexed SELECT query.

The loop begins with the MemLoad instruction at 11 which pushes a copy of the index key back onto the stack. The instruction IdxGT at 12 compares the key to the key in the current index record pointed to by cursor P1. If the index key at the current cursor location is greater than the index we are looking for, then jump out of the loop.

The instruction IdxRecno at 13 pushes onto the stack the table record number from the index. The following MoveTo pops it and moves the table cursor to that row. The next 3 instructions select the column data the same way as in the non- indexed case. The Column instructions fetch the column data and the callback function is invoked. The final Next instruction advances the index cursor, not the table cursor, to the next row, and then branches back to the start of the loop if there are any index records left.

Since the index is used to look up values in the table, it is important that the index and table be kept consistent. Now that there is an index on the examp table, we will have to update that index whenever data is inserted, deleted, or changed in the examp table. Remember the first example above where we were able to insert a new row into the "examp" table using 12 VDBE instructions. Now that this table is indexed, 19 instructions are required. The SQL statement is this:

INSERT INTO examp VALUES('Hello, World!',99);

And the generated code looks like this:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     Transaction   1      0
1     Transaction   0      0
2     VerifyCookie  0      256
3     Integer       0      0
4     OpenWrite     0      3      examp
5     Integer       0      0
6     OpenWrite     1      4      examp_idx1
7     NewRecno      0      0
8     String        0      0      Hello, World!
9     Integer       99     0      99
10    Dup           2      1
11    Dup           1      1
12    MakeIdxKey    1      0      n
13    IdxPut        1      0
14    MakeRecord    2      0
15    PutIntKey     0      1
16    Close         0      0
17    Close         1      0
18    Commit        0      0
19    Halt          0      0

At this point, you should understand the VDBE well enough to figure out on your own how the above program works. So we will not discuss it further in this text.

Joins

In a join, two or more tables are combined to generate a single result. The result table consists of every possible combination of rows from the tables being joined. The easiest and most natural way to implement this is with nested loops.

Recall the query template discussed above where there was a single loop that searched through every record of the table. In a join we have basically the same thing except that there are nested loops. For example, to join two tables, the query template might look something like this:

  1. Initialize the azColumnName[] array for the callback.
  2. Open two cursors, one to each of the two tables being queried.
  3. For each record in the first table, do:
    1. For each record in the second table do:
      1. If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.
      2. Compute all columns for the current row of the result.
      3. Invoke the callback function for the current row of the result.
  4. Close both cursors.

This template will work, but it is likely to be slow since we are now dealing with an O(N2) loop. But it often works out that the WHERE clause can be factored into terms and that one or more of those terms will involve only columns in the first table. When this happens, we can factor part of the WHERE clause test out of the inner loop and gain a lot of efficiency. So a better template would be something like this:

  1. Initialize the azColumnName[] array for the callback.
  2. Open two cursors, one to each of the two tables being queried.
  3. For each record in the first table, do:
    1. Evaluate terms of the WHERE clause that only involve columns from the first table. If any term is false (meaning that the whole WHERE clause must be false) then skip the rest of this loop and continue to the next record.
    2. For each record in the second table do:
      1. If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.
      2. Compute all columns for the current row of the result.
      3. Invoke the callback function for the current row of the result.
  4. Close both cursors.

Additional speed-up can occur if an index can be used to speed the search of either or the two loops.

SQLite always constructs the loops in the same order as the tables appear in the FROM clause of the SELECT statement. The left-most table becomes the outer loop and the right-most table becomes the inner loop. It is possible, in theory, to reorder the loops in some circumstances to speed the evaluation of the join. But SQLite does not attempt this optimization.

You can see how SQLite constructs nested loops in the following example:

CREATE TABLE examp2(three int, four int);
SELECT * FROM examp, examp2 WHERE two<50 AND four==two;
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      examp.one
1     ColumnName    1      0      examp.two
2     ColumnName    2      0      examp2.three
3     ColumnName    3      0      examp2.four
4     Integer       0      0
5     OpenRead      0      3      examp
6     VerifyCookie  0      909
7     Integer       0      0
8     OpenRead      1      5      examp2
9     Rewind        0      24
10    Column        0      1
11    Integer       50     0      50
12    Ge            1      23
13    Rewind        1      23
14    Column        1      1
15    Column        0      1
16    Ne            1      22
17    Column        0      0
18    Column        0      1
19    Column        1      0
20    Column        1      1
21    Callback      4      0
22    Next          1      14
23    Next          0      10
24    Close         0      0
25    Close         1      0
26    Halt          0      0

The outer loop over table examp is implement by instructions 7 through 23. The inner loop is instructions 13 through 22. Notice that the "two<50" term of the WHERE expression involves only columns from the first table and can be factored out of the inner loop. SQLite does this and implements the "two<50" test in instructions 10 through 12. The "four==two" test is implement by instructions 14 through 16 in the inner loop.

SQLite does not impose any arbitrary limits on the tables in a join. It also allows a table to be joined with itself.

The ORDER BY clause

For historical reasons, and for efficiency, all sorting is currently done in memory.

SQLite implements the ORDER BY clause using a special set of instructions to control an object called a sorter. In the inner-most loop of the query, where there would normally be a Callback instruction, instead a record is constructed that contains both callback parameters and a key. This record is added to the sorter (in a linked list). After the query loop finishes, the list of records is sorted and this list is walked. For each record on the list, the callback is invoked. Finally, the sorter is closed and memory is deallocated.

We can see the process in action in the following query:

SELECT * FROM examp ORDER BY one DESC, two;
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      one
1     ColumnName    1      0      two
2     Integer       0      0
3     OpenRead      0      3      examp
4     VerifyCookie  0      909
5     Rewind        0      14
6     Column        0      0
7     Column        0      1
8     SortMakeRec   2      0
9     Column        0      0
10    Column        0      1
11    SortMakeKey   2      0      D+
12    SortPut       0      0
13    Next          0      6
14    Close         0      0
15    Sort          0      0
16    SortNext      0      19
17    SortCallback  2      0
18    Goto          0      16
19    SortReset     0      0
20    Halt          0      0

There is only one sorter object, so there are no instructions to open or close it. It is opened automatically when needed, and it is closed when the VDBE program halts.

The query loop is built from instructions 5 through 13. Instructions 6 through 8 build a record that contains the azData[] values for a single invocation of the callback. A sort key is generated by instructions 9 through 11. Instruction 12 combines the invocation record and the sort key into a single entry and puts that entry on the sort list.

The P3 argument of instruction 11 is of particular interest. The sort key is formed by prepending one character from P3 to each string and concatenating all the strings. The sort comparison function will look at this character to determine whether the sort order is ascending or descending, and whether to sort as a string or number. In this example, the first column should be sorted as a string in descending order so its prefix is "D" and the second column should sorted numerically in ascending order so its prefix is "+". Ascending string sorting uses "A", and descending numeric sorting uses "-".

After the query loop ends, the table being queried is closed at instruction 14. This is done early in order to allow other processes or threads to access that table, if desired. The list of records that was built up inside the query loop is sorted by the instruction at 15. Instructions 16 through 18 walk through the record list (which is now in sorted order) and invoke the callback once for each record. Finally, the sorter is closed at instruction 19.

Aggregate Functions And The GROUP BY and HAVING Clauses

To compute aggregate functions, the VDBE implements a special data structure and instructions for controlling that data structure. The data structure is an unordered set of buckets, where each bucket has a key and one or more memory locations. Within the query loop, the GROUP BY clause is used to construct a key and the bucket with that key is brought into focus. A new bucket is created with the key if one did not previously exist. Once the bucket is in focus, the memory locations of the bucket are used to accumulate the values of the various aggregate functions. After the query loop terminates, each bucket is visited once to generate a single row of the results.

An example will help to clarify this concept. Consider the following query:

SELECT three, min(three+four)+avg(four)
FROM examp2
GROUP BY three;

The VDBE code generated for this query is as follows:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      three
1     ColumnName    1      0      min(three+four)+avg(four)
2     AggReset      0      3
3     AggInit       0      1      ptr(0x7903a0)
4     AggInit       0      2      ptr(0x790700)
5     Integer       0      0
6     OpenRead      0      5      examp2
7     VerifyCookie  0      909
8     Rewind        0      23
9     Column        0      0
10    MakeKey       1      0      n
11    AggFocus      0      14
12    Column        0      0
13    AggSet        0      0
14    Column        0      0
15    Column        0      1
16    Add           0      0
17    Integer       1      0
18    AggFunc       0      1      ptr(0x7903a0)
19    Column        0      1
20    Integer       2      0
21    AggFunc       0      1      ptr(0x790700)
22    Next          0      9
23    Close         0      0
24    AggNext       0      31
25    AggGet        0      0
26    AggGet        0      1
27    AggGet        0      2
28    Add           0      0
29    Callback      2      0
30    Goto          0      24
31    Noop          0      0
32    Halt          0      0

The first instruction of interest is the AggReset at 2. The AggReset instruction initializes the set of buckets to be the empty set and specifies the number of memory slots available in each bucket as P2. In this example, each bucket will hold 3 memory slots. It is not obvious, but if you look closely at the rest of the program you can figure out what each of these slots is intended for.

Memory Slot | Intended Use Of This Memory Slot
0 | The "three" column -- the key to the bucket
1 | The minimum "three+four" value
2 | The sum of all "four" values. This is used to compute "avg(four)".

The query loop is implemented by instructions 8 through 22. The aggregate key specified by the GROUP BY clause is computed by instructions 9 and 10. Instruction 11 causes the appropriate bucket to come into focus. If a bucket with the given key does not already exists, a new bucket is created and control falls through to instructions 12 and 13 which initialize the bucket. If the bucket does already exist, then a jump is made to instruction 14. The values of aggregate functions are updated by the instructions between 11 and 21. Instructions 14 through 18 update memory slot 1 to hold the next value "min(three+four)". Then the sum of the "four" column is updated by instructions 19 through 21.

After the query loop is finished, the table "examp2" is closed at instruction 23 so that its lock will be released and it can be used by other threads or processes. The next step is to loop over all aggregate buckets and output one row of the result for each bucket. This is done by the loop at instructions 24 through 30. The AggNext instruction at 24 brings the next bucket into focus, or jumps to the end of the loop if all buckets have been examined already. The 3 columns of the result are fetched from the aggregator bucket in order at instructions 25 through 27. Finally, the callback is invoked at instruction 29.

In summary then, any query with aggregate functions is implemented by two loops. The first loop scans the input table and computes aggregate information into buckets and the second loop scans through all the buckets to compute the final result.

The realization that an aggregate query is really two consecutive loops makes it much easier to understand the difference between a WHERE clause and a HAVING clause in SQL query statement. The WHERE clause is a restriction on the first loop and the HAVING clause is a restriction on the second loop. You can see this by adding both a WHERE and a HAVING clause to our example query:

SELECT three, min(three+four)+avg(four)
FROM examp2
WHERE three>four
GROUP BY three
HAVING avg(four)<10;
addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     ColumnName    0      0      three
1     ColumnName    1      0      min(three+four)+avg(four)
2     AggReset      0      3
3     AggInit       0      1      ptr(0x7903a0)
4     AggInit       0      2      ptr(0x790700)
5     Integer       0      0
6     OpenRead      0      5      examp2
7     VerifyCookie  0      909
8     Rewind        0      26
9     Column        0      0
10    Column        0      1
11    Le            1      25
12    Column        0      0
13    MakeKey       1      0      n
14    AggFocus      0      17
15    Column        0      0
16    AggSet        0      0
17    Column        0      0
18    Column        0      1
19    Add           0      0
20    Integer       1      0
21    AggFunc       0      1      ptr(0x7903a0)
22    Column        0      1
23    Integer       2      0
24    AggFunc       0      1      ptr(0x790700)
25    Next          0      9
26    Close         0      0
27    AggNext       0      37
28    AggGet        0      2
29    Integer       10     0      10
30    Ge            1      27
31    AggGet        0      0
32    AggGet        0      1
33    AggGet        0      2
34    Add           0      0
35    Callback      2      0
36    Goto          0      27
37    Noop          0      0
38    Halt          0      0

The code generated in this last example is the same as the previous except for the addition of two conditional jumps used to implement the extra WHERE and HAVING clauses. The WHERE clause is implemented by instructions 9 through 11 in the query loop. The HAVING clause is implemented by instruction 28 through 30 in the output loop.

Using SELECT Statements As Terms In An Expression

The very name "Structured Query Language" tells us that SQL should support nested queries. And, in fact, two different kinds of nesting are supported. Any SELECT statement that returns a single-row, single-column result can be used as a term in an expression of another SELECT statement. And, a SELECT statement that returns a single-column, multi-row result can be used as the right-hand operand of the IN and NOT IN operators. We will begin this section with an example of the first kind of nesting, where a single-row, single-column SELECT is used as a term in an expression of another SELECT. Here is our example:

SELECT * FROM examp
WHERE two!=(SELECT three FROM examp2
            WHERE four=5);

The way SQLite deals with this is to first run the inner SELECT (the one against examp2) and store its result in a private memory cell. SQLite then substitutes the value of this private memory cell for the inner SELECT when it evaluates the outer SELECT. The code looks like this:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     String        0      0
1     MemStore      0      1
2     Integer       0      0
3     OpenRead      1      5      examp2
4     VerifyCookie  0      909
5     Rewind        1      13
6     Column        1      1
7     Integer       5      0      5
8     Ne            1      12
9     Column        1      0
10    MemStore      0      1
11    Goto          0      13
12    Next          1      6
13    Close         1      0
14    ColumnName    0      0      one
15    ColumnName    1      0      two
16    Integer       0      0
17    OpenRead      0      3      examp
18    Rewind        0      26
19    Column        0      1
20    MemLoad       0      0
21    Eq            1      25
22    Column        0      0
23    Column        0      1
24    Callback      2      0
25    Next          0      19
26    Close         0      0
27    Halt          0      0

The private memory cell is initialized to NULL by the first two instructions. Instructions 2 through 13 implement the inner SELECT statement against the examp2 table. Notice that instead of sending the result to a callback or storing the result on a sorter, the result of the query is pushed into the memory cell by instruction 10 and the loop is abandoned by the jump at instruction 11. The jump at instruction at 11 is vestigial and never executes.

The outer SELECT is implemented by instructions 14 through 25. In particular, the WHERE clause that contains the nested select is implemented by instructions 19 through 21. You can see that the result of the inner select is loaded onto the stack by instruction 20 and used by the conditional jump at 21.

When the result of a sub-select is a scalar, a single private memory cell can be used, as shown in the previous example. But when the result of a sub-select is a vector, such as when the sub-select is the right-hand operand of IN or NOT IN, a different approach is needed. In this case, the result of the sub-select is stored in a transient table and the contents of that table are tested using the Found or NotFound operators. Consider this example:

SELECT * FROM examp
WHERE two IN (SELECT three FROM examp2);

The code generated to implement this last query is as follows:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     OpenTemp      1      1
1     Integer       0      0
2     OpenRead      2      5      examp2
3     VerifyCookie  0      909
4     Rewind        2      10
5     Column        2      0
6     IsNull        -1     9
7     String        0      0
8     PutStrKey     1      0
9     Next          2      5
10    Close         2      0
11    ColumnName    0      0      one
12    ColumnName    1      0      two
13    Integer       0      0
14    OpenRead      0      3      examp
15    Rewind        0      25
16    Column        0      1
17    NotNull       -1     20
18    Pop           1      0
19    Goto          0      24
20    NotFound      1      24
21    Column        0      0
22    Column        0      1
23    Callback      2      0
24    Next          0      16
25    Close         0      0
26    Halt          0      0

The transient table in which the results of the inner SELECT are stored is created by the OpenTemp instruction at 0. This opcode is used for tables that exist for the duration of a single SQL statement only. The transient cursor is always opened read/write even if the main database is read-only. The transient table is deleted automatically when the cursor is closed. The P2 value of 1 means the cursor points to a BTree index, which has no data but can have an arbitrary key.

The inner SELECT statement is implemented by instructions 1 through 10. All this code does is make an entry in the temporary table for each row of the examp2 table with a non-NULL value for the "three" column. The key for each temporary table entry is the "three" column of examp2 and the data is an empty string since it is never used.

The outer SELECT is implemented by instructions 11 through 25. In particular, the WHERE clause containing the IN operator is implemented by instructions at 16, 17, and 20. Instruction 16 pushes the value of the "two" column for the current row onto the stack and instruction 17 checks to see that it is non-NULL. If this is successful, execution jumps to 20, where it tests to see if top of the stack matches any key in the temporary table. The rest of the code is the same as what has been shown before.

Compound SELECT Statements

SQLite also allows two or more SELECT statements to be joined as peers using operators UNION, UNION ALL, INTERSECT, and EXCEPT. These compound select statements are implemented using transient tables. The implementation is slightly different for each operator, but the basic ideas are the same. For an example we will use the EXCEPT operator.

SELECT two FROM examp
EXCEPT
SELECT four FROM examp2;

The result of this last example should be every unique value of the "two" column in the examp table, except any value that is in the "four" column of examp2 is removed. The code to implement this query is as follows:

addr  opcode        p1     p2     p3
----  ------------  -----  -----  -----------------------------------
0     OpenTemp      0      1
1     KeyAsData     0      1
2     Integer       0      0
3     OpenRead      1      3      examp
4     VerifyCookie  0      909
5     Rewind        1      11
6     Column        1      1
7     MakeRecord    1      0
8     String        0      0
9     PutStrKey     0      0
10    Next          1      6
11    Close         1      0
12    Integer       0      0
13    OpenRead      2      5      examp2
14    Rewind        2      20
15    Column        2      1
16    MakeRecord    1      0
17    NotFound      0      19
18    Delete        0      0
19    Next          2      15
20    Close         2      0
21    ColumnName    0      0      four
22    Rewind        0      26
23    Column        0      0
24    Callback      1      0
25    Next          0      23
26    Close         0      0
27    Halt          0      0

The transient table in which the result is built is created by instruction 0. Three loops then follow. The loop at instructions 5 through 10 implements the first SELECT statement. The second SELECT statement is implemented by the loop at instructions 14 through 19. Finally, a loop at instructions 22 through 25 reads the transient table and invokes the callback once for each row in the result.

Instruction 1 is of particular importance in this example. Normally, the Column instruction extracts the value of a column from a larger record in the data of an SQLite file entry. Instruction 1 sets a flag on the transient table so that Column will instead treat the key of the SQLite file entry as if it were data and extract column information from the key.

Here is what is going to happen: The first SELECT statement will construct rows of the result and save each row as the key of an entry in the transient table. The data for each entry in the transient table is a never used so we fill it in with an empty string. The second SELECT statement also constructs rows, but the rows constructed by the second SELECT are removed from the transient table. That is why we want the rows to be stored in the key of the SQLite file instead of in the data -- so they can be easily located and deleted.

Let's look more closely at what is happening here. The first SELECT is implemented by the loop at instructions 5 through 10. Instruction 5 initializes the loop by rewinding its cursor. Instruction 6 extracts the value of the "two" column from "examp" and instruction 7 converts this into a row. Instruction 8 pushes an empty string onto the stack. Finally, instruction 9 writes the row into the temporary table. But remember, the PutStrKey opcode uses the top of the stack as the record data and the next on stack as the key. For an INSERT statement, the row generated by the MakeRecord opcode is the record data and the record key is an integer created by the NewRecno opcode. But here the roles are reversed and the row created by MakeRecord is the record key and the record data is just an empty string.

The second SELECT is implemented by instructions 14 through 19. Instruction 14 initializes the loop by rewinding its cursor. A new result row is created from the "four" column of table "examp2" by instructions 15 and 16. But instead of using PutStrKey to write this new row into the temporary table, we instead call Delete to remove it from the temporary table if it exists.

The result of the compound select is sent to the callback routine by the loop at instructions 22 through 25. There is nothing new or remarkable about this loop, except for the fact that the Column instruction at 23 will be extracting a column out of the record key rather than the record data.

Summary

This article has reviewed all of the major techniques used by SQLite's VDBE to implement SQL statements. What has not been shown is that most of these techniques can be used in combination to generate code for an appropriately complex query statement. For example, we have shown how sorting is accomplished on a simple query and we have shown how to implement a compound query. But we did not give an example of sorting in a compound query. This is because sorting a compound query does not introduce any new concepts: it merely combines two previous ideas (sorting and compounding) in the same VDBE program.

For additional information on how the SQLite library functions, the reader is directed to look at the SQLite source code directly. If you understand the material in this article, you should not have much difficulty in following the sources. Serious students of the internals of SQLite will probably also want to make a careful study of the VDBE opcodes as documented here. Most of the opcode documentation is extracted from comments in the source code using a script so you can also get information about the various opcodes directly from the vdbe.c source file. If you have successfully read this far, you should have little difficulty understanding the rest.

If you find errors in either the documentation or the code, feel free to fix them and/or contact the author at drh@hwaci.com. Your bug fixes or suggestions are always welcomed.


SQLite Version 3 Overview

SQLite version 3.0 introduces important changes to the library, including:

  • A more compact format for database files.
  • Manifest typing and BLOB support.
  • Support for both UTF-8 and UTF-16 text.
  • User-defined text collating sequences.
  • 64-bit ROWIDs.
  • Improved Concurrency.

This document is a quick introduction to the changes for SQLite 3.0 for users who are already familiar with SQLite version 2.8.

Naming Changes

SQLite version 2.8 will continue to be supported with bug fixes for the foreseeable future. In order to allow SQLite version 2.8 and SQLite version 3.0 to peacefully coexist, the names of key files and APIs in SQLite version 3.0 have been changed to include the character "3". For example, the include file used by C programs has been changed from "sqlite.h" to "sqlite3.h". And the name of the shell program used to interact with databases has been changed from "sqlite.exe" to "sqlite3.exe". With these changes, it is possible to have both SQLite 2.8 and SQLite 3.0 installed on the same system at the same time. And it is possible for the same C program to link against both SQLite 2.8 and SQLite 3.0 at the same time and to use both libraries at the same time.

New File Format

The format used by SQLite database files has been completely revised. The old version 2.1 format and the new 3.0 format are incompatible with one another. Version 2.8 of SQLite will not read a version 3.0 database files and version 3.0 of SQLite will not read a version 2.8 database file.

To convert an SQLite 2.8 database into an SQLite 3.0 database, have ready the command-line shells for both version 2.8 and 3.0. Then enter a command like the following:

sqlite OLD.DB .dump | sqlite3 NEW.DB

The new database file format uses B+trees for tables. In a B+tree, all data is stored in the leaves of the tree instead of in both the leaves and the intermediate branch nodes. The use of B+trees for tables allows for better scalability and the storage of larger data fields without the use of overflow pages. Traditional B-trees are still used for indices.

The new file format also supports variable pages sizes between 512 and 65536 bytes. The size of a page is stored in the file header so the same library can read databases with different pages sizes, in theory, though this feature has not yet been implemented in practice.

The new file format omits unused fields from its disk images. For example, indices use only the key part of a B-tree record and not the data. So for indices, the field that records the length of the data is omitted. Integer values such as the length of key and data are stored using a variable-length encoding so that only one or two bytes are required to store the most common cases but up to 64-bits of information can be encoded if needed. Integer and floating point data is stored on the disk in binary rather than being converted into ASCII as in SQLite version 2.8. These changes taken together result in database files that are typically 25% to 35% smaller than the equivalent files in SQLite version 2.8.

Details of the low-level B-tree format used in SQLite version 3.0 can be found in header comments to the btreeInt.h source file and in the file format documentation.

Manifest Typing and BLOB Support

SQLite version 2.8 will deal with data in various formats internally, but when writing to the disk or interacting through its API, SQLite 2.8 always converts data into ASCII text. SQLite 3.0, in contrast, exposes its internal data representations to the user and stores binary representations to disk when appropriate. The exposing of non-ASCII representations was added in order to support BLOBs.

SQLite version 2.8 had the feature that any type of data could be stored in any table column regardless of the declared type of that column. This feature is retained in version 3.0, though in a slightly modified form. Each table column will store any type of data, though columns have an affinity for the format of data defined by their declared datatype. When data is inserted into a column, that column will make an attempt to convert the data format into the column's declared type. All SQL database engines do this. The difference is that SQLite 3.0 will still store the data even if a format conversion is not possible.

For example, if you have a table column declared to be of type "INTEGER" and you try to insert a string, the column will look at the text string and see if it looks like a number. If the string does look like a number it is converted into a number and into an integer if the number does not have a fractional part, and stored that way. But if the string is not a well-formed number it is still stored as a string. A column with a type of "TEXT" tries to convert numbers into an ASCII-Text representation before storing them. But BLOBs are stored in TEXT columns as BLOBs because you cannot in general convert a BLOB into text.

In most other SQL database engines the datatype is associated with the table column that holds the data - with the data container. In SQLite 3.0, the datatype is associated with the data itself, not with its container. Paul Graham in his book ANSI Common Lisp calls this property "Manifest Typing". Other writers have other definitions for the term "manifest typing", so beware of confusion. But by whatever name, that is the datatype model supported by SQLite 3.0.

Additional information about datatypes in SQLite version 3.0 is available separately.

Support for UTF-8 and UTF-16

The new API for SQLite 3.0 contains routines that accept text as both UTF-8 and UTF-16 in the native byte order of the host machine. Each database file manages text as either UTF-8, UTF-16BE (big-endian), or UTF-16LE (little-endian). Internally and in the disk file, the same text representation is used everywhere. If the text representation specified by the database file (in the file header) does not match the text representation required by the interface routines, then text is converted on-the-fly. Constantly converting text from one representation to another can be computationally expensive, so it is suggested that programmers choose a single representation and stick with it throughout their application.

In the current implementation of SQLite, the SQL parser only works with UTF-8 text. So if you supply UTF-16 text it will be converted. This is just an implementation issue and there is nothing to prevent future versions of SQLite from parsing UTF-16 encoded SQL natively.

When creating new user-defined SQL functions and collating sequences, each function or collating sequence can specify if it works with UTF-8, UTF-16be, or UTF-16le. Separate implementations can be registered for each encoding. If an SQL function or collating sequence is required but a version for the current text encoding is not available, then the text is automatically converted. As before, this conversion takes computation time, so programmers are advised to pick a single encoding and stick with it in order to minimize the amount of unnecessary format juggling.

SQLite is not particular about the text it receives and is more than happy to process text strings that are not normalized or even well-formed UTF-8 or UTF-16. Thus, programmers who want to store IS08859 data can do so using the UTF-8 interfaces. As long as no attempts are made to use a UTF-16 collating sequence or SQL function, the byte sequence of the text will not be modified in any way.

User-defined Collating Sequences

A collating sequence is just a defined order for text. When SQLite 3.0 sorts (or uses a comparison operator like "<" or ">=") the sort order is first determined by the data type.

  • NULLs sort first
  • Numeric values sort next in numerical order
  • Text values come after numerics
  • BLOBs sort last

Collating sequences are used for comparing two text strings. The collating sequence does not change the ordering of NULLs, numbers, or BLOBs, only text.

A collating sequence is implemented as a function that takes the two strings being compared as inputs and returns negative, zero, or positive if the first string is less than, equal to, or greater than the second. SQLite 3.0 comes with a single built-in collating sequence named "BINARY" which is implemented using the memcmp() routine from the standard C library. The BINARY collating sequence works well for English text. For other languages or locales, alternative collating sequences may be preferred.

The decision of which collating sequence to use is controlled by the COLLATE clause in SQL. A COLLATE clause can occur on a table definition, to define a default collating sequence to a table column, or on field of an index, or in the ORDER BY clause of a SELECT statement. Planned enhancements to SQLite are to include standard CAST() syntax to allow the collating sequence of an expression to be defined.

64-bit ROWIDs

Every row of a table has a unique rowid. If the table defines a column with the type "INTEGER PRIMARY KEY" then that column becomes an alias for the rowid. But with or without an INTEGER PRIMARY KEY column, every row still has a rowid.

In SQLite version 3.0, the rowid is a 64-bit signed integer. This is an expansion of SQLite version 2.8 which only permitted rowids of 32-bits.

To minimize storage space, the 64-bit rowid is stored as a variable length integer. Rowids between 0 and 127 use only a single byte. Rowids between 0 and 16383 use just 2 bytes. Up to 2097152 uses three bytes. And so forth. Negative rowids are allowed but they always use nine bytes of storage and so their use is discouraged. When rowids are generated automatically by SQLite, they will always be non-negative.

Improved Concurrency

SQLite version 2.8 allowed multiple simultaneous readers or a single writer but not both. SQLite version 3.0 allows one process to begin writing the database while other processes continue to read. The writer must still obtain an exclusive lock on the database for a brief interval in order to commit its changes, but the exclusive lock is no longer required for the entire write operation. A more detailed report on the locking behavior of SQLite version 3.0 is available separately.

A limited form of table-level locking is now also available in SQLite. If each table is stored in a separate database file, those separate files can be attached to the main database (using the ATTACH command) and the combined databases will function as one. But locks will only be acquired on individual files as needed. So if you redefine "database" to mean two or more database files, then it is entirely possible for two processes to be writing to the same database at the same time. To further support this capability, commits of transactions involving two or more ATTACHed database are now atomic.

Credits

SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software.


The OS Backend (VFS) To SQLite

Choose any three.
About Sitemap Documentation Download License News Support

The SQLite OS Interface or "VFS"

This article describes the SQLite OS portability layer or "VFS" - the module at the bottom of the SQLite implementation stack that provides portability across operating systems.

1.0 The VFS In Relation To The Rest Of SQLite

The internal organization of the SQLite library can be viewed as the stack of modules shown to the right. The Tokenizer, Parser, and Code Generator components are used to process SQL statements and convert them into executable programs in a virtual machine language or byte code. Roughly speaking, these top three layers implement sqlite3_prepare_v2(). The byte code generated by the top three layers is a prepared statement. The Virtual Machine module is responsible for running the SQL statement byte code. The B-Tree module organizes a database file into multiple key/value stores with ordered keys and logarithmic performance. The Pager module is responsible for loading pages of the database file into memory, for implementing and controlling transactions, and for creating and maintaining the journal files that prevent database corruption following a crash or power failure. The OS Interface is a thin abstraction that provides a common set of routines for adapting SQLite to run on different operating systems. Roughly speaking, the bottom four layers implement sqlite3_step().

This article is about the bottom layer.

The OS Interface - also called the "VFS" - is what makes SQLite portable across operating systems. Whenever any of the other modules in SQLite needs to communicate with the operating system, they invoke methods in the VFS. The VFS then invokes the operating-specific code needed to satisfy the request. Hence, porting SQLite to a new operating system is simply a matter of writing a new OS interface layer or "VFS".

2.0 Multiple VFSes

The standard SQLite source tree contains built-in VFSes for os/2, unix, and windows. Alternative VFSes can be added at start-time or run-time using the sqlite3_vfs_register() interface.

Multiple VFSes can be registered at the same time. Each VFS has a unique names. Separate database connections within the same process can be using different VFSes at the same time. For that matter, if a single database connection has multiple database files open using the ATTACH command, then each attached database might be using a different VFS.

Unix builds come with multiple VFSes built-in. The default VFS for unix is called "unix" and is the VFS used in an overwhelming majority of applications. Other VFSes that can be found in unix may include:

  1. unix-dotfile - uses dot-file locking rather than POSIX advisory locks.

  2. unix-excl - obtains and holds an exclusive lock on database files, preventing other processes from accessing the database. Also keeps the wal-index in heap rather than in shared memory.

  3. unix-none - all file locking operations are no-ops.

  4. unix-namedsem - uses named semaphores for file locking. VXWorks only.

The various unix VFSes differ only in the way they handle file locking - they share most of their implementation in common with one another and are all located in the same SQLite source file: os_unix.c. Note that except for "unix" and "unix-excl", the various unix VFSes all use incompatible locking implementations. If two processes are accessing the same SQLite database using different unix VFSes, they may not see each others locks and may end up interfering with one another, resulting in database corruption. The "unix-none" VFS in particular does no locking at all and will easily result in database corruption if used by two or more database connections at the same time. Programmers are encouraged to use only "unix" or "unix-excl" unless there is a compelling reason to do otherwise.

2.1 Specifying Which VFS To Use

There is always one VFS which is the default VFS. On unix systems, the "unix" VFS comes up as the default and on windows it is "win32". If no other actions are taken, new database connections will make use of the default VFS.

The default VFS can be changed by registering or re-registering the VFS using the sqlite3_vfs_register() interface with a second parameter of 1. Hence, if a (unix) process to always use the "unix-nolock" VFS in place of "unix", the following code would work:

sqlite3_vfs_register(sqlite3_vfs_find("unix-nolock"), 1);

An alternate VFS can also be specified as the 4th parameter to the sqlite3_open_v2() function. For example:

int rc = sqlite3_open_v2("demo.db", &db, SQLITE_OPEN_READWRITE, "unix-nolock");

Finally, if URI filenames have been enabled, then the alternative VFS can be specified using the "vfs=" parameter on the URI. This technique works with sqlite3_open(), sqlite3_open16(), sqlite3_open_v2(), and when a new database is ATTACH-ed to an existing database connection. For example:

ATTACH 'file:demo2.db?vfs=unix-none' AS demo2;

The VFS specified by a URI has the highest priority. After that comes a VFS specified as the fourth argument to sqlite3_open_v2(). The default VFS is used if no VFS is specified otherwise.

2.2 VFS Shims

From the point of view of the uppers layers of the SQLite stack, each open database file uses exactly one VFS. But in practice, a particular VFS might just be a thin wrapper around another VFS that does the real work. We call a wrapper VFS a "shim".

A simple example of a shim is the "vfstrace" VFS. This is a VFS (implemented in the test_vfstrace.c source file) that writes a message associated with each VFS method call into a log file, then passes control off to another VFS to do the actual work.

2.3 Other Example VFSes

The following are other VFS implementations available in the public SQLite source tree:

  • test_demovfs.c - This file implements a very simple VFS named "demo" that uss POSIX functions such as open(), read(), write(), fsync(), close(), fsync(), sleep(), time(), and so forth. This VFS only works on unix systems. But it is not intended as a replacement for the standard "unix" VFS used by default on unix platforms. The "demo" VFS is deliberately kept very simple so that it can be used as a learning aid or as template for building other VFSes or for porting SQLite to new operating systems.

  • test_quota.c - This file implements a shim called "quota" that enforces cumulative file size limits on a collection of database files. An auxiliary interface is used to define "quote groups". A quota group is a set of files (database files, journals, and temporary files) whose names all match a GLOB pattern. The sum of the sizes of all files in each quota group is tracked, and if that sum exceeds a threshold defined for the quota group, a callback function is invoked. That callback can either increase the threshold or cause the operation that would have exceeded the quota to fail with an SQLITE_FULL error. One of the uses of this shim is used to enforce resource limits on application databases in Firefox.

  • test_multiplex.c - This file implements a shim that allows database files to exceed the maximum file size of the underlying filesystem. This shim presents an interface to the upper six layers of SQLite that makes it look like very large files are being used, when in reality each such large file is split up into many smaller files on the underlying system. This shim has been used, for example, to allow databases to grow larger than 2 gibibytes on FAT16 filesystems.

  • test_onefile.c - This file implements a demonstration VFS named "fs" that shows how SQLite can be used on an embedded device that lacks a filesystem. Content is written directly to the underlying media. A VFS derived from this demonstration code could be used by a gadget with a limited amount of flash memory to make SQLite behave as the filesystem for the flash memory on the device.

  • test_journal.c - This file implements a shim used during SQLite testing that verifies that the database and rollback journal are written in the correct order and are "synced" at appropriate times in order to guarantee that the database can recover from a power lose are hard reset at any time. The shim checks several invariants on the operation of databases and rollback journals and raises exceptions if any of those invariants are violated. These invariants, in turn, assure that the database is always recoverable. Running a large suite of test cases using this shim provides added assurance that SQLite databases will not be damaged by unexpected power failures or device resets.

  • test_vfs.c - This file implements a shim that can be used to simulate filesystem faults. This shim is used during testing to verify that SQLite responses sanely to hardware malfunctions or to other error conditions such as running out of filesystem space that are difficult to test on a real system.

There are other VFS implementations both in the core SQLite source code library and in available extensions. The list above is not meant to be exhaustive but merely representative of the kinds of features that can be realized using the VFS interface.

3.0 VFS Implementations

A new VFS is implemented by subclassing three objects:

  • sqlite3_vfs
  • sqlite3_io_methods
  • sqlite3_file

An sqlite3_vfs object defines the name of the VFS and the core methods that implement the interface to the operating system, such as checking for existence of files, deleting files, creating files and opening and for reading and/or writing, converting filenames into their canonical form. The sqlite3_vfs object also contains methods for obtaining randomness from the operating system, for suspending a process (sleeping) and for finding the current date and time.

The sqlite3_file object represents an open file. The xOpen method of sqlite3_vfs constructs an sqlite3_file object when the file is opened. The sqlite3_file keeps track of the state of the file while it is opened.

The sqlite3_io_methods object holds the methods used to interact with an open file. Each sqlite3_file contains a pointer to an sqlite3_io_methods object that is appropriate for the file it represents. The sqlite3_io_methods object contains methods to do things such as read and write from the file, to truncate the file, to flush any changes to persistent storage, to find the size of the file, to lock and unlock the file, and to close file and destroy the sqlite3_file object.

Writing the code for a new VFS involves constructing a subclass for the sqlite3_vfs object and then registering that VFS object using a call to sqlite3_vfs_register(). The VFS implementation also provides subclasses for sqlite3_file and sqlite3_io_methods but those objects are not registered directly with SQLite. Instead, the sqlite3_file object is returned from the xOpen method of sqlite3_vfs and the sqlite3_file object points to an instance of the sqlite3_io_methods object.

To Be Continued...


The Virtual Table Mechanism Of SQLite

1.0 Introduction

A virtual table is an object that is registered with an open SQLite database connection. From the perspective of an SQL statement, the virtual table object looks like any other table or view. But behind the scenes, queries from and updates to a virtual table invoke callback methods on the virtual table object instead of reading and writing to the database file.

The virtual table mechanism allows an application to publish interfaces that are accessible from SQL statements as if they were tables. SQL statements can in general do anything to a virtual table that they can do to a real table, with the following exceptions:

  • One cannot create a trigger on a virtual table.
  • One cannot create additional indices on a virtual table. (Virtual tables can have indices but that must be built into the virtual table implementation. Indices cannot be added separately using CREATE INDEX statements.)
  • One cannot run ALTER TABLE ... ADD COLUMN commands against a virtual table.

Particular virtual table implementations might impose additional constraints. For example, some virtual implementations might provide read-only tables. Or some virtual table implementations might allow INSERT or DELETE but not UPDATE. Or some virtual table implementations might limit the kinds of UPDATEs that can be made.

A virtual table might represent an in-memory data structures. Or it might represent a view of data on disk that is not in the SQLite format. Or the application might compute the content of the virtual table on demand.

Here are some postulated uses for virtual tables:

  • A full-text search interface
  • Spatial indices using R-Trees
  • Read and/or write the content of a comma-separated value (CSV) file
  • Access to the filesystem of the host computer
  • Enabling SQL manipulation of data in statistics packages like R

1.1 Usage

A virtual table is created using using a CREATE VIRTUAL TABLE statement. This statement creates a table with a particular name and associates the table with a "module".

   CREATE VIRTUAL TABLE tablename USING modulename;

One can also provide comma-separated arguments to the module following the module name:

   CREATE VIRTUAL TABLE tablename USING modulename(arg1, arg2, ...);

The format of the arguments to the module is very general. Each argument can consist of keywords, string literals, identifiers, numbers, and punctuation. The arguments are passed as written (as text) into the constructor method of the virtual table implementation when the virtual table is created and that constructor is responsible for parsing and interpreting the arguments. The argument syntax is sufficiently general that a virtual table implementation can, if it wants to, interpret its arguments as column definitions in an ordinary CREATE TABLE statement. The implementation could also impose some other interpretation on the arguments.

Once a virtual table has been created, it can be used like any other table with the exceptions noted above and imposed by specific virtual table implementations. A virtual table is destroyed using the ordinary DROP TABLE syntax.

2.2 Implementation

Several new C-level objects are used by the virtual table implementation:

  typedef struct sqlite3_vtab sqlite3_vtab;
  typedef struct sqlite3_index_info sqlite3_index_info;
  typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
  typedef struct sqlite3_module sqlite3_module;

The sqlite3_module structure defines a module object used to implement a virtual table. Think of a module as a class from which one can construct multiple virtual tables having similar properties. For example, one might have a module that provides read-only access to comma-separated-value (CSV) files on disk. That one module can then be used to create several virtual tables where each virtual table refers to a different CSV file.

The module structure contains methods that are invoked by SQLite to perform various actions on the virtual table such as creating new instances of a virtual table or destroying old ones, reading and writing data, searching for and deleting, updating, or inserting rows. The module structure is explained in more detail below.

Each virtual table instance is represented by an sqlite3_vtab structure. The sqlite3_vtab structure looks like this:

  struct sqlite3_vtab {
    const sqlite3_module *pModule;
    int nRef;
    char *zErrMsg;
  };

Virtual table implementations will normally subclass this structure to add additional private and implementation-specific fields. The nRef field is used internally by the SQLite core and should not be altered by the virtual table implementation. The virtual table implementation may pass error message text to the core by putting an error message string in zErrMsg. Space to hold this error message string must be obtained from an SQLite memory allocation function such as sqlite3_mprintf() or sqlite3_malloc(). Prior to assigning a new value to zErrMsg, the virtual table implementation must free any preexisting content of zErrMsg using sqlite3_free(). Failure to do this will result in a memory leak. The SQLite core will free and zero the content of zErrMsg when it delivers the error message text to the client application or when it destroys the virtual table. The virtual table implementation only needs to worry about freeing the zErrMsg content when it overwrites the content with a new, different error message.

The sqlite3_vtab_cursor structure represents a pointer to a specific row of a virtual table. This is what an sqlite3_vtab_cursor looks like:

  struct sqlite3_vtab_cursor {
    sqlite3_vtab *pVtab;
  };

Once again, practical implementations will likely subclass this structure to add additional private fields.

The sqlite3_index_info structure is used to pass information into and out of the xBestIndex method of the module that implements a virtual table.

Before a CREATE VIRTUAL TABLE statement can be run, the module specified in that statement must be registered with the database connection. This is accomplished using either of the sqlite3_create_module() or sqlite3_create_module_v2() interfaces:

  int sqlite3_create_module(
    sqlite3 *db,               /* SQLite connection to register module with */
    const char *zName,         /* Name of the module */
    const sqlite3_module *,    /* Methods for the module */
    void *                     /* Client data for xCreate/xConnect */
  );
  int sqlite3_create_module_v2(
    sqlite3 *db,               /* SQLite connection to register module with */
    const char *zName,         /* Name of the module */
    const sqlite3_module *,    /* Methods for the module */
    void *,                    /* Client data for xCreate/xConnect */
    void(*xDestroy)(void*)     /* Client data destructor function */
  );

The sqlite3_create_module() and sqlite3_create_module_v2() routines associates a module name with an sqlite3_module structure and a separate client data that is specific to each module. The only difference between the two create_module methods is that the _v2 method includes an extra parameter that specifies a destructor for client data pointer. The module structure is what defines the behavior of a virtual table. The module structure looks like this:

  struct sqlite3_module {
    int iVersion;
    int (*xCreate)(sqlite3*, void *pAux,
                 int argc, char **argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xConnect)(sqlite3*, void *pAux,
                 int argc, char **argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
    int (*xDisconnect)(sqlite3_vtab *pVTab);
    int (*xDestroy)(sqlite3_vtab *pVTab);
    int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
    int (*xClose)(sqlite3_vtab_cursor*);
    int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                  int argc, sqlite3_value **argv);
    int (*xNext)(sqlite3_vtab_cursor*);
    int (*xEof)(sqlite3_vtab_cursor*);
    int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
    int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid);
    int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *);
    int (*xBegin)(sqlite3_vtab *pVTab);
    int (*xSync)(sqlite3_vtab *pVTab);
    int (*xCommit)(sqlite3_vtab *pVTab);
    int (*xRollback)(sqlite3_vtab *pVTab);
    int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
                       void **ppArg);
    int (*Rename)(sqlite3_vtab *pVtab, const char *zNew);
    /* The methods above are in version 1 of the sqlite_module object. Those
    ** below are for version 2 and greater. */
    int (*xSavepoint)(sqlite3_vtab *pVTab, int);
    int (*xRelease)(sqlite3_vtab *pVTab, int);
    int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
  };

The module structure defines all of the methods for each virtual table object. The module structure also contains the iVersion field which defines the particular edition of the module table structure. Currently, iVersion is always 1, but in future releases of SQLite the module structure definition might be extended with additional methods and in that case the iVersion value will be increased.

The rest of the module structure consists of methods used to implement various features of the virtual table. Details on what each of these methods do are provided in the sequel.

1.3 Virtual Tables And Shared Cache

Prior to SQLite version 3.6.17, the virtual table mechanism assumes that each database connection kept its own copy of the database schema. Hence, the virtual table mechanism could not be used in a database that has shared cache mode enabled. The sqlite3_create_module() interface would return an error if shared cache mode is enabled. That restriction was relaxed beginning with SQLite version 3.6.17.

1.4 Creating New Virtual Table Implementations

Follow these steps to create your own virtual table:

  1. Write all necessary methods.
  2. Create an instance of the sqlite3_module structure containing pointers to all the methods from step 1.
  3. Register your sqlite3_module structure using one of the sqlite3_create_module() or sqlite3_create_module_v2() interfaces.
  4. Run a CREATE VIRTUAL TABLE command that specifies the new module in the USING clause.

The only really hard part is step 1. You might want to start with an existing virtual table implementation and modify it to suit your needs. There are several virtual table implementations in the SQLite source tree (for testing purposes). You might use one of those as a guide. Locate these test virtual table implementations by searching for "sqlite3_create_module".

You might also want to implement your new virtual table as a loadable extension.

2.0 Virtual Table Methods

2.1 The xCreate Method

  int (*xCreate)(sqlite3 *db, void *pAux,
               int argc, char **argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);

This method is called to create a new instance of a virtual table in response to a CREATE VIRTUAL TABLE statement. The db parameter is a pointer to the SQLite database connection that is executing the CREATE VIRTUAL TABLE statement. The pAux argument is the copy of the client data pointer that was the fourth argument to the sqlite3_create_module() or sqlite3_create_module_v2() call that registered the virtual table module. The argv parameter is an array of argc pointers to null terminated strings. The first string, argv[0], is the name of the module being invoked. The module name is the name provided as the second argument to sqlite3_create_module() and as the argument to the USING clause of the CREATE VIRTUAL TABLE statement that is running. The second, argv[1], is the name of the database in which the new virtual table is being created. The database name is "main" for the primary database, or "temp" for TEMP database, or the name given at the end of the ATTACH statement for attached databases. The third element of the array, argv[2], is the name of the new virtual table, as specified following the TABLE keyword in the CREATE VIRTUAL TABLE statement. If present, the fourth and subsequent strings in the argv[] array report the arguments to the module name in the CREATE VIRTUAL TABLE statement.

The job of this method is to construct the new virtual table object (an sqlite3_vtab object) and return a pointer to it in *ppVTab.

As part of the task of creating a new sqlite3_vtab structure, this method must invoke sqlite3_declare_vtab() to tell the SQLite core about the columns and datatypes in the virtual table. The sqlite3_declare_vtab() API has the following prototype:

    int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable)

The first argument to sqlite3_declare_vtab() must be the same database connection pointer as the first parameter to this method. The second argument to sqlite3_declare_vtab() must a zero-terminated UTF-8 string that contains a well-formed CREATE TABLE statement that defines the columns in the virtual table and their data types. The name of the table in this CREATE TABLE statement is ignored, as are all constraints. Only the column names and datatypes matter. The CREATE TABLE statement string need not to be held in persistent memory. The string can be deallocated and/or reused as soon as the sqlite3_declare_vtab() routine returns.

The xCreate method need not initialize the pModule, nRef, and zErrMsg fields of the sqlite3_vtab object. The SQLite core will take care of that chore.

The xCreate must should return SQLITE_OK if it is successful in creating the new virtual table, or SQLITE_ERROR if it is not successful. If not successful, the sqlite3_vtab structure must not be allocated. An error message may optionally be returned in *pzErr if unsuccessful. Space to hold the error message string must be allocated using an SQLite memory allocation function like sqlite3_malloc() or sqlite3_mprintf() as the SQLite core will attempt to free the space using sqlite3_free() after the error has been reported up to the application.

The xCreate method is required for every virtual table implementation, though the xCreate and xConnect pointers of the sqlite3_module object may point to the same function the virtual table does not need to initialize backing store.

2.1.1 Hidden columns in virtual tables

If a column datatype contains the special keyword "HIDDEN" (in any combination of upper and lower case letters) then that keyword it is omitted from the column datatype name and the column is marked as a hidden column internally. A hidden column differs from a normal column in three respects:

  • Hidden columns are not listed in the dataset returned by "PRAGMA table_info",
  • Hidden columns are not included in the expansion of a "*" expression in the result set of a SELECT, and
  • Hidden columns are not included in the implicit column-list used by an INSERT statement that lacks an explicit column-list.

For example, if the following SQL is passed to sqlite3_declare_vtab():

   CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden);

Then the virtual table would be created with two hidden columns, and with datatypes of "VARCHAR(12)" and "INTEGER".

An example use of hidden columns can be seen in the FTS3 virtual table implementation, where every FTS virtual table contains an FTS hidden column that is used to pass information from the virtual table into FTS auxiliary functions and to the FTS MATCH operator.

2.2 The xConnect Method

  int (*xConnect)(sqlite3*, void *pAux,
               int argc, char **argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);

The xConnect method is very similar to xCreate. It has the same parameters and constructs a new sqlite3_vtab structure just like xCreate. And it must also call sqlite3_declare_vtab() like xCreate.

The difference is that xConnect is called to establish a new connection to an existing virtual table whereas xCreate is called to create a new virtual table from scratch.

The xCreate and xConnect methods are only different when the virtual table has some kind of backing store that must be initialized the first time the virtual table is created. The xCreate method creates and initializes the backing store. The xConnect method just connects to an existing backing store.

As an example, consider a virtual table implementation that provides read-only access to existing comma-separated-value (CSV) files on disk. There is no backing store that needs to be created or initialized for such a virtual table (since the CSV files already exist on disk) so the xCreate and xConnect methods will be identical for that module.

Another example is a virtual table that implements a full-text index. The xCreate method must create and initialize data structures to hold the dictionary and posting lists for that index. The xConnect method, on the other hand, only has to locate and use an existing dictionary and posting lists that were created by a prior xCreate call.

The xConnect method must return SQLITE_OK if it is successful in creating the new virtual table, or SQLITE_ERROR if it is not successful. If not successful, the sqlite3_vtab structure must not be allocated. An error message may optionally be returned in *pzErr if unsuccessful. Space to hold the error message string must be allocated using an SQLite memory allocation function like sqlite3_malloc() or sqlite3_mprintf() as the SQLite core will attempt to free the space using sqlite3_free() after the error has been reported up to the application.

The xConnect method is required for every virtual table implementation, though the xCreate and xConnect pointers of the sqlite3_module object may point to the same function the virtual table does not need to initialize backing store.

2.3 The xBestIndex Method

SQLite uses the xBestIndex method of a virtual table module to determine the best way to access the virtual table. The xBestIndex method has a prototype like this:

  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);

The SQLite core communicates with the xBestIndex method by filling in certain fields of the sqlite3_index_info structure and passing a pointer to that structure into xBestIndex as the second parameter. The xBestIndex method fills out other fields of this structure which forms the reply. The sqlite3_index_info structure looks like this:

  struct sqlite3_index_info {
    /* Inputs */
    const int nConstraint;     /* Number of entries in aConstraint */
    const struct sqlite3_index_constraint {
       int iColumn;              /* Column on left-hand side of constraint */
       unsigned char op;         /* Constraint operator */
       unsigned char usable;     /* True if this constraint is usable */
       int iTermOffset;          /* Used internally - xBestIndex should ignore */
    } *const aConstraint;      /* Table of WHERE clause constraints */
    const int nOrderBy;        /* Number of terms in the ORDER BY clause */
    const struct sqlite3_index_orderby {
       int iColumn;              /* Column number */
       unsigned char desc;       /* True for DESC.  False for ASC. */
    } *const aOrderBy;         /* The ORDER BY clause */

    /* Outputs */
    struct sqlite3_index_constraint_usage {
      int argvIndex;           /* if >0, constraint is part of argv to xFilter */
      unsigned char omit;      /* Do not code a test for this constraint */
    } *const aConstraintUsage;
    int idxNum;                /* Number used to identify the index */
    char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
    int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
    int orderByConsumed;       /* True if output is already ordered */
    double estimatedCost;      /* Estimated cost of using this index */
  };

In addition, there are some defined constants:

  #define SQLITE_INDEX_CONSTRAINT_EQ    2
  #define SQLITE_INDEX_CONSTRAINT_GT    4
  #define SQLITE_INDEX_CONSTRAINT_LE    8
  #define SQLITE_INDEX_CONSTRAINT_LT    16
  #define SQLITE_INDEX_CONSTRAINT_GE    32
  #define SQLITE_INDEX_CONSTRAINT_MATCH 64

The SQLite core calls the xBestIndex method when it is compiling a query that involves a virtual table. In other words, SQLite calls this method when it is running sqlite3_prepare() or the equivalent. By calling this method, the SQLite core is saying to the virtual table that it needs to access some subset of the rows in the virtual table and it wants to know the most efficient way to do that access. The xBestIndex method replies with information that the SQLite core can then use to conduct an efficient search of the virtual table.

While compiling a single SQL query, the SQLite core might call xBestIndex multiple times with different settings in sqlite3_index_info. The SQLite core will then select the combination that appears to give the best performance.

Before calling this method, the SQLite core initializes an instance of the sqlite3_index_info structure with information about the query that it is currently trying to process. This information derives mainly from the WHERE clause and ORDER BY or GROUP BY clauses of the query, but also from any ON or USING clauses if the query is a join. The information that the SQLite core provides to the xBestIndex method is held in the part of the structure that is marked as "Inputs". The "Outputs" section is initialized to zero.

The information in the sqlite3_index_info structure is ephemeral and may be overwritten or deallocated as soon as the xBestIndex method returns. If the xBestIndex method needs to remember any part of the sqlite3_index_info structure, it should make a copy. Care must be take to store the copy in a place where it will be deallocated, such as in the idxStr field with needToFreeIdxStr set to 1.

Note that xBestIndex will always be called before xFilter, since the idxNum and idxStr outputs from xBestIndex are required inputs to xFilter. However, there is no guarantee that xFilter will be called following a successful xBestIndex.

The xBestIndex method is required for every virtual table implementation.

2.3.1 Inputs

The main thing that the SQLite core is trying to communicate to the virtual table is the constraints that are available to limit the number of rows that need to be searched. The aConstraint[] array contains one entry for each constraint. There will be exactly nConstraint entries in that array.

Each constraint will correspond to a term in the WHERE clause or in a USING or ON clause that is of the form

column OP EXPR

Where "column" is a column in the virtual table, OP is an operator like "=" or "<", and EXPR is an arbitrary expression. So, for example, if the WHERE clause contained a term like this:

     a = 5

Then one of the constraints would be on the "a" column with operator "=" and an expression of "5". Constraints need not have a literal representation of the WHERE clause. The query optimizer might make transformations to the WHERE clause in order to extract as many constraints as it can. So, for example, if the WHERE clause contained something like this:

     x BETWEEN 10 AND 100 AND 999>y

The query optimizer might translate this into three separate constraints:

     x >= 10
     x <= 100
     y < 999

For each constraint, the aConstraint[].iColumn field indicates which column appears on the left-hand side of the constraint. The first column of the virtual table is column 0. The rowid of the virtual table is column -1. The aConstraint[].op field indicates which operator is used. The SQLITE_INDEX_CONSTRAINT_* constants map integer constants into operator values. Columns occur in the order they were defined by the call to sqlite3_declare_vtab() in the xCreate or xConnect method. Hidden columns are counted when determining the column index.

The aConstraint[] array contains information about all constraints that apply to the virtual table. But some of the constraints might not be usable because of the way tables are ordered in a join. The xBestIndex method must therefore only consider constraints that have an aConstraint[].usable flag which is true.

In addition to WHERE clause constraints, the SQLite core also tells the xBestIndex method about the ORDER BY clause. (In an aggregate query, the SQLite core might put in GROUP BY clause information in place of the ORDER BY clause information, but this fact should not make any difference to the xBestIndex method.) If all terms of the ORDER BY clause are columns in the virtual table, then nOrderBy will be the number of terms in the ORDER BY clause and the aOrderBy[] array will identify the column for each term in the order by clause and whether or not that column is ASC or DESC.

2.3.2 Outputs

Given all of the information above, the job of the xBestIndex method it to figure out the best way to search the virtual table.

The xBestIndex method fills the idxNum and idxStr fields with information that communicates an indexing strategy to the xFilter method. The information in idxNum and idxStr is arbitrary as far as the SQLite core is concerned. The SQLite core just copies the information through to the xFilter method. Any desired meaning can be assigned to idxNum and idxStr as long as xBestIndex and xFilter agree on what that meaning is.

The idxStr value may be a string obtained from an SQLite memory allocation function such as sqlite3_mprintf(). If this is the case, then the needToFreeIdxStr flag must be set to true so that the SQLite core will know to call sqlite3_free() on that string when it has finished with it, and thus avoid a memory leak.

If the virtual table will output rows in the order specified by the ORDER BY clause, then the orderByConsumed flag may be set to true. If the output is not automatically in the correct order then orderByConsumed must be left in its default false setting. This will indicate to the SQLite core that it will need to do a separate sorting pass over the data after it comes out of the virtual table.

The estimatedCost field should be set to the estimated number of disk access operations required to execute this query against the virtual table. The SQLite core will often call xBestIndex multiple times with different constraints, obtain multiple cost estimates, then choose the query plan that gives the lowest estimate.

The aConstraintUsage[] array contains one element for each of the nConstraint constraints in the inputs section of the sqlite3_index_info structure. The aConstraintUsage[] array is used by xBestIndex to tell the core how it is using the constraints.

The xBestIndex method may set aConstraintUsage[].argvIndex entries to values greater than one. Exactly one entry should be set to 1, another to 2, another to 3, and so forth up to as many or as few as the xBestIndex method wants. The EXPR of the corresponding constraints will then be passed in as the argv[] parameters to xFilter.

For example, if the aConstraint[3].argvIndex is set to 1, then when xFilter is called, the argv[0] passed to xFilter will have the EXPR value of the aConstraint[3] constraint.

By default, the SQLite core double checks all constraints on each row of the virtual table that it receives. If such a check is redundant, the xBestFilter method can suppress that double-check by setting aConstraintUsage[].omit.

2.4 The xDisconnect Method

  int (*xDisconnect)(sqlite3_vtab *pVTab);

This method releases a connection to a virtual table. Only the sqlite3_vtab object is destroyed. The virtual table is not destroyed and any backing store associated with the virtual table persists. This method undoes the work of xConnect.

This method is a destructor for a connection to the virtual table. Contrast this method with xDestroy. The xDestroy is a destructor for the entire virtual table.

The xDestroy method is required for every virtual table implementation, though it is acceptable for the xDisconnect and xDestroy methods to be the same function if that makes sense for the particular virtual table.

2.5 The xDestroy Method

  int (*xDestroy)(sqlite3_vtab *pVTab);

This method releases a connection to a virtual table, just like the xDisconnect method, and it also destroys the underlying table implementation. This method undoes the work of xCreate.

The xDisconnect method is called whenever a database connection that uses a virtual table is closed. The xDestroy method is only called when a DROP TABLE statement is executed against the virtual table.

The xDisconnect method is required for every virtual table implementation, though it is acceptable for the xDisconnect and xDestroy methods to be the same function if that makes sense for the particular virtual table.

2.6 The xOpen Method

  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);

The xOpen method creates a new cursor used for accessing (read and/or writing) a virtual table. A successful invocation of this method will allocate the memory for the sqlite3_vtab_cursor (or a subclass), initialize the new object, and make *ppCursor point to the new object. The successful call then returns SQLITE_OK.

For every successful call to this method, the SQLite core will later invoke the xClose method to destroy the allocated cursor.

The xOpen method need not initialize the pVtab field of the sqlite3_vtab_cursor structure. The SQLite core will take care of that chore automatically.

A virtual table implementation must be able to support an arbitrary number of simultaneously open cursors.

When initially opened, the cursor is in an undefined state. The SQLite core will invoke the xFilter method on the cursor prior to any attempt to position or read from the cursor.

The xOpen method is required for every virtual table implementation.

2.7 The xClose Method

  int (*xClose)(sqlite3_vtab_cursor*);

The xClose method closes a cursor previously opened by xOpen. The SQLite core will always call xClose once for each cursor opened using xOpen.

This method must release all resources allocated by the corresponding xOpen call. The routine will not be called again even if it returns an error. The SQLite core will not use the sqlite3_vtab_cursor again after it has been closed.

The xClose method is required for every virtual table implementation.

2.8 The xEof Method

  int (*xEof)(sqlite3_vtab_cursor*);

The xEof method must return false (zero) if the specified cursor currently points to a valid row of data, or true (non-zero) otherwise. This method is called by the SQL engine immediately after each xFilter and xNext invocation.

The xEof method is required for every virtual table implementation.

2.9 The xFilter Method

  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                int argc, sqlite3_value **argv);

This method begins a search of a virtual table. The first argument is a cursor opened by xOpen. The next two argument define a particular search index previously chosen by xBestIndex. The specific meanings of idxNum and idxStr are unimportant as long as xFilter and xBestIndex agree on what that meaning is.

The xBestIndex function may have requested the values of certain expressions using the aConstraintUsage[].argvIndex values of the sqlite3_index_info structure. Those values are passed to xFilter using the argc and argv parameters.

If the virtual table contains one or more rows that match the search criteria, then the cursor must be left point at the first row. Subsequent calls to xEof must return false (zero). If there are no rows match, then the cursor must be left in a state that will cause the xEof to return true (non-zero). The SQLite engine will use the xColumn and xRowid methods to access that row content. The xNext method will be used to advance to the next row.

This method must return SQLITE_OK if successful, or an sqlite error code if an error occurs.

The xFilter method is required for every virtual table implementation.

2.10 The xNext Method

  int (*xNext)(sqlite3_vtab_cursor*);

The xNext method advances a virtual table cursor to the next row of a result set initiated by xFilter. If the cursor is already pointing at the last row when this routine is called, then the cursor no longer points to valid data and a subsequent call to the xEof method must return true (non-zero). If the cursor is successfully advanced to another row of content, then subsequent calls to xEof must return false (zero).

This method must return SQLITE_OK if successful, or an sqlite error code if an error occurs.

The xNext method is required for every virtual table implementation.

2.11 The xColumn Method

  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);

The SQLite core invokes this method in order to find the value for the N-th column of the current row. N is zero-based so the first column is numbered 0. The xColumn method may return its result back to SQLite using one of the following interface:

  • sqlite3_result_blob()
  • sqlite3_result_double()
  • sqlite3_result_int()
  • sqlite3_result_int64()
  • sqlite3_result_null()
  • sqlite3_result_text()
  • sqlite3_result_text16()
  • sqlite3_result_text16le()
  • sqlite3_result_text16be()
  • sqlite3_result_zeroblob()

If the xColumn method implementation calls none of the functions above, then the value of the column defaults to an SQL NULL.

To raise an error, the xColumn method should use one of the result_text() methods to set the error message text, then return an appropriate error code. The xColumn method must return SQLITE_OK on success.

The xColumn method is required for every virtual table implementation.

2.12 The xRowid Method

  int (*xRowid)(sqlite3_vtab_cursor *pCur, sqlite_int64 *pRowid);

A successful invocation of this method will cause *pRowid to be filled with the rowid of row that the virtual table cursor pCur is currently pointing at. This method returns SQLITE_OK on success. It returns an appropriate error code on failure.

The xRowid method is required for every virtual table implementation.

2.13 The xUpdate Method

  int (*xUpdate)(
    sqlite3_vtab *pVTab,
    int argc,
    sqlite3_value **argv,
    sqlite_int64 *pRowid
  );

All changes to a virtual table are made using the xUpdate method. This one method can be used to insert, delete, or update.

The argc parameter specifies the number of entries in the argv array. The value of argc will be 1 for a pure delete operation or N+2 for an insert or replace or update where N is the number of columns in the table. In the previous sentence, N includes any hidden columns.

Every argv entry will have a non-NULL value in C but may contain the SQL value NULL. In other words, it is always true that argv[i]!=0 for i between 0 and argc-1. However, it might be the case that sqlite3_value_type(argv[i])==SQLITE_NULL.

The argv[0] parameter is the rowid of a row in the virtual table to be deleted. If argv[0] is an SQL NULL, then no deletion occurs.

The argv[1] parameter is the rowid of a new row to be inserted into the virtual table. If argv[1] is an SQL NULL, then the implementation must choose a rowid for the newly inserted row. Subsequent argv[] entries contain values of the columns of the virtual table, in the order that the columns were declared. The number of columns will match the table declaration that the xConnect or xCreate method made using the sqlite3_declare_vtab() call. All hidden columns are included.

When doing an insert without a rowid (argc>1, argv[1] is an SQL NULL), the implementation must set *pRowid to the rowid of the newly inserted row; this will become the value returned by the sqlite3_last_insert_rowid() function. Setting this value in all the other cases is a harmless no-op; the SQLite engine ignores the *pRowid return value if argc==1 or argv[1] is not an SQL NULL.

Each call to xUpdate will fall into one of cases shown below. Not that references to argv[i] mean the SQL value held within the argv[i] object, not the argv[i] object itself.

argc = 1

The single row with rowid equal to argv[0] is deleted. No insert occurs.

argc > 1
argv[0] = NULL

A new row is inserted with a rowid argv[1] and column values in argv[2] and following. If argv[1] is an SQL NULL, the a new unique rowid is generated automatically.

argc > 1
argv[0] ≠ NULL
argv[0] = argv[1]

The row with rowid argv[0] is updated with new values in argv[2] and following parameters.

argc > 1
argv[0] ≠ NULL
argv[0] ≠ argv[1]

The row with rowid argv[0] is updated with rowid argv[1] and new values in argv[2] and following parameters. This will occur when an SQL statement updates a rowid, as in the statement:

UPDATE table SET rowid=rowid+1 WHERE ...;

The xUpdate method must return SQLITE_OK if and only if it is successful. If a failure occurs, the xUpdate must return an appropriate error code. On a failure, the pVTab->zErrMsg element may optionally be replaced with error message text stored in memory allocated from SQLite using functions such as sqlite3_mprintf() or sqlite3_malloc().

If the xUpdate method violates some constraint of the virtual table (including, but not limited to, attempting to store a value of the wrong datatype, attempting to store a value that is too large or too small, or attempting to change a read-only value) then the xUpdate must fail with an appropriate error code.

There might be one or more sqlite3_vtab_cursor objects open and in use on the virtual table instance and perhaps even on the row of the virtual table when the xUpdate method is invoked. The implementation of xUpdate must be prepared for attempts to delete or modify rows of the table out from other existing cursors. If the virtual table cannot accommodate such changes, the xUpdate method must return an error code.

The xUpdate method is optional. If the xUpdate pointer in the sqlite3_module for a virtual table is a NULL pointer, then the virtual table is read-only.

2.14 The xFindFunction Method

  int (*xFindFunction)(
    sqlite3_vtab *pVtab,
    int nArg,
    const char *zName,
    void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
    void **ppArg
  );

This method is called during sqlite3_prepare() to give the virtual table implementation an opportunity to overload functions. This method may be set to NULL in which case no overloading occurs.

When a function uses a column from a virtual table as its first argument, this method is called to see if the virtual table would like to overload the function. The first three parameters are inputs: the virtual table, the number of arguments to the function, and the name of the function. If no overloading is desired, this method returns 0. To overload the function, this method writes the new function implementation into *pxFunc and writes user data into *ppArg and returns 1.

Note that infix functions (LIKE, GLOB, REGEXP, and MATCH) reverse the order of their arguments. So "like(A,B)" is equivalent to "B like A". For the form "B like A" the B term is considered the first argument to the function. But for "like(A,B)" the A term is considered the first argument.

The function pointer returned by this routine must be valid for the lifetime of the sqlite3_vtab object given in the first parameter.

2.15 The xBegin Method

  int (*xBegin)(sqlite3_vtab *pVTab);

This method begins a transaction on a virtual table. This is method is optional. The xBegin pointer of sqlite3_module may be NULL.

This method is always followed by one call to either the xCommit or xRollback method. Virtual table transactions do not nest, so the xBegin method will not be invoked more than once on a single virtual table without an intervening call to either xCommit or xRollback. Multiple calls to other methods can and likely will occur in between the xBegin and the corresponding xCommit or xRollback.

2.16 The xSync Method

  int (*xSync)(sqlite3_vtab *pVTab);

This method signals the start of a two-phase commit on a virtual table. This is method is optional. The xSync pointer of sqlite3_module may be NULL.

This method is only invoked after call to the xBegin method and prior to an xCommit or xRollback. In order to implement two-phase commit, the xSync method on all virtual tables is invoked prior to invoking the xCommit method on any virtual table. If any of the xSync methods fail, the entire transaction is rolled back.

2.17 The xCommit Method

  int (*xCommit)(sqlite3_vtab *pVTab);

This method causes a virtual table transaction to commit. This is method is optional. The xCommit pointer of sqlite3_module may be NULL.

A call to this method always follows a prior call to xBegin and xSync.

2.18 The xRollback Method

  int (*xRollback)(sqlite3_vtab *pVTab);

This method causes a virtual table transaction to rollback. This is method is optional. The xRollback pointer of sqlite3_module may be NULL.

A call to this method always follows a prior call to xBegin.

2.19 The xRename Method

  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);

This method provides notification that the virtual table implementation that the virtual table will be given a new name. If this method returns SQLITE_OK then SQLite renames the table. If this method returns an error code then the renaming is prevented.

The xRename method is required for every virtual table implementation.

2.20 The xSavepoint, xRelease, and xRollbackTo Methods

  int (*xSavepoint)(sqlite3_vtab *pVtab, int);
  int (*xRelease)(sqlite3_vtab *pVtab, int);
  int (*xRollbackTo)(sqlite3_vtab *pVtab, int);

These methods provide the virtual table implementation an opportunity to implement nested transactions. They are always optional and will only be called in SQLite version 3.7.7 and later.

When xSavepoint(X,N) is invoked, that is a signal to the virtual table X that it should save its current state as savepoint N. A subsequent call to xRollbackTo(X,R) means that the state of the virtual table should return to what it was when xSavepoint(X,R) was last called. The call to xRollbackTo(X,R) will invalidate all savepoints with N>R; none of the invalided savepoints will be rolled back or released without first being reinitialized by a call to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints where N>=M.

None of the xSavepoint(), xRelease(), or xRollbackTo() methods will ever be called except in between calls to xBegin() and either xCommit() or xRollback().


Write-Ahead Logging

The default method by which SQLite implements atomic commit and rollback is a rollback journal. Beginning with version 3.7.0, a new "Write-Ahead Log" option (hereafter referred to as "WAL") is available.

There are advantages and disadvantages to using WAL instead of a rollback journal. Advantages include:

  1. WAL is significantly faster in most scenarios.
  2. WAL provides more concurrency as readers do not block writers and a writer does not block readers. Reading and writing can proceed concurrently.
  3. Disk I/O operations tends to be more sequential using WAL.
  4. WAL uses many fewer fsync() operations and is thus less vulnerable to problems on systems where the fsync() system call is broken.

But there are also disadvantages:

  1. WAL normally requires that the VFS support shared-memory primitives. (Exception: WAL without shared memory) The built-in unix and windows VFSes support this but third-party extension VFSes for custom operating systems might not.
  2. All processes using a database must be on the same host computer; WAL does not work over a network filesystem.
  3. Transactions that involve changes against multiple ATTACHed databases are atomic for each individual database, but are not atomic across all databases as a set.
  4. It is not possible to change the database page size after entering WAL mode, either on an empty database or by using VACUUM or by restoring from a backup using the backup API. You must be in a rollback journal mode to change the page size.
  5. It is not possible to open read-only WAL databases. The opening process must have write privileges for "-shm" wal-index shared memory file associated with the database, if that file exists, or else write access on the directory containing the database file if the "-shm" file does not exist.
  6. WAL might be very slightly slower (perhaps 1% or 2% slower) than the traditional rollback-journal approach in applications that do mostly reads and seldom write.
  7. There is an additional quasi-persistent "-wal" file and "-shm shared memory file associated with each database, which can make SQLite less appealing for use as an application file-format.
  8. There is the extra operation of checkpointing which, though automatic by default, is still something that application developers need to be mindful of.
  9. WAL works best with smaller transactions. WAL does not work well for very large transactions. For transactions larger than about 100 megabytes, traditional rollback journal modes will likely be faster. For transactions in excess of a gigabyte, WAL mode may fail with an I/O or disk-full error. It is recommended that one of the rollback journal modes be used for transactions larger than a few dozen megabytes.

How WAL Works

The traditional rollback journal works by writing a copy of the original unchanged database content into a separate rollback journal file and then writing changes directly into the database file. In the event of a crash or ROLLBACK, the original content contained in the rollback journal is played back into the database file to revert the database file to its original state. The COMMIT occurs when the rollback journal is deleted.

The WAL approach inverts this. The original content is preserved in the database file and the changes are appended into a separate WAL file. A COMMIT occurs when a special record indicating a commit is appended to the WAL. Thus a COMMIT can happen without ever writing to the original database, which allows readers to continue operating from the original unaltered database while changes are simultaneously being committed into the WAL. Multiple transactions can be appended to the end of a single WAL file.

Checkpointing

Of course, one wants to eventually transfer all the transactions that are appended in the WAL file back into the original database. Moving the WAL file transactions back into the database is called a "checkpoint".

Another way to think about the difference between rollback and write-ahead log is that in the rollback-journal approach, there are two primitive operations, reading and writing, whereas with a write-ahead log there are now three primitive operations: reading, writing, and checkpointing.

By default, SQLite does a checkpoint automatically when the WAL file reaches a threshold size of 1000 pages. (The SQLITE_DEFAULT_WAL_AUTOCHECKPOINT compile-time option can be used to specify a different default.) Applications using WAL do not have to do anything in order to for these checkpoints to occur. But if they want to, applications can adjust the automatic checkpoint threshold. Or they can turn off the automatic checkpoints and run checkpoints during idle moments or in a separate thread or process.

Concurrency

When a read operation begins on a WAL-mode database, it first remembers the location of the last valid commit record in the WAL. Call this point the "end mark". Because the WAL can be growing and adding new commit records while various readers connect to the database, each reader can potentially have its own end mark. But for any particular reader, the end mark is unchanged for the duration of the transaction, thus ensuring that a single read transaction only sees the database content as it existed at a single point in time.

When a reader needs a page of content, it first checks the WAL to see if that page appears there, and if so it pulls in the last copy of the page that occurs in the WAL prior to the reader's end mark. If no copy of the page exists in the WAL prior to the reader's end mark, then the page is read from the original database file. Readers can exist in separate processes, so to avoid forcing every reader to scan the entire WAL looking for pages (the WAL file can grow to multiple megabytes, depending on how often checkpoints are run), a data structure called the "wal-index" is maintained in shared memory which helps readers locate pages in the WAL quickly and with a minimum of I/O. The wal-index greatly improves the performance of readers, but the use of shared memory means that all readers must exist on the same machine. This is why the write-ahead log implementation will not work on a network filesystem.

Writers merely append new content to the end of the WAL file. Because writers do nothing that would interfere with the actions of readers, writers and readers can run at the same time. However, since there is only one WAL file, there can only be one writer at a time.

A checkpoint operation takes content from the WAL file and transfers it back into the original database file. A checkpoint can run concurrently with readers, however the checkpoint must stop when it reaches a page in the WAL that is past the read mark of any current reader. The checkpoint has to stop at that point because otherwise it might overwrite part of the database file that the reader is actively using. The checkpoint remembers (in the wal-index) how far it got and will resume transferring content from the WAL to the database from where it left off on the next invocation.

Thus a long-running read transaction can prevent a checkpointer from making progress. But presumably every read transactions will eventually end and the checkpointer will be able to continue.

Whenever a write operation occurs, the writer checks how much progress the checkpointer has made, and if the entire WAL has been transferred into the database and synced and if no readers are making use of the WAL, then the writer will rewind the WAL back to the beginning and start putting new transactions at the beginning of the WAL. This mechanism prevents a WAL file from growing without bound.

Performance Considerations

Write transactions are very fast since they only involve writing the content once (versus twice for rollback-journal transactions) and because the writes are all sequential. Further, syncing the content to the disk is not required, as long as the application is willing to sacrifice durability following a power loss or hard reboot. (Writers sync the WAL on every transaction commit if PRAGMA synchronous is set to FULL but omit this sync if PRAGMA synchronous is set to NORMAL.)

On the other hand, read performance deteriorates as the WAL file grows in size since each reader must check the WAL file for the content and the time needed to check the WAL file is proportional to the size of the WAL file. The wal-index helps find content in the WAL file much faster, but performance still falls off with increasing WAL file size. Hence, to maintain good read performance it is important to keep the WAL file size down by running checkpoints at regular intervals.

Checkpointing does require sync operations in order to avoid the possibility of database corruption following a power loss or hard reboot. The WAL must be synced to persistent storage prior to moving content from the WAL into the database and the database file must by synced prior to resetting the WAL. Checkpoint also requires more seeking. The checkpointer makes an effort to do as many sequential page writes to the database as it can (the pages are transferred from WAL to database in ascending order) but even then there will typically be many seek operations interspersed among the page writes. These factors combine to make checkpoints slower than write transactions.

The default strategy is to allow successive write transactions to grow the WAL until the WAL becomes about 1000 pages in size, then to run a checkpoint operation for each subsequent COMMIT until the WAL is reset to be smaller than 1000 pages. By default, the checkpoint will be run automatically by the same thread that does the COMMIT that pushes the WAL over its size limit. This has the effect of causing most COMMIT operations to be very fast but an occasional COMMIT (those that trigger a checkpoint) to be much slower. If that effect is undesirable, then the application can disable automatic checkpointing and run the periodic checkpoints in a separate thread, or separate process. (Links to commands and interfaces to accomplish this are shown below.)

Note that with PRAGMA synchronous set to NORMAL, the checkpoint is the only operation to issue an I/O barrier or sync operation (fsync() on unix or FlushFileBuffers() on windows). If an application therefore runs checkpoint in a separate thread or process, the main thread or process that is doing database queries and updates will never block on a sync operation. This helps to prevent "latch-up" in applications running on a busy disk drive. The downside to this configuration is that transactions are no longer durable and might rollback following a power failure or hard reset.

Notice too that there is a tradeoff between average read performance and average write performance. To maximize the read performance, one wants to keep the WAL as small as possible and hence run checkpoints frequently, perhaps as often as every COMMIT. To maximize write performance, one wants to amortize the cost of each checkpoint over as many writes as possible, meaning that one wants to run checkpoints infrequently and let the WAL grow as large as possible before each checkpoint. The decision of how often to run checkpoints may therefore vary from one application to another depending on the relative read and write performance requirements of the application. The default strategy is to run a checkpoint once the WAL reaches 1000 pages and this strategy seems to work well in test applications on workstations, but other strategies might work better on different platforms or for different workloads.

Activating And Configuring WAL Mode

An SQLite database connection defaults to journal_mode=DELETE. To convert to WAL mode, use the following pragma:

PRAGMA journal_mode=WAL;

The journal_mode pragma returns a string which is the new journal mode. On success, the pragma will return the string "wal". If the conversion to WAL could not be completed (for example, if the VFS does not support the necessary shared-memory primitives) then the journaling mode will be unchanged and the string returned from the primitive will be the prior journaling mode (for example "delete").

Automatic Checkpoint

By default, SQLite will automatically checkpoint whenever a COMMIT occurs that causes the WAL file to be 1000 pages or more in size, or when the last database connection on a database file closes. The default configuration is intended to work well for most applications. But programs that want more control can force a checkpoint using the wal_checkpoint pragma or by calling the sqlite3_wal_checkpoint() C interface. The automatic checkpoint threshold can be changed or automatic checkpointing can be completely disabled using the wal_autocheckpoint pragma or by calling the sqlite3_wal_autocheckpoint() C interface. A program can also use sqlite3_wal_hook() to register a callback to be invoked whenever any transaction commits to the WAL. This callback can then invoke sqlite3_wal_checkpoint() to for a checkpoint based on whatever criteria it thinks is appropriate. (The automatic checkpoint mechanism is implemented as a simple wrapper around sqlite3_wal_hook().)

Persistence of WAL mode

Unlike the other journaling modes, PRAGMA journal_mode=WAL is persistent. If a process sets WAL mode, then closes and reopens the database, the database will come back in WAL mode. In contrast, if a process sets (for example) PRAGMA journal_mode=TRUNCATE and then closes and reopens the database will come back up in the default rollback mode of DELETE rather than the previous TRUNCATE setting.

The persistence of WAL mode means that applications can be converted to using SQLite in WAL mode without making any changes to the application itself. One has merely to run "PRAGMA journal_mode=WAL;" on the database file(s) using the command-line shell or other utility, then restart the application.

The WAL journal mode will be set on all connections to the same database file if it is set on any one connection.

Read-Only Databases

No SQLite database (regardless of whether or not it is WAL mode) is readable if it is located on read-only media and it requires recovery. So, for example, if an application crashes and leaves an SQLite database with a hot journal, that database cannot be opened unless the opening process has write privilege on the database file, the directory containing the database file, and the hot journal. This is because the incomplete transaction left over from the crash must be rolled back prior to reading the database and that rollback cannot occur without write permission on all files and the directory containing them.

A database in WAL mode cannot generally be opened from read-only media because even ordinary reads in WAL mode require recovery-like operations.

An efficient implementation of the WAL read algorithm requires that there exist a hash table in shared memory over the content of the WAL file. This hash table is called the wal-index. The wal-index is in shared memory, and so technically it does not have to have a name in the host computer filesystem. Custom VFS implementations are free to implement shared memory in any way they see fit, but the default unix and windows drivers that come built-in with SQLite implement shared memory using mmapped files named using the suffix "-shm" and located in the same directory as the database file. The wal-index must be rebuilt upon first access, even by readers, and so in order to open the WAL database, write access is required on the "-shm" shared memory file if the file exists, or else write access is required on the directory containing the database so that the wal-index can be created if it does not already exist. This does not preclude custom VFS implementations that implement shared memory differently from being able to access read-only WAL databases, but it does prevent the default unix and windows backends from accessing WAL databases on read-only media.

Hence, SQLite databases should always be converted to PRAGMA journal_mode=DELETE prior to being transferred to read-only media.

Also, if multiple processes are to access a WAL mode database, then all processes should run under user or group IDs that give them write access to the database files, the WAL file, the shared memory -shm file, and the containing directory.

Implementation Of Shared-Memory For The WAL-Index

The wal-index is implemented using an ordinary file that is mmapped for robustness. Early (pre-release) implementations of WAL mode stored the wal-index in volatile shared-memory, such as files created in /dev/shm on Linux or /tmp on other unix systems. The problem with that approach is that processes with a different root directory (changed via chroot) will see different files and hence use different shared memory areas, leading to database corruption. Other methods for creating nameless shared memory blocks are not portable across the various flavors of unix. And we could not find any method to create nameless shared memory blocks on windows. The only way we have found to guarantee that all processes accessing the same database file use the same shared memory is to create the shared memory by mmapping a file in the same directory as the database itself.

Using an ordinary disk file to provide shared memory has the disadvantage that it might actually do unnecessary disk I/O by writing the shared memory to disk. However, the developers do not think this is a major concern since the wal-index rarely exceeds 32 KiB in size and is never synced. Furthermore, the wal-index backing file is deleted when the last database connection disconnects, which often prevents any real disk I/O from ever happening.

Specialized applications for which the default implementation of shared memory is unacceptable can devise alternative methods via a custom VFS. For example, if it is known that a particular database will only be accessed by threads within a single process, the wal-index can be implemented using heap memory instead of true shared memory.

Use of WAL Without Shared-Memory

Beginning in SQLite version 3.7.4, WAL databases can be created, read, and written even if shared memory is unavailable as long as the locking_mode is set to EXCLUSIVE before the first attempted access. In other words, a process can interact with a WAL database without using shared memory if that process is guaranteed to be the only process accessing the database. This feature allows WAL databases to be created, read, and written by legacy VFSes that lack the "version 2" shared-memory methods xShmMap, xShmLock, xShmBarrier, and xShmUnmap on the sqlite3_io_methods object.

If EXCLUSIVE locking mode is set prior to the first WAL-mode database access, then SQLite never attempts to call any of the shared-memory methods and hence no shared-memory wal-index is ever created. In that case, the database connection remains in EXCLUSIVE mode as long as the journal mode is WAL; attempts to change the locking mode using "PRAGMA locking_mode=NORMAL;" are no-ops. The only way to change out of EXCLUSIVE locking mode is to first change out of WAL journal mode.

If NORMAL locking mode is in effect for the first WAL-mode database access, then the shared-memory wal-index is created. This means that the underlying VFS must support the "version 2" shared-memory. If the VFS does not support shared-memory methods, then the attempt to open a database that is already in WAL mode, or the attempt convert a database into WAL mode, will fail. As long a connection is using a shared-memory wal-index, the locking mode can be changed freely between NORMAL and EXCLUSIVE. It is only when the shared-memory wal-index is omitted, when the locking mode is EXCLUSIVE prior to the first WAL-mode database access, that the locking mode is stuck in EXCLUSIVE.

Backwards Compatibility

The database file format is unchanged for WAL mode. However, the WAL file and the wal-index are new concepts and so older versions of SQLite will not know how to recover a crashed SQLite database that was operating in WAL mode when the crash occurred. To prevent older versions of SQLite from trying to recover a WAL-mode database (and making matters worse) the database file format version numbers (bytes 18 and 19 in the database header) are increased from 1 to 2 in WAL mode. Thus, if an older version of SQLite attempts to connect to an SQLite database that is operating in WAL mode, it will report an error along the lines of "file is encrypted or is not a database".

One can explicitly change out of WAL mode using a pragma such as this:

PRAGMA journal_mode=DELETE;

Deliberately changing out of WAL mode changes the database file format version numbers back to 1 so that older versions of SQLite can once again access the database file.


Appropriate Uses For SQLite

SQLite is different from most other SQL database engines in that its primary design goal is to be simple:

  • Simple to administer
  • Simple to operate
  • Simple to embed in a larger program
  • Simple to maintain and customize

Many people like SQLite because it is small and fast. But those qualities are just happy accidents. Users also find that SQLite is very reliable. Reliability is a consequence of simplicity. With less complication, there is less to go wrong. So, yes, SQLite is small, fast, and reliable, but first and foremost, SQLite strives to be simple.

Simplicity in a database engine can be either a strength or a weakness, depending on what you are trying to do. In order to achieve simplicity, SQLite has had to sacrifice other characteristics that some people find useful, such as high concurrency, fine-grained access control, a rich set of built-in functions, stored procedures, esoteric SQL language features, XML and/or Java extensions, tera- or peta-byte scalability, and so forth. If you need some of these features and do not mind the added complexity that they bring, then SQLite is probably not the database for you. SQLite is not intended to be an enterprise database engine. It is not designed to compete with Oracle or PostgreSQL.

The basic rule of thumb for when it is appropriate to use SQLite is this: Use SQLite in situations where simplicity of administration, implementation, and maintenance are more important than the countless complex features that enterprise database engines provide. As it turns out, situations where simplicity is the better choice are more common than many people realize.

Another way to look at SQLite is this: SQLite is not designed to replace Oracle. It is designed to replace fopen().

Situations Where SQLite Works Well

  • Application File Format

    SQLite has been used with great success as the on-disk file format for desktop applications such as financial analysis tools, CAD packages, record keeping programs, and so forth. The traditional File/Open operation does an sqlite3_open() and executes a BEGIN TRANSACTION to get exclusive access to the content. File/Save does a COMMIT followed by another BEGIN TRANSACTION. The use of transactions guarantees that updates to the application file are atomic, durable, isolated, and consistent.

    Temporary triggers can be added to the database to record all changes into a (temporary) undo/redo log table. These changes can then be played back when the user presses the Undo and Redo buttons. Using this technique, an unlimited depth undo/redo implementation can be written in surprisingly little code.

  • Embedded devices and applications

    Because an SQLite database requires little or no administration, SQLite is a good choice for devices or services that must work unattended and without human support. SQLite is a good fit for use in cellphones, PDAs, set-top boxes, and/or appliances. It also works well as an embedded database in downloadable consumer applications.

  • Websites

    SQLite usually will work great as the database engine for low to medium traffic websites (which is to say, 99.9% of all websites). The amount of web traffic that SQLite can handle depends, of course, on how heavily the website uses its database. Generally speaking, any site that gets fewer than 100K hits/day should work fine with SQLite. The 100K hits/day figure is a conservative estimate, not a hard upper bound. SQLite has been demonstrated to work with 10 times that amount of traffic.

  • Replacement for ad hoc disk files

    Many programs use fopen(), fread(), and fwrite() to create and manage files of data in home-grown formats. SQLite works particularly well as a replacement for these ad hoc data files.

  • Internal or temporary databases

    For programs that have a lot of data that must be sifted and sorted in diverse ways, it is often easier and quicker to load the data into an in-memory SQLite database and use queries with joins and ORDER BY clauses to extract the data in the form and order needed rather than to try to code the same operations manually. Using an SQL database internally in this way also gives the program greater flexibility since new columns and indices can be added without having to recode every query.

  • Command-line dataset analysis tool

    Experienced SQL users can employ the command-line sqlite program to analyze miscellaneous datasets. Raw data can be imported from CSV files, then that data can be sliced and diced to generate a myriad of summary reports. Possible uses include website log analysis, sports statistics analysis, compilation of programming metrics, and analysis of experimental results.

    You can also do the same thing with an enterprise client/server database, of course. The advantages to using SQLite in this situation are that SQLite is much easier to set up and the resulting database is a single file that you can store on a floppy disk or flash-memory stick or email to a colleague.

  • Stand-in for an enterprise database during demos or testing

    If you are writing a client application for an enterprise database engine, it makes sense to use a generic database backend that allows you to connect to many different kinds of SQL database engines. It makes even better sense to go ahead and include SQLite in the mix of supported databases and to statically link the SQLite engine in with the client. That way the client program can be used standalone with an SQLite data file for testing or for demonstrations.

  • Database Pedagogy

    Because it is simple to setup and use (installation is trivial: just copy the sqlite or sqlite.exe executable to the target machine and run it) SQLite makes a good database engine for use in teaching SQL. Students can easily create as many databases as they like and can email databases to the instructor for comments or grading. For more advanced students who are interested in studying how an RDBMS is implemented, the modular and well-commented and documented SQLite code can serve as a good basis. This is not to say that SQLite is an accurate model of how other database engines are implemented, but rather a student who understands how SQLite works can more quickly comprehend the operational principles of other systems.

  • Experimental SQL language extensions

    The simple, modular design of SQLite makes it a good platform for prototyping new, experimental database language features or ideas.

Situations Where Another RDBMS May Work Better

  • Client/Server Applications

    If you have many client programs accessing a common database over a network, you should consider using a client/server database engine instead of SQLite. SQLite will work over a network filesystem, but because of the latency associated with most network filesystems, performance will not be great. Also, the file locking logic of many network filesystems implementation contains bugs (on both Unix and Windows). If file locking does not work like it should, it might be possible for two or more client programs to modify the same part of the same database at the same time, resulting in database corruption. Because this problem results from bugs in the underlying filesystem implementation, there is nothing SQLite can do to prevent it.

    A good rule of thumb is that you should avoid using SQLite in situations where the same database will be accessed simultaneously from many computers over a network filesystem.

  • High-volume Websites

    SQLite will normally work fine as the database backend to a website. But if you website is so busy that you are thinking of splitting the database component off onto a separate machine, then you should definitely consider using an enterprise-class client/server database engine instead of SQLite.

  • Very large datasets

    With the default page size of 1024 bytes, an SQLite database is limited in size to 2 terabytes (241 bytes). And even if it could handle larger databases, SQLite stores the entire database in a single disk file and many filesystems limit the maximum size of files to something less than this. So if you are contemplating databases of this magnitude, you would do well to consider using a client/server database engine that spreads its content across multiple disk files, and perhaps across multiple volumes.

  • High Concurrency

    SQLite uses reader/writer locks on the entire database file. That means if any process is reading from any part of the database, all other processes are prevented from writing any other part of the database. Similarly, if any one process is writing to the database, all other processes are prevented from reading any other part of the database. For many situations, this is not a problem. Each application does its database work quickly and moves on, and no lock lasts for more than a few dozen milliseconds. But there are some applications that require more concurrency, and those applications may need to seek a different solution.


Zero-Configuration

Choose any three.
About Sitemap Documentation Download License News Support

SQLite Is A Zero-Configuration Database

SQLite does not need to be "installed" before it is used. There is no "setup" procedure. There is no server process that needs to be started, stopped, or configured. There is no need for an administrator to create a new database instance or assign access permissions to users. SQLite uses no configuration files. Nothing needs to be done to tell the system that SQLite is running. No actions are required to recover after a system crash or power failure. There is nothing to troubleshoot.

SQLite just works.

Other database engines may run great once you get them going. But doing the initial installation and configuration can often be intimidating.


Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Obtain Aggregate Function Context

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

Implementations of aggregate SQL functions use this routine to allocate memory for storing their state.

The first time the sqlite3_aggregate_context(C,N) routine is called for a particular aggregate function, SQLite allocates N of memory, zeroes out that memory, and returns a pointer to the new memory. On second and subsequent calls to sqlite3_aggregate_context() for the same aggregate function instance, the same buffer is returned. Sqlite3_aggregate_context() is normally called once for each invocation of the xStep callback and then one last time when the xFinal callback is invoked. When no rows match an aggregate query, the xStep() callback of the aggregate function implementation is never called and xFinal() is called exactly once. In those cases, sqlite3_aggregate_context() might be called for the first time from within xFinal().

The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is less than or equal to zero or if a memory allocate error occurs.

The amount of space allocated by sqlite3_aggregate_context(C,N) is determined by the N parameter on first successful call. Changing the value of N in subsequent call to sqlite3_aggregate_context() within the same aggregate function instance will not resize the memory allocation.

SQLite automatically frees the memory allocated by sqlite3_aggregate_context() when the aggregate query concludes.

The first parameter must be a copy of the SQL function context that is the first parameter to the xStep or xFinal callback routine that implements the aggregate function.

This routine must be called from the same thread in which the aggregate SQL function is running.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Deprecated Functions

#ifndef SQLITE_OMIT_DEPRECATED
int sqlite3_aggregate_count(sqlite3_context*);
int sqlite3_expired(sqlite3_stmt*);
int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
int sqlite3_global_recover(void);
void sqlite3_thread_cleanup(void);
int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
#endif

These functions are deprecated. In order to maintain backwards compatibility with older code, these functions continue to be supported. However, new applications should avoid the use of these functions. To help encourage people to avoid using these functions, we are not going to tell you what they do.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Automatically Load Statically Linked Extensions

int sqlite3_auto_extension(void (*xEntryPoint)(void));

This interface causes the xEntryPoint() function to be invoked for each new database connection that is created. The idea here is that xEntryPoint() is the entry point for a statically linked SQLite extension that is to be automatically loaded into all new database connections.

Even though the function prototype shows that xEntryPoint() takes no arguments and returns void, SQLite invokes xEntryPoint() with three arguments and expects and integer result as if the signature of the entry point where as follows:

   int xEntryPoint(
     sqlite3 *db,
     const char **pzErrMsg,
     const struct sqlite3_api_routines *pThunk
   );

If the xEntryPoint routine encounters an error, it should make *pzErrMsg point to an appropriate error message (obtained from sqlite3_mprintf()) and return an appropriate error code. SQLite ensures that *pzErrMsg is NULL before calling the xEntryPoint(). SQLite will invoke sqlite3_free() on *pzErrMsg after xEntryPoint() returns. If any xEntryPoint() returns an error, the sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() call that provoked the xEntryPoint() will fail.

Calling sqlite3_auto_extension(X) with an entry point X that is already on the list of automatic extensions is a harmless no-op. No entry point will be called more than once for each database connection that is opened.

See also: sqlite3_reset_auto_extension().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Online Backup Object

typedef struct sqlite3_backup sqlite3_backup;

The sqlite3_backup object records state information about an ongoing online backup operation. The sqlite3_backup object is created by a call to sqlite3_backup_init() and is destroyed by a call to sqlite3_backup_finish().

See Also: Using the SQLite Online Backup API

See also lists of Objects, Constants, and Functions.


SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Online Backup API.

sqlite3_backup *sqlite3_backup_init(
  sqlite3 *pDest,                        /* Destination database handle */
  const char *zDestName,                 /* Destination database name */
  sqlite3 *pSource,                      /* Source database handle */
  const char *zSourceName                /* Source database name */
);
int sqlite3_backup_step(sqlite3_backup *p, int nPage);
int sqlite3_backup_finish(sqlite3_backup *p);
int sqlite3_backup_remaining(sqlite3_backup *p);
int sqlite3_backup_pagecount(sqlite3_backup *p);

The backup API copies the content of one database into another. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

See Also: Using the SQLite Online Backup API

SQLite holds a write transaction open on the destination database file for the duration of the backup operation. The source database is read-locked only while it is being read; it is not locked continuously for the entire backup operation. Thus, the backup may be performed on a live source database without preventing other database connections from reading or writing to the source database while the backup is underway.

To perform a backup operation:

  1. sqlite3_backup_init() is called once to initialize the backup,
  2. sqlite3_backup_step() is called one or more times to transfer the data between the two databases, and finally
  3. sqlite3_backup_finish() is called to release all resources associated with the backup operation.
There should be exactly one call to sqlite3_backup_finish() for each successful call to sqlite3_backup_init().

sqlite3_backup_init()

The D and N arguments to sqlite3_backup_init(D,N,S,M) are the database connection associated with the destination database and the database name, respectively. The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database. The S and M arguments passed to sqlite3_backup_init(D,N,S,M) identify the database connection and database name of the source database, respectively. The source and destination database connections (parameters S and D) must be different or else sqlite3_backup_init(D,N,S,M) will fail with an error.

If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is returned and an error code and error message are stored in the destination database connection D. The error code and message for the failed call to sqlite3_backup_init() can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), and/or sqlite3_errmsg16() functions. A successful call to sqlite3_backup_init() returns a pointer to an sqlite3_backup object. The sqlite3_backup object may be used with the sqlite3_backup_step() and sqlite3_backup_finish() functions to perform the specified backup operation.

sqlite3_backup_step()

Function sqlite3_backup_step(B,N) will copy up to N pages between the source and destination databases specified by sqlite3_backup object B. If N is negative, all remaining source pages are copied. If sqlite3_backup_step(B,N) successfully copies N pages and there are still more pages to be copied, then the function returns SQLITE_OK. If sqlite3_backup_step(B,N) successfully finishes copying all pages from source to destination, then it returns SQLITE_DONE. If an error occurs while running sqlite3_backup_step(B,N), then an error code is returned. As well as SQLITE_OK and SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX extended error code.

The sqlite3_backup_step() might return SQLITE_READONLY if

  1. the destination database was opened read-only, or
  2. the destination database is using write-ahead-log journaling and the destination and source page sizes differ, or
  3. the destination database is an in-memory database and the destination and source page sizes differ.

If sqlite3_backup_step() cannot obtain a required file-system lock, then the busy-handler function is invoked (if one is specified). If the busy-handler returns non-zero before the lock is available, then SQLITE_BUSY is returned to the caller. In this case the call to sqlite3_backup_step() can be retried later. If the source database connection is being used to write to the source database when sqlite3_backup_step() is called, then SQLITE_LOCKED is returned immediately. Again, in this case the call to sqlite3_backup_step() can be retried later on. If SQLITE_IOERR_XXX, SQLITE_NOMEM, or SQLITE_READONLY is returned, then there is no point in retrying the call to sqlite3_backup_step(). These errors are considered fatal. The application must accept that the backup operation has failed and pass the backup operation handle to the sqlite3_backup_finish() to release associated resources.

The first call to sqlite3_backup_step() obtains an exclusive lock on the destination file. The exclusive lock is not released until either sqlite3_backup_finish() is called or the backup operation is complete and sqlite3_backup_step() returns SQLITE_DONE. Every call to sqlite3_backup_step() obtains a shared lock on the source database that lasts for the duration of the sqlite3_backup_step() call. Because the source database is not locked between calls to sqlite3_backup_step(), the source database may be modified mid-way through the backup process. If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be automatically restarted by the next call to sqlite3_backup_step(). If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is automatically updated at the same time.

sqlite3_backup_finish()

When sqlite3_backup_step() has returned SQLITE_DONE, or when the application wishes to abandon the backup operation, the application should destroy the sqlite3_backup by passing it to sqlite3_backup_finish(). The sqlite3_backup_finish() interfaces releases all resources associated with the sqlite3_backup object. If sqlite3_backup_step() has not yet returned SQLITE_DONE, then any active write-transaction on the destination database is rolled back. The sqlite3_backup object is invalid and may not be used following a call to sqlite3_backup_finish().

The value returned by sqlite3_backup_finish is SQLITE_OK if no sqlite3_backup_step() errors occurred, regardless or whether or not sqlite3_backup_step() completed. If an out-of-memory condition or IO error occurred during any prior sqlite3_backup_step() call on the same sqlite3_backup object, then sqlite3_backup_finish() returns the corresponding error code.

A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is not a permanent error and does not affect the return value of sqlite3_backup_finish().

sqlite3_backup_remaining() and sqlite3_backup_pagecount()

Each call to sqlite3_backup_step() sets two values inside the sqlite3_backup object: the number of pages still to be backed up and the total number of pages in the source database file. The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces retrieve these two values, respectively.

The values returned by these functions are only updated by sqlite3_backup_step(). If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.

Concurrent Usage of Database Handles

The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized. If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.

However, the application must guarantee that the destination database connection is not passed to any other API (by any thread) after sqlite3_backup_init() is called and before the corresponding call to sqlite3_backup_finish(). SQLite does not currently check to see if the application incorrectly accesses the destination database connection and so no error code is reported, but the operations may malfunction nevertheless. Use of the destination database connection while a backup is in progress might also also cause a mutex deadlock.

If running in shared cache mode, the application must guarantee that the shared cache used by the destination database is not accessed while the backup is running. In practice this means that the application must guarantee that the disk file being backed up to is not accessed by any connection within the process, not just the specific connection that was passed to sqlite3_backup_init().

The sqlite3_backup object itself is partially threadsafe. Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() APIs are not strictly speaking threadsafe. If they are invoked at the same time as another thread is invoking sqlite3_backup_step() it is possible that they return invalid values.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Binding Values To Prepared Statements

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

In the SQL statement text input to sqlite3_prepare_v2() and its variants, literals may be replaced by a parameter that matches one of following templates:

  • ?
  • ?NNN
  • :VVV
  • @VVV
  • $VVV

In the templates above, NNN represents an integer literal, and VVV represents an alphanumeric identifier. The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the sqlite3_bind_*() routines defined here.

The first argument to the sqlite3_bind_*() routines is always a pointer to the sqlite3_stmt object returned from sqlite3_prepare_v2() or its variants.

The second argument is the index of the SQL parameter to be set. The leftmost SQL parameter has an index of 1. When the same named SQL parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence. The index for named parameters can be looked up using the sqlite3_bind_parameter_index() API if desired. The index for "?NNN" parameters is the value of NNN. The NNN value must be between 1 and the sqlite3_limit() parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value: 999).

The third argument is the value to bind to the parameter.

In those routines that have a fourth argument, its value is the number of bytes in the parameter. To be clear: the value is the number of bytes in the value, not the number of characters. If the fourth parameter is negative, the length of the string is the number of bytes up to the first zero terminator. If a non-negative fourth parameter is provided to sqlite3_bind_text() or sqlite3_bind_text16() then that parameter must be the byte offset where the NUL terminator would occur assuming the string were NUL terminated. If any NUL characters occur at byte offsets less than the value of the fourth parameter then the resulting string value will contain embedded NULs. The result of expressions involving strings with embedded NULs is undefined.

The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and sqlite3_bind_text16() is a destructor used to dispose of the BLOB or string after SQLite has finished with it. The destructor is called to dispose of the BLOB or string even if the call to sqlite3_bind_blob(), sqlite3_bind_text(), or sqlite3_bind_text16() fails. If the fifth argument is the special value SQLITE_STATIC, then SQLite assumes that the information is in static, unmanaged space and does not need to be freed. If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its own private copy of the data immediately, before the sqlite3_bind_*() routine returns.

The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is filled with zeroes. A zeroblob uses a fixed amount of memory (just an integer to hold its size) while it is being processed. Zeroblobs are intended to serve as placeholders for BLOBs whose content is later written using incremental BLOB I/O routines. A negative value for the zeroblob results in a zero-length BLOB.

If any of the sqlite3_bind_*() routines are called with a NULL pointer for the prepared statement or with a prepared statement for which sqlite3_step() has been called more recently than sqlite3_reset(), then the call will return SQLITE_MISUSE. If any sqlite3_bind_() routine is passed a prepared statement that has been finalized, the result is undefined and probably harmful.

Bindings are not cleared by the sqlite3_reset() routine. Unbound parameters are interpreted as NULL.

The sqlite3_bind_* routines return SQLITE_OK on success or an error code if anything goes wrong. SQLITE_RANGE is returned if the parameter index is out of range. SQLITE_NOMEM is returned if malloc() fails.

See also: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name(), and sqlite3_bind_parameter_index().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Number Of SQL Parameters

int sqlite3_bind_parameter_count(sqlite3_stmt*);

This routine can be used to find the number of SQL parameters in a prepared statement. SQL parameters are tokens of the form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as placeholders for values that are bound to the parameters at a later time.

This routine actually returns the index of the largest (rightmost) parameter. For all forms except ?NNN, this will correspond to the number of unique parameters. If parameters of the ?NNN form are used, there may be gaps in the list.

See also: sqlite3_bind(),
sqlite3_bind_parameter_name(), and
sqlite3_bind_parameter_index().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Index Of A Parameter With A Given Name

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

Return the index of an SQL parameter given its name. The index value returned is suitable for use as the second parameter to sqlite3_bind(). A zero is returned if no matching parameter is found. The parameter name must be given in UTF-8 even if the original statement was prepared from UTF-16 text using sqlite3_prepare16_v2().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_index().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Name Of A Host Parameter

const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

The sqlite3_bind_parameter_name(P,N) interface returns the name of the N-th SQL parameter in the prepared statement P. SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" respectively. In other words, the initial ":" or "$" or "@" or "?" is included as part of the name. Parameters of the form "?" without a following integer have no name and are referred to as "nameless" or "anonymous parameters".

The first host parameter has an index of 1, not 0.

If the value N is out of range or if the N-th parameter is nameless, then NULL is returned. The returned string is always in UTF-8 encoding even if the named parameter was originally specified as UTF-16 in sqlite3_prepare16() or sqlite3_prepare16_v2().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_index().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

A Handle To An Open BLOB

typedef struct sqlite3_blob sqlite3_blob;

An instance of this object represents an open BLOB on which incremental BLOB I/O can be performed. Objects of this type are created by sqlite3_blob_open() and destroyed by sqlite3_blob_close(). The sqlite3_blob_read() and sqlite3_blob_write() interfaces can be used to read or write small subsections of the BLOB. The sqlite3_blob_bytes() interface returns the size of the BLOB in bytes.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Return The Size Of An Open BLOB

int sqlite3_blob_bytes(sqlite3_blob *);

Returns the size in bytes of the BLOB accessible via the successfully opened BLOB handle in its only argument. The incremental blob I/O routines can only read or overwriting existing blob content; they cannot change the size of a blob.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Close A BLOB Handle

int sqlite3_blob_close(sqlite3_blob *);

Closes an open BLOB handle.

Closing a BLOB shall cause the current transaction to commit if there are no other BLOBs, no pending prepared statements, and the database connection is in autocommit mode. If any writes were made to the BLOB, they might be held in cache until the close operation if they will fit.

Closing the BLOB often forces the changes out to disk and so if any I/O errors occur, they will likely occur at the time when the BLOB is closed. Any errors that occur during closing are reported as a non-zero return value.

The BLOB is closed unconditionally. Even if this routine returns an error code, the BLOB is still closed.

Calling this routine with a null pointer (such as would be returned by a failed call to sqlite3_blob_open()) is a harmless no-op.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Open A BLOB For Incremental I/O

int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

This interfaces opens a handle to the BLOB located in row iRow, column zColumn, table zTable in database zDb; in other words, the same BLOB that would be selected by:

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

If the flags parameter is non-zero, then the BLOB is opened for read and write access. If it is zero, the BLOB is opened for read access. It is not possible to open a column that is part of an index or primary key for writing. If foreign key constraints are enabled, it is not possible to open a column that is part of a child key for writing.

Note that the database name is not the filename that contains the database but rather the symbolic name of the database that appears after the AS keyword when the database is connected using ATTACH. For the main database file, the database name is "main". For TEMP tables, the database name is "temp".

On success, SQLITE_OK is returned and the new BLOB handle is written to *ppBlob. Otherwise an error code is returned and *ppBlob is set to be a null pointer. This function sets the database connection error code and message accessible via sqlite3_errcode() and sqlite3_errmsg() and related functions. Note that the *ppBlob variable is always initialized in a way that makes it safe to invoke sqlite3_blob_close() on *ppBlob regardless of the success or failure of this routine.

If the row that a BLOB handle points to is modified by an UPDATE, DELETE, or by ON CONFLICT side-effects then the BLOB handle is marked as "expired". This is true if any column of the row is changed, even a column other than the one the BLOB handle is open on. Calls to sqlite3_blob_read() and sqlite3_blob_write() for an expired BLOB handle fail with a return code of SQLITE_ABORT. Changes written into a BLOB prior to the BLOB expiring are not rolled back by the expiration of the BLOB. Such changes will eventually commit if the transaction continues to completion.

Use the sqlite3_blob_bytes() interface to determine the size of the opened blob. The size of a blob may not be changed by this interface. Use the UPDATE SQL command to change the size of a blob.

The sqlite3_bind_zeroblob() and sqlite3_result_zeroblob() interfaces and the built-in zeroblob SQL function can be used, if desired, to create an empty, zero-filled blob in which to read or write using this interface.

To avoid a resource leak, every open BLOB handle should eventually be released by a call to sqlite3_blob_close().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Read Data From A BLOB Incrementally

int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

This function is used to read data from an open BLOB handle into a caller-supplied buffer. N bytes of data are copied into buffer Z from the open BLOB, starting at offset iOffset.

If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR is returned and no data is read. If N or iOffset is less than zero, SQLITE_ERROR is returned and no data is read. The size of the blob (and hence the maximum value of N+iOffset) can be determined using the sqlite3_blob_bytes() interface.

An attempt to read from an expired BLOB handle fails with an error code of SQLITE_ABORT.

On success, sqlite3_blob_read() returns SQLITE_OK. Otherwise, an error code or an extended error code is returned.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_write().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Move a BLOB Handle to a New Row

int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);

This function is used to move an existing blob handle so that it points to a different row of the same database table. The new row is identified by the rowid value passed as the second argument. Only the row can be changed. The database, table and column on which the blob handle is open remain the same. Moving an existing blob handle to a new row can be faster than closing the existing handle and opening a new one.

The new row must meet the same criteria as for sqlite3_blob_open() - it must exist and there must be either a blob or text value stored in the nominated column. If the new row is not present in the table, or if it does not contain a blob or text value, or if another error occurs, an SQLite error code is returned and the blob handle is considered aborted. All subsequent calls to sqlite3_blob_read(), sqlite3_blob_write() or sqlite3_blob_reopen() on an aborted blob handle immediately return SQLITE_ABORT. Calling sqlite3_blob_bytes() on an aborted blob handle always returns zero.

This function sets the database handle error code and message.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Write Data Into A BLOB Incrementally

int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

This function is used to write data into an open BLOB handle from a caller-supplied buffer. N bytes of data are copied from the buffer Z into the open BLOB, starting at offset iOffset.

If the BLOB handle passed as the first argument was not opened for writing (the flags parameter to sqlite3_blob_open() was zero), this function returns SQLITE_READONLY.

This function may only modify the contents of the BLOB; it is not possible to increase the size of a BLOB using this API. If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR is returned and no data is written. If N is less than zero SQLITE_ERROR is returned and no data is written. The size of the BLOB (and hence the maximum value of N+iOffset) can be determined using the sqlite3_blob_bytes() interface.

An attempt to write to an expired BLOB handle fails with an error code of SQLITE_ABORT. Writes to the BLOB that occurred before the BLOB handle expired are not rolled back by the expiration of the handle, though of course those changes might have been overwritten by the statement that expired the BLOB handle or by other independent statements.

On success, sqlite3_blob_write() returns SQLITE_OK. Otherwise, an error code or an extended error code is returned.

This routine only works on a BLOB handle which has been created by a prior successful call to sqlite3_blob_open() and which has not been closed by sqlite3_blob_close(). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_read().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Register A Callback To Handle SQLITE_BUSY Errors

int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

This routine sets a callback function that might be invoked whenever an attempt is made to open a database table that another thread or process has locked.

If the busy callback is NULL, then SQLITE_BUSY or SQLITE_IOERR_BLOCKED is returned immediately upon encountering the lock. If the busy callback is not NULL, then the callback might be invoked with two arguments.

The first argument to the busy handler is a copy of the void* pointer which is the third argument to sqlite3_busy_handler(). The second argument to the busy handler callback is the number of times that the busy handler has been invoked for this locking event. If the busy callback returns 0, then no additional attempts are made to access the database and SQLITE_BUSY or SQLITE_IOERR_BLOCKED is returned. If the callback returns non-zero, then another attempt is made to open the database for reading and the cycle repeats.

The presence of a busy handler does not guarantee that it will be invoked when there is lock contention. If SQLite determines that invoking the busy handler could result in a deadlock, it will go ahead and return SQLITE_BUSY or SQLITE_IOERR_BLOCKED instead of invoking the busy handler. Consider a scenario where one process is holding a read lock that it is trying to promote to a reserved lock and a second process is holding a reserved lock that it is trying to promote to an exclusive lock. The first process cannot proceed because it is blocked by the second and the second process cannot proceed because it is blocked by the first. If both processes invoke the busy handlers, neither will make any progress. Therefore, SQLite returns SQLITE_BUSY for the first process, hoping that this will induce the first process to release its read lock and allow the second process to proceed.

The default busy callback is NULL.

The SQLITE_BUSY error is converted to SQLITE_IOERR_BLOCKED when SQLite is in the middle of a large transaction where all the changes will not fit into the in-memory cache. SQLite will already hold a RESERVED lock on the database file, but it needs to promote this lock to EXCLUSIVE so that it can spill cache pages into the database file without harm to concurrent readers. If it is unable to promote the lock, then the in-memory cache will be left in an inconsistent state and so the error code is promoted from the relatively benign SQLITE_BUSY to the more severe SQLITE_IOERR_BLOCKED. This error code promotion forces an automatic rollback of the changes. See the CorruptionFollowingBusyError wiki page for a discussion of why this is important.

There can only be a single busy handler defined for each database connection. Setting a new busy handler clears any previously set handler. Note that calling sqlite3_busy_timeout() will also set or clear the busy handler.

The busy callback should not take any actions which modify the database connection that invoked the busy handler. Any such actions result in undefined behavior.

A busy handler must not close the database connection or prepared statement that invoked the busy handler.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Set A Busy Timeout

int sqlite3_busy_timeout(sqlite3*, int ms);

This routine sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated. After at least "ms" milliseconds of sleeping, the handler returns 0 which causes sqlite3_step() to return SQLITE_BUSY or SQLITE_IOERR_BLOCKED.

Calling this routine with an argument less than or equal to zero turns off all busy handlers.

There can only be a single busy handler for a particular database connection any any given moment. If another busy handler was defined (using sqlite3_busy_handler()) prior to calling this routine, that other busy handler is cleared.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Result Codes

#define SQLITE_OK           0   /* Successful result */
/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
/* end-of-error-codes */

Many SQLite functions return an integer result code from the set shown here in order to indicates success or failure.

New error codes may be added in future versions of SQLite.

See also: extended result codes, sqlite3_vtab_on_conflict() result codes.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Flags for the xAccess VFS method

#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
#define SQLITE_ACCESS_READ      2   /* Unused */

These integer constants can be used as the third parameter to the xAccess method of an sqlite3_vfs object. They determine what kind of permissions the xAccess method is looking for. With SQLITE_ACCESS_EXISTS, the xAccess method simply checks whether the file exists. With SQLITE_ACCESS_READWRITE, the xAccess method checks whether the named directory is both readable and writable (in other words, if files can be added, removed, and renamed within the directory). The SQLITE_ACCESS_READWRITE constant is currently used only by the temp_store_directory pragma, though this could change in a future release of SQLite. With SQLITE_ACCESS_READ, the xAccess method checks whether the file is readable. The SQLITE_ACCESS_READ constant is currently unused, though it might be used in a future release of SQLite.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Authorizer Action Codes

/******************************************* 3rd ************ 4th ***********/
#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
#define SQLITE_DELETE                9   /* Table Name      NULL            */
#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
#define SQLITE_INSERT               18   /* Table Name      NULL            */
#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
#define SQLITE_READ                 20   /* Table Name      Column Name     */
#define SQLITE_SELECT               21   /* NULL            NULL            */
#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
#define SQLITE_ATTACH               24   /* Filename        NULL            */
#define SQLITE_DETACH               25   /* Database Name   NULL            */
#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
#define SQLITE_REINDEX              27   /* Index Name      NULL            */
#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
#define SQLITE_COPY                  0   /* No longer used */

The sqlite3_set_authorizer() interface registers a callback function that is invoked to authorize certain SQL statement actions. The second parameter to the callback is an integer code that specifies what action is being authorized. These are the integer action codes that the authorizer callback may be passed.

These action code values signify what kind of operation is to be authorized. The 3rd and 4th parameters to the authorization callback function will be parameters or NULL depending on which of these codes is used as the second parameter. The 5th parameter to the authorizer callback is the name of the database ("main", "temp", etc.) if applicable. The 6th parameter to the authorizer callback is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from top-level SQL code.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Text Encodings

#define SQLITE_UTF8           1
#define SQLITE_UTF16LE        2
#define SQLITE_UTF16BE        3
#define SQLITE_UTF16          4    /* Use native byte order */
#define SQLITE_ANY            5    /* sqlite3_create_function only */
#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */

These constant define integer codes that represent the various text encodings supported by SQLite.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Fundamental Datatypes

#define SQLITE_INTEGER  1
#define SQLITE_FLOAT    2
#define SQLITE_BLOB     4
#define SQLITE_NULL     5
#ifdef SQLITE_TEXT
# undef SQLITE_TEXT
#else
# define SQLITE_TEXT     3
#endif
#define SQLITE3_TEXT     3

Every value in SQLite has one of five fundamental datatypes:

  • 64-bit signed integer
  • 64-bit IEEE floating point number
  • string
  • BLOB
  • NULL

These constants are codes for each of those types.

Note that the SQLITE_TEXT constant was also used in SQLite version 2 for a completely different meaning. Software that links against both SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not SQLITE_TEXT.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Extended Result Codes

#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))

In its default configuration, SQLite API routines return one of 26 integer result codes. However, experience has shown that many of these result codes are too coarse-grained. They do not provide as much information about problems as programmers might like. In an effort to address this, newer versions of SQLite (version 3.3.8 and later) include support for additional result codes that provide more detailed information about errors. The extended result codes are enabled or disabled on a per database connection basis using the sqlite3_extended_result_codes() API.

Some of the available extended result codes are listed here. One may expect the number of extended result codes will be expand over time. Software that uses extended result codes should expect to see new result codes in future releases of SQLite.

The SQLITE_OK result code will never be extended. It will always be exactly zero.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Checkpoint operation parameters

#define SQLITE_CHECKPOINT_PASSIVE 0
#define SQLITE_CHECKPOINT_FULL    1
#define SQLITE_CHECKPOINT_RESTART 2

These constants can be used as the 3rd parameter to sqlite3_wal_checkpoint_v2(). See the sqlite3_wal_checkpoint_v2() documentation for additional information about the meaning and use of each of these values.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

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* */
#define SQLITE_CONFIG_URI          17  /* int */

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_limit64()
  • 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 scratch 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 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 two scratch buffers per thread. So N should be set to twice 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 implementation. 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 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. The minimum allocation size is capped at 2**12. Reasonable values for the minimum allocation size are 2**5 through 2**8.

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.

SQLITE_CONFIG_URI
This option takes a single argument of type int. If non-zero, then URI handling is globally enabled. If the parameter is zero, then URI handling is globally disabled. If URI handling is globally enabled, all filenames passed to sqlite3_open(), sqlite3_open_v2(), sqlite3_open16() or specified as part of ATTACH commands are interpreted as URIs, regardless of whether or not the SQLITE_OPEN_URI flag is set when the database connection is opened. If it is globally disabled, filenames are only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the database connection is opened. By default, URI handling is globally disabled. The default value may be changed by compiling with the SQLITE_USE_URI symbol defined.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Database Connection Configuration Options

#define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
#define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
#define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */

These constants are the available integer configuration options that can be passed as the second argument to the sqlite3_db_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_db_config() to make sure that the call worked. The sqlite3_db_config() interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.

SQLITE_DBCONFIG_LOOKASIDE
This option takes three additional arguments that determine the lookaside memory allocator configuration for the database connection. The first argument (the third parameter to sqlite3_db_config() is a pointer to a memory buffer to use for lookaside memory. The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be NULL in which case SQLite will allocate the lookaside buffer itself using sqlite3_malloc(). The second argument is the size of each lookaside buffer slot. The third argument is the number of slots. The size of the buffer in the first argument must be greater than or equal to the product of the second and third arguments. The buffer must be aligned to an 8-byte boundary. If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally rounded down to the next smaller multiple of 8. The lookaside memory configuration for a database connection can only be changed when that connection is not currently using lookaside memory, or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_CONFIG_LOOKASIDE,...) is zero. Any attempt to change the lookaside memory configuration when lookaside memory is in use leaves the configuration unchanged and returns SQLITE_BUSY.

SQLITE_DBCONFIG_ENABLE_FKEY
This option is used to enable or disable the enforcement of foreign key constraints. There should be two additional arguments. The first argument is an integer which is 0 to disable FK enforcement, positive to enable FK enforcement or negative to leave FK enforcement unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether FK enforcement is off or on following this call. The second parameter may be a NULL pointer, in which case the FK enforcement setting is not reported back.

SQLITE_DBCONFIG_ENABLE_TRIGGER
This option is used to enable or disable triggers. There should be two additional arguments. The first argument is an integer which is 0 to disable triggers, positive to enable triggers or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether triggers are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the trigger setting is not reported back.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Status Parameters for database connections

#define SQLITE_DBSTATUS_LOOKASIDE_USED       0
#define SQLITE_DBSTATUS_CACHE_USED           1
#define SQLITE_DBSTATUS_SCHEMA_USED          2
#define SQLITE_DBSTATUS_STMT_USED            3
#define SQLITE_DBSTATUS_LOOKASIDE_HIT        4
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
#define SQLITE_DBSTATUS_CACHE_HIT            7
#define SQLITE_DBSTATUS_CACHE_MISS           8
#define SQLITE_DBSTATUS_MAX                  8   /* Largest defined DBSTATUS */

These constants are the available integer "verbs" that can be passed as the second argument to the sqlite3_db_status() interface.

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

SQLITE_DBSTATUS_LOOKASIDE_USED
This parameter returns the number of lookaside memory slots currently checked out.

SQLITE_DBSTATUS_LOOKASIDE_HIT
This parameter returns the number malloc attempts that were satisfied using lookaside memory. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to the amount of memory requested being larger than the lookaside slot size. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to all lookaside memory already being in use. Only the high-water value is meaningful; the current value is always zero.

SQLITE_DBSTATUS_CACHE_USED
This parameter returns the approximate number of of bytes of heap memory used by all pager caches associated with the database connection. The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.

SQLITE_DBSTATUS_SCHEMA_USED
This parameter returns the approximate number of of bytes of heap memory used to store the schema for all databases associated with the connection - main, temp, and any ATTACH-ed databases. The full amount of memory used by the schemas is reported, even if the schema memory is shared with other database connections due to shared cache mode being enabled. The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.

SQLITE_DBSTATUS_STMT_USED
This parameter returns the approximate number of of bytes of heap and lookaside memory used by all prepared statements associated with the database connection. The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.

SQLITE_DBSTATUS_CACHE_HIT
This parameter returns the number of pager cache hits that have occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT is always 0.

SQLITE_DBSTATUS_CACHE_MISS
This parameter returns the number of pager cache misses that have occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS is always 0.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Authorizer Return Codes

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */

The authorizer callback function must return either SQLITE_OK or one of these two constants in order to signal SQLite whether or not the action is permitted. See the authorizer documentation for additional information.

Note that SQLITE_IGNORE is also used as a return code from the sqlite3_vtab_on_conflict() interface.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Conflict resolution modes

#define SQLITE_ROLLBACK 1
/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
#define SQLITE_FAIL     3
/* #define SQLITE_ABORT 4  // Also an error code */
#define SQLITE_REPLACE  5

These constants are returned by sqlite3_vtab_on_conflict() to inform a virtual table implementation what the ON CONFLICT mode is for the SQL statement being evaluated.

Note that the SQLITE_IGNORE constant is also used as a potential return value from the sqlite3_set_authorizer() callback and that SQLITE_ABORT is also a result code.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Standard File Control Opcodes

#define SQLITE_FCNTL_LOCKSTATE        1
#define SQLITE_GET_LOCKPROXYFILE      2
#define SQLITE_SET_LOCKPROXYFILE      3
#define SQLITE_LAST_ERRNO             4
#define SQLITE_FCNTL_SIZE_HINT        5
#define SQLITE_FCNTL_CHUNK_SIZE       6
#define SQLITE_FCNTL_FILE_POINTER     7
#define SQLITE_FCNTL_SYNC_OMITTED     8
#define SQLITE_FCNTL_WIN32_AV_RETRY   9
#define SQLITE_FCNTL_PERSIST_WAL     10
#define SQLITE_FCNTL_OVERWRITE       11

These integer constants are opcodes for the xFileControl method of the sqlite3_io_methods object and for the sqlite3_file_control() interface.

The SQLITE_FCNTL_LOCKSTATE opcode is used for debugging. This opcode causes the xFileControl method to write the current state of the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE) into an integer that the pArg argument points to. This capability is used during testing and only needs to be supported when SQLITE_TEST is defined.

The SQLITE_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS layer a hint of how large the database file will grow to be during the current transaction. This hint is not guaranteed to be accurate but it is often close. The underlying VFS might choose to preallocate database file space based on this hint in order to help writes to the database file run faster.

The SQLITE_FCNTL_CHUNK_SIZE opcode is used to request that the VFS extends and truncates the database file in chunks of a size specified by the user. The fourth argument to sqlite3_file_control() should point to an integer (type int) containing the new chunk-size to use for the nominated database. Allocating database file space in large chunks (say 1MB at a time), may reduce file-system fragmentation and improve performance on some systems.

The SQLITE_FCNTL_FILE_POINTER opcode is used to obtain a pointer to the sqlite3_file object associated with a particular database connection. See the sqlite3_file_control() documentation for additional information.

The SQLITE_FCNTL_SYNC_OMITTED opcode is generated internally by SQLite and sent to all VFSes in place of a call to the xSync method when the database connection has PRAGMA synchronous set to OFF. Some specialized VFSes need this signal in order to operate correctly when PRAGMA synchronous=OFF is set, but most VFSes do not need this signal and should silently ignore this opcode. Applications should not call sqlite3_file_control() with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.

The SQLITE_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic retry counts and intervals for certain disk I/O operations for the windows VFS in order to work to provide robustness against anti-virus programs. By default, the windows VFS will retry file read, file write, and file delete operations up to 10 times, with a delay of 25 milliseconds before the first retry and with the delay increasing by an additional 25 milliseconds with each subsequent retry. This opcode allows those to values (10 retries and 25 milliseconds of delay) to be adjusted. The values are changed for all database connections within the same process. The argument is a pointer to an array of two integers where the first integer i the new retry count and the second integer is the delay. If either integer is negative, then the setting is not changed but instead the prior value of that setting is written into the array entry, allowing the current retry settings to be interrogated. The zDbName parameter is ignored.

The SQLITE_FCNTL_PERSIST_WAL opcode is used to set or query the persistent Write AHead Log setting. By default, the auxiliary write ahead log and shared memory files used for transaction control are automatically deleted when the latest connection to the database closes. Setting persistent WAL mode causes those files to persist after close. Persisting the files is useful when other processes that do not have write permission on the directory containing the database file want to read the database file, as the WAL and shared memory files must exist in order for the database to be readable. The fourth parameter to sqlite3_file_control() for this opcode should be a pointer to an integer. That integer is 0 to disable persistent WAL mode or 1 to enable persistent WAL mode. If the integer is -1, then it is overwritten with the current WAL persistence setting.

The SQLITE_FCNTL_OVERWRITE opcode is invoked by SQLite after opening a write transaction to indicate that, unless it is rolled back for some reason, the entire database file will be overwritten by the current transaction. This is used by VACUUM operations.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Constraint Operator Codes

#define SQLITE_INDEX_CONSTRAINT_EQ    2
#define SQLITE_INDEX_CONSTRAINT_GT    4
#define SQLITE_INDEX_CONSTRAINT_LE    8
#define SQLITE_INDEX_CONSTRAINT_LT    16
#define SQLITE_INDEX_CONSTRAINT_GE    32
#define SQLITE_INDEX_CONSTRAINT_MATCH 64

These macros defined the allowed values for the sqlite3_index_info.aConstraint[].op field. Each value represents an operator that is part of a constraint term in the wHERE clause of a query that uses a virtual table.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Device Characteristics

#define SQLITE_IOCAP_ATOMIC                 0x00000001
#define SQLITE_IOCAP_ATOMIC512              0x00000002
#define SQLITE_IOCAP_ATOMIC1K               0x00000004
#define SQLITE_IOCAP_ATOMIC2K               0x00000008
#define SQLITE_IOCAP_ATOMIC4K               0x00000010
#define SQLITE_IOCAP_ATOMIC8K               0x00000020
#define SQLITE_IOCAP_ATOMIC16K              0x00000040
#define SQLITE_IOCAP_ATOMIC32K              0x00000080
#define SQLITE_IOCAP_ATOMIC64K              0x00000100
#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800

The xDeviceCharacteristics method of the sqlite3_io_methods object returns an integer which is a vector of the these bit values expressing I/O characteristics of the mass storage device that holds the file that the sqlite3_io_methods refers to.

The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQLITE_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Run-Time Limit Categories

#define SQLITE_LIMIT_LENGTH                    0
#define SQLITE_LIMIT_SQL_LENGTH                1
#define SQLITE_LIMIT_COLUMN                    2
#define SQLITE_LIMIT_EXPR_DEPTH                3
#define SQLITE_LIMIT_COMPOUND_SELECT           4
#define SQLITE_LIMIT_VDBE_OP                   5
#define SQLITE_LIMIT_FUNCTION_ARG              6
#define SQLITE_LIMIT_ATTACHED                  7
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
#define SQLITE_LIMIT_VARIABLE_NUMBER           9
#define SQLITE_LIMIT_TRIGGER_DEPTH            10

These constants define various performance limits that can be lowered at run-time using sqlite3_limit(). The synopsis of the meanings of the various limits is shown below. Additional information is available at Limits in SQLite.

SQLITE_LIMIT_LENGTH
The maximum size of any string or BLOB or table row, in bytes.

SQLITE_LIMIT_SQL_LENGTH
The maximum length of an SQL statement, in bytes.

SQLITE_LIMIT_COLUMN
The maximum number of columns in a table definition or in the result set of a SELECT or the maximum number of columns in an index or in an ORDER BY or GROUP BY clause.

SQLITE_LIMIT_EXPR_DEPTH
The maximum depth of the parse tree on any expression.

SQLITE_LIMIT_COMPOUND_SELECT
The maximum number of terms in a compound SELECT statement.

SQLITE_LIMIT_VDBE_OP
The maximum number of instructions in a virtual machine program used to implement an SQL statement. This limit is not currently enforced, though that might be added in some future release of SQLite.

SQLITE_LIMIT_FUNCTION_ARG
The maximum number of arguments on a function.

SQLITE_LIMIT_ATTACHED
The maximum number of attached databases.

SQLITE_LIMIT_LIKE_PATTERN_LENGTH
The maximum length of the pattern argument to the LIKE or GLOB operators.

SQLITE_LIMIT_VARIABLE_NUMBER
The maximum index number of any parameter in an SQL statement.

SQLITE_LIMIT_TRIGGER_DEPTH
The maximum depth of recursion for triggers.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

File Locking Levels

#define SQLITE_LOCK_NONE          0
#define SQLITE_LOCK_SHARED        1
#define SQLITE_LOCK_RESERVED      2
#define SQLITE_LOCK_PENDING       3
#define SQLITE_LOCK_EXCLUSIVE     4

SQLite uses one of these integer values as the second argument to calls it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods object.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Mutex Types

#define SQLITE_MUTEX_FAST             0
#define SQLITE_MUTEX_RECURSIVE        1
#define SQLITE_MUTEX_STATIC_MASTER    2
#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
#define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */
#define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */

The sqlite3_mutex_alloc() interface takes a single argument which is one of these integer constants.

The set of static mutexes may change from one SQLite release to the next. Applications that override the built-in mutex logic must be prepared to accommodate additional static mutexes.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Flags For File Open Operations

#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */

These bit values are intended for use in the 3rd parameter to the sqlite3_open_v2() interface and in the 4th parameter to the sqlite3_vfs.xOpen method.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Flags for the xShmLock VFS method

#define SQLITE_SHM_UNLOCK       1
#define SQLITE_SHM_LOCK         2
#define SQLITE_SHM_SHARED       4
#define SQLITE_SHM_EXCLUSIVE    8

These integer constants define the various locking operations allowed by the xShmLock method of sqlite3_io_methods. The following are the only legal combinations of flags to the xShmLock method:

  • SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  • SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE

When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as was given no the corresponding lock.

The xShmLock method can transition between unlocked and SHARED or between unlocked and EXCLUSIVE. It cannot transition between SHARED and EXCLUSIVE.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Maximum xShmLock index

#define SQLITE_SHM_NLOCK        8

The xShmLock method on sqlite3_io_methods may use values between 0 and this upper bound as its "offset" argument. The SQLite core will never attempt to acquire or release a lock outside of this range

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Compile-Time Library Version Numbers

#define SQLITE_VERSION        "3.7.9"
#define SQLITE_VERSION_NUMBER 3007009
#define SQLITE_SOURCE_ID      "2011-11-01 00:52:41 c7c6050ef060877ebe77b41d959e9df13f8c9b5e"

The SQLITE_VERSION C preprocessor macro in the sqlite3.h header evaluates to a string literal that is the SQLite version in the format "X.Y.Z" where X is the major version number (always 3 for SQLite3) and Y is the minor version number and Z is the release number. The SQLITE_VERSION_NUMBER C preprocessor macro resolves to an integer with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same numbers used in SQLITE_VERSION. The SQLITE_VERSION_NUMBER for any given release of SQLite will also be larger than the release from which it is derived. Either Y will be held constant and Z will be incremented or else Y will be incremented and Z will be reset to zero.

Since version 3.6.18, SQLite source code has been stored in the Fossil configuration management system. The SQLITE_SOURCE_ID macro evaluates to a string which identifies a particular check-in of SQLite within its configuration management system. The SQLITE_SOURCE_ID string contains the date and time of the check-in (UTC) and an SHA1 hash of the entire source tree.

See also: sqlite3_libversion(),
sqlite3_libversion_number(), sqlite3_sourceid(),
sqlite_version() and sqlite_source_id().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Constants Defining Special Destructor Behavior

typedef void (*sqlite3_destructor_type)(void*);
#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)

These are special values for the destructor that is passed in as the final argument to routines like sqlite3_result_blob(). If the destructor argument is SQLITE_STATIC, it means that the content pointer is constant and will never change. It does not need to be destroyed. The SQLITE_TRANSIENT value means that the content will likely change in the near future and that SQLite should make its own private copy of the content before returning.

The typedef is necessary to work around problems in certain C++ compilers. See ticket #2191.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Status Parameters

#define SQLITE_STATUS_MEMORY_USED          0
#define SQLITE_STATUS_PAGECACHE_USED       1
#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
#define SQLITE_STATUS_SCRATCH_USED         3
#define SQLITE_STATUS_SCRATCH_OVERFLOW     4
#define SQLITE_STATUS_MALLOC_SIZE          5
#define SQLITE_STATUS_PARSER_STACK         6
#define SQLITE_STATUS_PAGECACHE_SIZE       7
#define SQLITE_STATUS_SCRATCH_SIZE         8
#define SQLITE_STATUS_MALLOC_COUNT         9

These integer constants designate various run-time status parameters that can be returned by sqlite3_status().

SQLITE_STATUS_MEMORY_USED
This parameter is the current amount of memory checked out using sqlite3_malloc(), either directly or indirectly. The figure includes calls made to sqlite3_malloc() by the application and internal memory usage by the SQLite library. Scratch memory controlled by SQLITE_CONFIG_SCRATCH and auxiliary page-cache memory controlled by SQLITE_CONFIG_PAGECACHE is not included in this parameter. The amount returned is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.

SQLITE_STATUS_MALLOC_SIZE
This parameter records the largest memory allocation request handed to sqlite3_malloc() or sqlite3_realloc() (or their internal equivalents). Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_MALLOC_COUNT
This parameter records the number of separate memory allocations currently checked out.

SQLITE_STATUS_PAGECACHE_USED
This parameter returns the number of pages used out of the pagecache memory allocator that was configured using SQLITE_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.

SQLITE_STATUS_PAGECACHE_OVERFLOW
This parameter returns the number of bytes of page cache allocation which could not be satisfied by the SQLITE_CONFIG_PAGECACHE buffer and where forced to overflow to sqlite3_malloc(). The returned value includes allocations that overflowed because they where too large (they were larger than the "sz" parameter to SQLITE_CONFIG_PAGECACHE) and allocations that overflowed because no space was left in the page cache.

SQLITE_STATUS_PAGECACHE_SIZE
This parameter records the largest memory allocation request handed to pagecache memory allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_SCRATCH_USED
This parameter returns the number of allocations used out of the scratch memory allocator configured using SQLITE_CONFIG_SCRATCH. The value returned is in allocations, not in bytes. Since a single thread may only have one scratch allocation outstanding at time, this parameter also reports the number of threads using scratch memory at the same time.

SQLITE_STATUS_SCRATCH_OVERFLOW
This parameter returns the number of bytes of scratch memory allocation which could not be satisfied by the SQLITE_CONFIG_SCRATCH buffer and where forced to overflow to sqlite3_malloc(). The values returned include overflows because the requested allocation was too larger (that is, because the requested allocation was larger than the "sz" parameter to SQLITE_CONFIG_SCRATCH) and because no scratch buffer slots were available.

SQLITE_STATUS_SCRATCH_SIZE
This parameter records the largest memory allocation request handed to scratch memory allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.

SQLITE_STATUS_PARSER_STACK
This parameter records the deepest parser stack. It is only meaningful if SQLite is compiled with YYTRACKMAXSTACKDEPTH.

New status parameters may be added from time to time.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Status Parameters for prepared statements

#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
#define SQLITE_STMTSTATUS_SORT              2
#define SQLITE_STMTSTATUS_AUTOINDEX         3

These preprocessor macros define integer codes that name counter values associated with the sqlite3_stmt_status() interface. The meanings of the various counters are as follows:

SQLITE_STMTSTATUS_FULLSCAN_STEP
This is the number of times that SQLite has stepped forward in a table as part of a full table scan. Large numbers for this counter may indicate opportunities for performance improvement through careful use of indices.

SQLITE_STMTSTATUS_SORT
This is the number of sort operations that have occurred. A non-zero value in this counter may indicate an opportunity to improvement performance through careful use of indices.

SQLITE_STMTSTATUS_AUTOINDEX
This is the number of rows inserted into transient indices that were created automatically in order to help joins run faster. A non-zero value in this counter may indicate an opportunity to improvement performance by adding permanent indices that do not need to be reinitialized each time the statement is run.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Synchronization Type Flags

#define SQLITE_SYNC_NORMAL        0x00002
#define SQLITE_SYNC_FULL          0x00003
#define SQLITE_SYNC_DATAONLY      0x00010

When SQLite invokes the xSync() method of an sqlite3_io_methods object it uses a combination of these integer values as the second argument.

When the SQLITE_SYNC_DATAONLY flag is used, it means that the sync operation only needs to flush data to mass storage. Inode information need not be flushed. If the lower four bits of the flag equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. If the lower four bits equal SQLITE_SYNC_FULL, that means to use Mac OS X style fullsync instead of fsync().

Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags with the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL settings. The synchronous pragma determines when calls to the xSync VFS method occur and applies uniformly across all platforms. The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how energetic or rigorous or forceful the sync operations are and only make a difference on Mac OSX for the default SQLite code. (Third-party VFS implementations might also make the distinction between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the operating systems natively supported by SQLite, only Mac OSX cares about the difference.)

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Testing Interface Operation Codes

#define SQLITE_TESTCTRL_FIRST                    5
#define SQLITE_TESTCTRL_PRNG_SAVE                5
#define SQLITE_TESTCTRL_PRNG_RESTORE             6
#define SQLITE_TESTCTRL_PRNG_RESET               7
#define SQLITE_TESTCTRL_BITVEC_TEST              8
#define SQLITE_TESTCTRL_FAULT_INSTALL            9
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
#define SQLITE_TESTCTRL_PENDING_BYTE            11
#define SQLITE_TESTCTRL_ASSERT                  12
#define SQLITE_TESTCTRL_ALWAYS                  13
#define SQLITE_TESTCTRL_RESERVE                 14
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
#define SQLITE_TESTCTRL_ISKEYWORD               16
#define SQLITE_TESTCTRL_PGHDRSZ                 17
#define SQLITE_TESTCTRL_SCRATCHMALLOC           18
#define SQLITE_TESTCTRL_LOCALTIME_FAULT         19
#define SQLITE_TESTCTRL_LAST                    19

These constants are the valid operation code parameters used as the first argument to sqlite3_test_control().

These parameters and their meanings are subject to change without notice. These values are for testing purposes only. Applications should not use any of these parameters or the sqlite3_test_control() interface.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Configuration Options

#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1

These macros define the various options to the sqlite3_vtab_config() interface that virtual table implementations can use to customize and optimize their behavior.

SQLITE_VTAB_CONSTRAINT_SUPPORT
Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported, where X is an integer. If X is zero, then the virtual table whose xCreate or xConnect method invoked sqlite3_vtab_config() does not support constraints. In this configuration (which is the default) if a call to the xUpdate method returns SQLITE_CONSTRAINT, then the entire statement is rolled back as if OR ABORT had been specified as part of the users SQL statement, regardless of the actual ON CONFLICT mode specified.

If X is non-zero, then the virtual table implementation guarantees that if xUpdate returns SQLITE_CONSTRAINT, it will do so before any modifications to internal or persistent data structures have been made. If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite is able to roll back a statement or database transaction, and abandon or continue processing the current SQL statement as appropriate. If the ON CONFLICT mode is REPLACE and the xUpdate method returns SQLITE_CONSTRAINT, SQLite handles this as if the ON CONFLICT mode had been ABORT.

Virtual table implementations that are required to handle OR REPLACE must do so within the xUpdate method. If a call to the sqlite3_vtab_on_conflict() function indicates that the current ON CONFLICT policy is REPLACE, the virtual table implementation should silently replace the appropriate rows within the xUpdate callback and return SQLITE_OK. Or, if this is not possible, it may return SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT constraint handling.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Count The Number Of Rows Modified

int sqlite3_changes(sqlite3*);

This function returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement on the database connection specified by the first parameter. Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted. Auxiliary changes caused by triggers or foreign key actions are not counted. Use the sqlite3_total_changes() function to find the total number of changes including changes caused by triggers and foreign key actions.

Changes to a view that are simulated by an INSTEAD OF trigger are not counted. Only real table changes are counted.

A "row change" is a change to a single row of a single table caused by an INSERT, DELETE, or UPDATE statement. Rows that are changed as side effects of REPLACE constraint resolution, rollback, ABORT processing, DROP TABLE, or by any other mechanisms do not count as direct row changes.

A "trigger context" is a scope of execution that begins and ends with the script of a trigger. Most SQL statements are evaluated outside of any trigger. This is the "top level" trigger context. If a trigger fires from the top level, a new trigger context is entered for the duration of that one trigger. Subtriggers create subcontexts for their duration.

Calling sqlite3_exec() or sqlite3_step() recursively does not create a new trigger context.

This function returns the number of direct row changes in the most recent INSERT, UPDATE, or DELETE statement within the same trigger context.

Thus, when called from the top level, this function returns the number of changes in the most recent INSERT, UPDATE, or DELETE that also occurred at the top level. Within the body of a trigger, the sqlite3_changes() interface can be called to find the number of changes in the most recently completed INSERT, UPDATE, or DELETE statement within the body of the same trigger. However, the number returned does not include changes caused by subtriggers since those have their own context.

See also the sqlite3_total_changes() interface, the count_changes pragma, and the changes() SQL function.

If a separate thread makes changes on the same database connection while sqlite3_changes() is running then the value returned is unpredictable and not meaningful.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Reset All Bindings On A Prepared Statement

int sqlite3_clear_bindings(sqlite3_stmt*);

Contrary to the intuition of many, sqlite3_reset() does not reset the bindings on a prepared statement. Use this routine to reset all host parameters to NULL.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Closing A Database Connection

int sqlite3_close(sqlite3 *);

The sqlite3_close() routine is the destructor for the sqlite3 object. Calls to sqlite3_close() return SQLITE_OK if the sqlite3 object is successfully destroyed and all associated resources are deallocated.

Applications must finalize all prepared statements and close all BLOB handles associated with the sqlite3 object prior to attempting to close the object. If sqlite3_close() is called on a database connection that still has outstanding prepared statements or BLOB handles, then it returns SQLITE_BUSY.

If sqlite3_close() is invoked while a transaction is open, the transaction is automatically rolled back.

The C parameter to sqlite3_close(C) must be either a NULL pointer or an sqlite3 object pointer obtained from sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(), and not previously closed. Calling sqlite3_close() with a NULL pointer argument is a harmless no-op.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Collation Needed Callbacks

int sqlite3_collation_needed(
  sqlite3*,
  void*,
  void(*)(void*,sqlite3*,int eTextRep,const char*)
);
int sqlite3_collation_needed16(
  sqlite3*,
  void*,
  void(*)(void*,sqlite3*,int eTextRep,const void*)
);

To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database connection to be invoked whenever an undefined collation sequence is required.

If the function is registered using the sqlite3_collation_needed() API, then it is passed the names of undefined collation sequences as strings encoded in UTF-8. If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. A call to either function replaces the existing collation-needed callback.

When the callback is invoked, the first argument passed is a copy of the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). The second argument is the database connection. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, or SQLITE_UTF16LE, indicating the most desirable form of the collation sequence function required. The fourth parameter is the name of the required collation sequence.

The callback function should register the desired collation using sqlite3_create_collation(), sqlite3_create_collation16(), or sqlite3_create_collation_v2().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Result Values From A Query

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

These routines form the "result set" interface.

These routines return information about a single column of the current result row of a query. In every case the first argument is a pointer to the prepared statement that is being evaluated (the sqlite3_stmt* that was returned from sqlite3_prepare_v2() or one of its variants) and the second argument is the index of the column for which information should be returned. The leftmost column of the result set has the index 0. The number of columns in the result can be determined using sqlite3_column_count().

If the SQL statement does not currently point to a valid row, or if the column index is out of range, the result is undefined. These routines may only be called when the most recent call to sqlite3_step() has returned SQLITE_ROW and neither sqlite3_reset() nor sqlite3_finalize() have been called subsequently. If any of these routines are called after sqlite3_reset() or sqlite3_finalize() or after sqlite3_step() has returned something other than SQLITE_ROW, the results are undefined. If sqlite3_step() or sqlite3_reset() or sqlite3_finalize() are called from a different thread while any of these routines are pending, then the results are undefined.

The sqlite3_column_type() routine returns the datatype code for the initial data type of the result column. The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. The value returned by sqlite3_column_type() is only meaningful if no type conversions have occurred as described below. After a type conversion, the value returned by sqlite3_column_type() is undefined. Future versions of SQLite may change the behavior of sqlite3_column_type() following a type conversion.

If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() routine returns the number of bytes in that BLOB or string. If the result is a UTF-16 string, then sqlite3_column_bytes() converts the string to UTF-8 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf() to convert that value to a UTF-8 string and returns the number of bytes in that string. If the result is NULL, then sqlite3_column_bytes() returns zero.

If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() routine returns the number of bytes in that BLOB or string. If the result is a UTF-8 string, then sqlite3_column_bytes16() converts the string to UTF-16 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes16() uses sqlite3_snprintf() to convert that value to a UTF-16 string and returns the number of bytes in that string. If the result is NULL, then sqlite3_column_bytes16() returns zero.

The values returned by sqlite3_column_bytes() and sqlite3_column_bytes16() do not include the zero terminators at the end of the string. For clarity: the values returned by sqlite3_column_bytes() and sqlite3_column_bytes16() are the number of bytes in the string, not the number of characters.

Strings returned by sqlite3_column_text() and sqlite3_column_text16(), even empty strings, are always zero terminated. The return value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.

The object returned by sqlite3_column_value() is an unprotected sqlite3_value object. An unprotected sqlite3_value object may only be used with sqlite3_bind_value() and sqlite3_result_value(). If the unprotected sqlite3_value object returned by sqlite3_column_value() is used in any other way, including calls to routines like sqlite3_value_int(), sqlite3_value_text(), or sqlite3_value_bytes(), then the behavior is undefined.

These routines attempt to convert the value where appropriate. For example, if the internal representation is FLOAT and a text result is requested, sqlite3_snprintf() is used internally to perform the conversion automatically. The following table details the conversions that are applied:

Internal
Type 		Requested
Type 		Conversion

NULL | INTEGER | Result is 0
NULL | FLOAT | Result is 0.0
NULL | TEXT | Result is NULL pointer
NULL | BLOB | Result is NULL pointer
INTEGER | FLOAT | Convert from integer to float
INTEGER | TEXT | ASCII rendering of the integer
INTEGER | BLOB | Same as INTEGER->TEXT
FLOAT | INTEGER | Convert from float to integer
FLOAT | TEXT | ASCII rendering of the float
FLOAT | BLOB | Same as FLOAT->TEXT
TEXT | INTEGER | Use atoi()
TEXT | FLOAT | Use atof()
TEXT | BLOB | No change
BLOB | INTEGER | Convert to TEXT then use atoi()
BLOB | FLOAT | Convert to TEXT then use atof()
BLOB | TEXT | Add a zero terminator if needed

The table above makes reference to standard C library functions atoi() and atof(). SQLite does not really use these functions. It has its own equivalent internal routines. The atoi() and atof() names are used in the table for brevity and because they are familiar to most C programmers.

Note that when type conversions occur, pointers returned by prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() may be invalidated. Type conversions and pointer invalidations might occur in the following cases:

  • The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string.
  • The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16.
  • The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() is called. The content must be converted to UTF-8.

Conversions between UTF-16be and UTF-16le are always done in place and do not invalidate a prior pointer, though of course the content of the buffer that the prior pointer references will have been modified. Other kinds of conversion are done in place when it is possible, but sometimes they are not possible and in those cases prior pointers are invalidated.

The safest and easiest to remember policy is to invoke these routines in one of the following ways:

  • sqlite3_column_text() followed by sqlite3_column_bytes()
  • sqlite3_column_blob() followed by sqlite3_column_bytes()
  • sqlite3_column_text16() followed by sqlite3_column_bytes16()

In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), or sqlite3_column_text16() first to force the result into the desired format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to find the size of the result. Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().

The pointers returned are valid until a type conversion occurs as described above, or until sqlite3_step() or sqlite3_reset() or sqlite3_finalize() is called. The memory space used to hold strings and BLOBs is freed automatically. Do not pass the pointers returned sqlite3_column_blob(), sqlite3_column_text(), etc. into sqlite3_free().

If a memory allocation error occurs during the evaluation of any of these routines, a default value is returned. The default value is either the integer 0, the floating point number 0.0, or a NULL pointer. Subsequent calls to sqlite3_errcode() will return SQLITE_NOMEM.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Number Of Columns In A Result Set

int sqlite3_column_count(sqlite3_stmt *pStmt);

Return the number of columns in the result set returned by the prepared statement. This routine returns 0 if pStmt is an SQL statement that does not return data (for example an UPDATE).

See also: sqlite3_data_count()

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Source Of Data In A Query Result

const char *sqlite3_column_database_name(sqlite3_stmt*,int);
const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
const char *sqlite3_column_table_name(sqlite3_stmt*,int);
const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);

These routines provide a means to determine the database, table, and table column that is the origin of a particular result column in SELECT statement. The name of the database or table or column can be returned as either a UTF-8 or UTF-16 string. The _database_ routines return the database name, the _table_ routines return the table name, and the origin_ routines return the column name. The returned string is valid until the prepared statement is destroyed using sqlite3_finalize() or until the statement is automatically reprepared by the first call to sqlite3_step() for a particular run or until the same information is requested again in a different encoding.

The names returned are the original un-aliased names of the database, table, and column.

The first argument to these interfaces is a prepared statement. These functions return information about the Nth result column returned by the statement, where N is the second function argument. The left-most column is column 0 for these routines.

If the Nth column returned by the statement is an expression or subquery and is not a column value, then all of these functions return NULL. These routine might also return NULL if a memory allocation error occurs. Otherwise, they return the name of the attached database, table, or column that query result column was extracted from.

As with all other SQLite APIs, those whose names end with "16" return UTF-16 encoded strings and the other functions return UTF-8.

These APIs are only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol.

If two or more threads call one or more of these routines against the same prepared statement and column at the same time then the results are undefined.

If two or more threads call one or more column metadata interfaces for the same prepared statement and result column at the same time then the results are undefined.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Declared Datatype Of A Query Result

const char *sqlite3_column_decltype(sqlite3_stmt*,int);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

The first parameter is a prepared statement. If this statement is a SELECT statement and the Nth column of the returned result set of that SELECT is a table column (not an expression or subquery) then the declared type of the table column is returned. If the Nth column of the result set is an expression or subquery, then a NULL pointer is returned. The returned string is always UTF-8 encoded.

For example, given the database schema:

CREATE TABLE t1(c1 VARIANT);

and the following statement to be compiled:

SELECT c1 + 1, c1 FROM t1;

this routine would return the string "VARIANT" for the second result column (i==1), and a NULL pointer for the first result column (i==0).

SQLite uses dynamic run-time typing. So just because a column is declared to contain a particular type does not mean that the data stored in that column is of the declared type. SQLite is strongly typed, but the typing is dynamic not static. Type is associated with individual values, not with the containers used to hold those values.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Column Names In A Result Set

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

These routines return the name assigned to a particular column in the result set of a SELECT statement. The sqlite3_column_name() interface returns a pointer to a zero-terminated UTF-8 string and sqlite3_column_name16() returns a pointer to a zero-terminated UTF-16 string. The first parameter is the prepared statement that implements the SELECT statement. The second parameter is the column number. The leftmost column is number 0.

The returned string pointer is valid until either the prepared statement is destroyed by sqlite3_finalize() or until the statement is automatically reprepared by the first call to sqlite3_step() for a particular run or until the next call to sqlite3_column_name() or sqlite3_column_name16() on the same column.

If sqlite3_malloc() fails during the processing of either routine (for example during a conversion from UTF-8 to UTF-16) then a NULL pointer is returned.

The name of a result column is the value of the "AS" clause for that column, if there is an AS clause. If there is no AS clause then the name of the column is unspecified and may change from one release of SQLite to the next.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Commit And Rollback Notification Callbacks

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

The sqlite3_commit_hook() interface registers a callback function to be invoked whenever a transaction is committed. Any callback set by a previous call to sqlite3_commit_hook() for the same database connection is overridden. The sqlite3_rollback_hook() interface registers a callback function to be invoked whenever a transaction is rolled back. Any callback set by a previous call to sqlite3_rollback_hook() for the same database connection is overridden. The pArg argument is passed through to the callback. If the callback on a commit hook function returns non-zero, then the commit is converted into a rollback.

The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions return the P argument from the previous call of the same function on the same database connection D, or NULL for the first call for each function on D.

The callback implementation must not do anything that will modify the database connection that invoked the callback. Any actions to modify the database connection must be deferred until after the completion of the sqlite3_step() call that triggered the commit or rollback hook in the first place. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

Registering a NULL function disables the callback.

When the commit hook callback routine returns zero, the COMMIT operation is allowed to continue normally. If the commit hook returns non-zero, then the COMMIT is converted into a ROLLBACK. The rollback hook is invoked on a rollback that results from a commit hook returning non-zero, just as it would be with any other rollback.

For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. The rollback callback is not invoked if a transaction is automatically rolled back because the database connection is closed.

See also the sqlite3_update_hook() interface.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Run-Time Library Compilation Options Diagnostics

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
int sqlite3_compileoption_used(const char *zOptName);
const char *sqlite3_compileoption_get(int N);
#endif

The sqlite3_compileoption_used() function returns 0 or 1 indicating whether the specified option was defined at compile time. The SQLITE_ prefix may be omitted from the option name passed to sqlite3_compileoption_used().

The sqlite3_compileoption_get() function allows iterating over the list of options that were defined at compile time by returning the N-th compile time option string. If N is out of range, sqlite3_compileoption_get() returns a NULL pointer. The SQLITE_ prefix is omitted from any strings returned by sqlite3_compileoption_get().

Support for the diagnostic functions sqlite3_compileoption_used() and sqlite3_compileoption_get() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.

See also: SQL functions sqlite_compileoption_used() and sqlite_compileoption_get() and the compile_options pragma.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Determine If An SQL Statement Is Complete

int sqlite3_complete(const char *sql);
int sqlite3_complete16(const void *sql);

These routines are useful during command-line input to determine if the currently entered text seems to form a complete SQL statement or if additional input is needed before sending the text into SQLite for parsing. These routines return 1 if the input string appears to be a complete SQL statement. A statement is judged to be complete if it ends with a semicolon token and is not a prefix of a well-formed CREATE TRIGGER statement. Semicolons that are embedded within string literals or quoted identifier names or comments are not independent tokens (they are part of the token in which they are embedded) and thus do not count as a statement terminator. Whitespace and comments that follow the final semicolon are ignored.

These routines return 0 if the statement is incomplete. If a memory allocation fails, then SQLITE_NOMEM is returned.

These routines do not parse the SQL statements thus will not detect syntactically incorrect SQL.

If SQLite has not been initialized using sqlite3_initialize() prior to invoking sqlite3_complete16() then sqlite3_initialize() is invoked automatically by sqlite3_complete16(). If that initialization fails, then the return value from sqlite3_complete16() will be non-zero regardless of whether or not the input SQL is complete.

The input to sqlite3_complete() must be a zero-terminated UTF-8 string.

The input to sqlite3_complete16() must be a zero-terminated UTF-16 string in native byte order.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Configuring The SQLite Library

int sqlite3_config(int, ...);

The sqlite3_config() interface is used to make global configuration changes to SQLite in order to tune SQLite to the specific needs of the application. The default configuration is recommended for most applications and so this routine is usually not necessary. It is provided to support rare applications with unusual needs.

The sqlite3_config() interface is not threadsafe. The application must insure that no other SQLite interfaces are invoked by other threads while sqlite3_config() is running. Furthermore, sqlite3_config() may only be invoked prior to library initialization using sqlite3_initialize() or after shutdown by sqlite3_shutdown(). If sqlite3_config() is called after sqlite3_initialize() and before sqlite3_shutdown() then it will return SQLITE_MISUSE. Note, however, that sqlite3_config() can be called as part of the implementation of an application-defined sqlite3_os_init().

The first argument to sqlite3_config() is an integer configuration option that determines what property of SQLite is to be configured. Subsequent arguments vary depending on the configuration option in the first argument.

When a configuration option is set, sqlite3_config() returns SQLITE_OK. If the option is unknown or SQLite is unable to set the option then this routine returns a non-zero error code.

See also lists of Objects, Constants, and Functions.


List Of SQLite Constants

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Constants:

Note: Constants marked with "(exp)" are experimental and constants marked with "(obs)" are deprecated

  • SQLITE_ABORT
  • SQLITE_ACCESS_EXISTS
  • SQLITE_ACCESS_READ
  • SQLITE_ACCESS_READWRITE
  • SQLITE_ALTER_TABLE
  • SQLITE_ANALYZE
  • SQLITE_ANY
  • SQLITE_ATTACH
  • SQLITE_AUTH
  • SQLITE_BLOB
  • SQLITE_BUSY
  • SQLITE_BUSY_RECOVERY
  • SQLITE_CANTOPEN
  • SQLITE_CANTOPEN_NOTEMPDIR
  • SQLITE_CHECKPOINT_FULL
  • SQLITE_CHECKPOINT_PASSIVE
  • SQLITE_CHECKPOINT_RESTART
  • SQLITE_CONFIG_GETMALLOC
  • SQLITE_CONFIG_GETMUTEX
  • SQLITE_CONFIG_GETPCACHE
  • SQLITE_CONFIG_HEAP
  • SQLITE_CONFIG_LOG
  • SQLITE_CONFIG_LOOKASIDE
  • SQLITE_CONFIG_MALLOC
  • SQLITE_CONFIG_MEMSTATUS
  • SQLITE_CONFIG_MULTITHREAD
  • SQLITE_CONFIG_MUTEX
  • SQLITE_CONFIG_PAGECACHE
  • SQLITE_CONFIG_PCACHE
  • SQLITE_CONFIG_SCRATCH
  • SQLITE_CONFIG_SERIALIZED
  • SQLITE_CONFIG_SINGLETHREAD
  • SQLITE_CONFIG_URI
  • SQLITE_CONSTRAINT
  • SQLITE_COPY
  • SQLITE_CORRUPT
  • SQLITE_CORRUPT_VTAB
  • SQLITE_CREATE_INDEX
  • SQLITE_CREATE_TABLE
  • SQLITE_CREATE_TEMP_INDEX
  • SQLITE_CREATE_TEMP_TABLE
  • SQLITE_CREATE_TEMP_TRIGGER
  • SQLITE_CREATE_TEMP_VIEW
  • SQLITE_CREATE_TRIGGER
  • SQLITE_CREATE_VIEW
  • SQLITE_CREATE_VTABLE
  • SQLITE_DBCONFIG_ENABLE_FKEY
  • SQLITE_DBCONFIG_ENABLE_TRIGGER
  • SQLITE_DBCONFIG_LOOKASIDE
  • SQLITE_DBSTATUS_CACHE_HIT
  • SQLITE_DBSTATUS_CACHE_MISS
  • SQLITE_DBSTATUS_CACHE_USED
  • SQLITE_DBSTATUS_LOOKASIDE_HIT
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
  • SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
  • SQLITE_DBSTATUS_LOOKASIDE_USED
  • SQLITE_DBSTATUS_MAX
  • SQLITE_DBSTATUS_SCHEMA_USED
  • SQLITE_DBSTATUS_STMT_USED
  • SQLITE_DELETE
  • SQLITE_DENY
  • SQLITE_DETACH
  • SQLITE_DONE
  • SQLITE_DROP_INDEX
  • SQLITE_DROP_TABLE
  • SQLITE_DROP_TEMP_INDEX
  • SQLITE_DROP_TEMP_TABLE
  • SQLITE_DROP_TEMP_TRIGGER
  • SQLITE_DROP_TEMP_VIEW
  • SQLITE_DROP_TRIGGER
  • SQLITE_DROP_VIEW
  • SQLITE_DROP_VTABLE
  • SQLITE_EMPTY
  • SQLITE_ERROR
  • SQLITE_FAIL
  • SQLITE_FCNTL_CHUNK_SIZE
  • SQLITE_FCNTL_FILE_POINTER
  • SQLITE_FCNTL_LOCKSTATE
  • SQLITE_FCNTL_OVERWRITE
  • SQLITE_FCNTL_PERSIST_WAL
  • SQLITE_FCNTL_SIZE_HINT
  • SQLITE_FCNTL_SYNC_OMITTED
  • SQLITE_FCNTL_WIN32_AV_RETRY
  • SQLITE_FLOAT
  • SQLITE_FORMAT
  • SQLITE_FULL
  • SQLITE_FUNCTION
  • SQLITE_GET_LOCKPROXYFILE
  • SQLITE_IGNORE
  • SQLITE_INDEX_CONSTRAINT_EQ
  • SQLITE_INDEX_CONSTRAINT_GE
  • SQLITE_INDEX_CONSTRAINT_GT
  • SQLITE_INDEX_CONSTRAINT_LE
  • SQLITE_INDEX_CONSTRAINT_LT
  • SQLITE_INDEX_CONSTRAINT_MATCH
  • SQLITE_INSERT
  • SQLITE_INTEGER
  • SQLITE_INTERNAL
  • SQLITE_INTERRUPT
  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL
  • SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  • SQLITE_IOERR
  • SQLITE_IOERR_ACCESS
  • SQLITE_IOERR_BLOCKED
  • SQLITE_IOERR_CHECKRESERVEDLOCK
  • SQLITE_IOERR_CLOSE
  • SQLITE_IOERR_DELETE
  • SQLITE_IOERR_DIR_CLOSE
  • SQLITE_IOERR_DIR_FSYNC
  • SQLITE_IOERR_FSTAT
  • SQLITE_IOERR_FSYNC
  • SQLITE_IOERR_LOCK
  • SQLITE_IOERR_NOMEM
  • SQLITE_IOERR_RDLOCK
  • SQLITE_IOERR_READ
  • SQLITE_IOERR_SEEK
  • SQLITE_IOERR_SHMLOCK
  • SQLITE_IOERR_SHMMAP
  • SQLITE_IOERR_SHMOPEN
  • SQLITE_IOERR_SHMSIZE
  • SQLITE_IOERR_SHORT_READ
  • SQLITE_IOERR_TRUNCATE
  • SQLITE_IOERR_UNLOCK
  • SQLITE_IOERR_WRITE
  • SQLITE_LAST_ERRNO
  • SQLITE_LIMIT_ATTACHED
  • SQLITE_LIMIT_COLUMN
  • SQLITE_LIMIT_COMPOUND_SELECT
  • SQLITE_LIMIT_EXPR_DEPTH
  • SQLITE_LIMIT_FUNCTION_ARG
  • SQLITE_LIMIT_LENGTH
  • SQLITE_LIMIT_LIKE_PATTERN_LENGTH
  • SQLITE_LIMIT_SQL_LENGTH
  • SQLITE_LIMIT_TRIGGER_DEPTH
  • SQLITE_LIMIT_VARIABLE_NUMBER
  • SQLITE_LIMIT_VDBE_OP
  • SQLITE_LOCKED
  • SQLITE_LOCKED_SHAREDCACHE
  • SQLITE_LOCK_EXCLUSIVE
  • SQLITE_LOCK_NONE
  • SQLITE_LOCK_PENDING
  • SQLITE_LOCK_RESERVED
  • SQLITE_LOCK_SHARED
  • SQLITE_MISMATCH
  • SQLITE_MISUSE
  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_LRU
  • SQLITE_MUTEX_STATIC_LRU2
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_OPEN
  • SQLITE_MUTEX_STATIC_PMEM
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_NOLFS
  • SQLITE_NOMEM
  • SQLITE_NOTADB
  • SQLITE_NOTFOUND
  • SQLITE_NULL
  • SQLITE_OK
  • SQLITE_OPEN_AUTOPROXY
  • SQLITE_OPEN_CREATE
  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE
  • SQLITE_OPEN_FULLMUTEX
  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
  • SQLITE_OPEN_NOMUTEX
  • SQLITE_OPEN_PRIVATECACHE
  • SQLITE_OPEN_READONLY
  • SQLITE_OPEN_READWRITE
  • SQLITE_OPEN_SHAREDCACHE
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_URI
  • SQLITE_OPEN_WAL
  • SQLITE_PERM
  • SQLITE_PRAGMA
  • SQLITE_PROTOCOL
  • SQLITE_RANGE
  • SQLITE_READ
  • SQLITE_READONLY
  • SQLITE_READONLY_CANTLOCK
  • SQLITE_READONLY_RECOVERY
  • SQLITE_REINDEX
  • SQLITE_REPLACE
  • SQLITE_ROLLBACK
  • SQLITE_ROW
  • SQLITE_SAVEPOINT
  • SQLITE_SCHEMA
  • SQLITE_SELECT
  • SQLITE_SET_LOCKPROXYFILE
  • SQLITE_SHM_EXCLUSIVE
  • SQLITE_SHM_LOCK
  • SQLITE_SHM_NLOCK
  • SQLITE_SHM_SHARED
  • SQLITE_SHM_UNLOCK
  • SQLITE_SOURCE_ID
  • SQLITE_STATIC
  • SQLITE_STATUS_MALLOC_COUNT
  • SQLITE_STATUS_MALLOC_SIZE
  • SQLITE_STATUS_MEMORY_USED
  • SQLITE_STATUS_PAGECACHE_OVERFLOW
  • SQLITE_STATUS_PAGECACHE_SIZE
  • SQLITE_STATUS_PAGECACHE_USED
  • SQLITE_STATUS_PARSER_STACK
  • SQLITE_STATUS_SCRATCH_OVERFLOW
  • SQLITE_STATUS_SCRATCH_SIZE
  • SQLITE_STATUS_SCRATCH_USED
  • SQLITE_STMTSTATUS_AUTOINDEX
  • SQLITE_STMTSTATUS_FULLSCAN_STEP
  • SQLITE_STMTSTATUS_SORT
  • SQLITE_SYNC_DATAONLY
  • SQLITE_SYNC_FULL
  • SQLITE_SYNC_NORMAL
  • SQLITE_TESTCTRL_ALWAYS
  • SQLITE_TESTCTRL_ASSERT
  • SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS
  • SQLITE_TESTCTRL_BITVEC_TEST
  • SQLITE_TESTCTRL_FAULT_INSTALL
  • SQLITE_TESTCTRL_FIRST
  • SQLITE_TESTCTRL_ISKEYWORD
  • SQLITE_TESTCTRL_LAST
  • SQLITE_TESTCTRL_LOCALTIME_FAULT
  • SQLITE_TESTCTRL_OPTIMIZATIONS
  • SQLITE_TESTCTRL_PENDING_BYTE
  • SQLITE_TESTCTRL_PGHDRSZ
  • SQLITE_TESTCTRL_PRNG_RESET
  • SQLITE_TESTCTRL_PRNG_RESTORE
  • SQLITE_TESTCTRL_PRNG_SAVE
  • SQLITE_TESTCTRL_RESERVE
  • SQLITE_TESTCTRL_SCRATCHMALLOC
  • SQLITE_TEXT
  • SQLITE_TOOBIG
  • SQLITE_TRANSACTION
  • SQLITE_TRANSIENT
  • SQLITE_UPDATE
  • SQLITE_UTF16
  • SQLITE_UTF16BE
  • SQLITE_UTF16LE
  • SQLITE_UTF16_ALIGNED
  • SQLITE_UTF8
  • SQLITE_VERSION
  • SQLITE_VERSION_NUMBER
  • SQLITE_VTAB_CONSTRAINT_SUPPORT

Other lists: Objects and Functions.


Choose any three.

SQLite C Interface

SQL Function Context Object

typedef struct sqlite3_context sqlite3_context;

The context in which an SQL function executes is stored in an sqlite3_context object. A pointer to an sqlite3_context object is always first parameter to application-defined SQL functions. The application-defined SQL function implementation will pass this pointer through into calls to sqlite3_result(), sqlite3_aggregate_context(), sqlite3_user_data(), sqlite3_context_db_handle(), sqlite3_get_auxdata(), and/or sqlite3_set_auxdata().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Database Connection For Functions

sqlite3 *sqlite3_context_db_handle(sqlite3_context*);

The sqlite3_context_db_handle() interface returns a copy of the pointer to the database connection (the 1st parameter) of the sqlite3_create_function() and sqlite3_create_function16() routines that originally registered the application defined function.

See also lists of Objects, Constants, and Functions.


SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Define New Collating Sequences

int sqlite3_create_collation(
  sqlite3*,
  const char *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);
int sqlite3_create_collation_v2(
  sqlite3*,
  const char *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*),
  void(*xDestroy)(void*)
);
int sqlite3_create_collation16(
  sqlite3*,
  const void *zName,
  int eTextRep,
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);

These functions add, remove, or modify a collation associated with the database connection specified as the first argument.

The name of the collation is a UTF-8 string for sqlite3_create_collation() and sqlite3_create_collation_v2() and a UTF-16 string in native byte order for sqlite3_create_collation16(). Collation names that compare equal according to sqlite3_strnicmp() are considered to be the same name.

The third argument (eTextRep) must be one of the constants:

  • SQLITE_UTF8,
  • SQLITE_UTF16LE,
  • SQLITE_UTF16BE,
  • SQLITE_UTF16, or
  • SQLITE_UTF16_ALIGNED.
The eTextRep argument determines the encoding of strings passed to the collating function callback, xCallback. The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED values for eTextRep force strings to be UTF16 with native byte order. The SQLITE_UTF16_ALIGNED value for eTextRep forces strings to begin on an even byte address.

The fourth argument, pArg, is an application data pointer that is passed through as the first argument to the collating function callback.

The fifth argument, xCallback, is a pointer to the collating function. Multiple collating functions can be registered using the same name but with different eTextRep parameters and SQLite will use whichever function requires the least amount of data transformation. If the xCallback argument is NULL then the collating function is deleted. When all collating functions having the same name are deleted, that collation is no longer usable.

The collating function callback is invoked with a copy of the pArg application data pointer and with two strings in the encoding specified by the eTextRep argument. The collating function must return an integer that is negative, zero, or positive if the first string is less than, equal to, or greater than the second, respectively. A collating function must always return the same answer given the same inputs. If two or more collating functions are registered to the same collation name (using different eTextRep values) then all must give an equivalent answer when invoked with equivalent strings. The collating function must obey the following properties for all strings A, B, and C:

  1. If A==B then B==A.
  2. If A==B and B==C then A==C.
  3. If A<B THEN B>A.
  4. If A<B and B<C then A<C.

If a collating function fails any of the above constraints and that collating function is registered and used, then the behavior of SQLite is undefined.

The sqlite3_create_collation_v2() works like sqlite3_create_collation() with the addition that the xDestroy callback is invoked on pArg when the collating function is deleted. Collating functions are deleted when they are overridden by later calls to the collation creation functions or when the database connection is closed using sqlite3_close().

The xDestroy callback is not called if the sqlite3_create_collation_v2() function fails. Applications that invoke sqlite3_create_collation_v2() with a non-NULL xDestroy argument should check the return code and dispose of the application data pointer themselves rather than expecting SQLite to deal with it for them. This is different from every other SQLite interface. The inconsistency is unfortunate but cannot be changed without breaking backwards compatibility.

See also: sqlite3_collation_needed() and sqlite3_collation_needed16().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Create Or Redefine SQL Functions

int sqlite3_create_function(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function16(
  sqlite3 *db,
  const void *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function_v2(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*),
  void(*xDestroy)(void*)
);

These functions (collectively known as "function creation routines") are used to add SQL functions or aggregates or to redefine the behavior of existing SQL functions or aggregates. The only differences between these routines are the text encoding expected for the second parameter (the name of the function being created) and the presence or absence of a destructor callback for the application data pointer.

The first parameter is the database connection to which the SQL function is to be added. If an application uses more than one database connection then application-defined SQL functions must be added to each database connection separately.

The second parameter is the name of the SQL function to be created or redefined. The length of the name is limited to 255 bytes in a UTF-8 representation, exclusive of the zero-terminator. Note that the name length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. Any attempt to create a function with a longer name will result in SQLITE_MISUSE being returned.

The third parameter (nArg) is the number of arguments that the SQL function or aggregate takes. If this parameter is -1, then the SQL function or aggregate may take any number of arguments between 0 and the limit set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG). If the third parameter is less than -1 or greater than 127 then the behavior is undefined.

The fourth parameter, eTextRep, specifies what text encoding this SQL function prefers for its parameters. Every SQL function implementation must be able to work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be more efficient with one encoding than another. An application may invoke sqlite3_create_function() or sqlite3_create_function16() multiple times with the same function but with different values of eTextRep. When multiple implementations of the same function are available, SQLite will pick the one that involves the least amount of data conversion. If there is only a single implementation which does not care what text encoding is used, then the fourth argument should be SQLITE_ANY.

The fifth parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using sqlite3_user_data().

The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are pointers to C-language functions that implement the SQL function or aggregate. A scalar SQL function requires an implementation of the xFunc callback only; NULL pointers must be passed as the xStep and xFinal parameters. An aggregate SQL function requires an implementation of xStep and xFinal and NULL pointer must be passed for xFunc. To delete an existing SQL function or aggregate, pass NULL pointers for all three function callbacks.

If the ninth parameter to sqlite3_create_function_v2() is not NULL, then it is destructor for the application data pointer. The destructor is invoked when the function is deleted, either by being overloaded or when the database connection closes. The destructor is also invoked if the call to sqlite3_create_function_v2() fails. When the destructor callback of the tenth parameter is invoked, it is passed a single argument which is a copy of the application data pointer which was the fifth parameter to sqlite3_create_function_v2().

It is permitted to register multiple implementations of the same functions with the same name but with either differing numbers of arguments or differing preferred text encodings. SQLite will use the implementation that most closely matches the way in which the SQL function is used. A function implementation with a non-negative nArg parameter is a better match than a function implementation with a negative nArg. A function where the preferred text encoding matches the database encoding is a better match than a function where the encoding is different. A function where the encoding difference is between UTF16le and UTF16be is a closer match than a function where the encoding difference is between UTF8 and UTF16.

Built-in functions may be overloaded by new application-defined functions.

An application-defined function is permitted to call other SQLite interfaces. However, such calls must not close the database connection nor finalize or reset the prepared statement in which the function is running.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Register A Virtual Table Implementation

int sqlite3_create_module(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData          /* Client data for xCreate/xConnect */
);
int sqlite3_create_module_v2(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData,         /* Client data for xCreate/xConnect */
  void(*xDestroy)(void*)     /* Module destructor function */
);

These routines are used to register a new virtual table module name. Module names must be registered before creating a new virtual table using the module and before using a preexisting virtual table for the module.

The module name is registered on the database connection specified by the first parameter. The name of the module is given by the second parameter. The third parameter is a pointer to the implementation of the virtual table module. The fourth parameter is an arbitrary client data pointer that is passed through into the xCreate and xConnect methods of the virtual table module when a new virtual table is be being created or reinitialized.

The sqlite3_create_module_v2() interface has a fifth parameter which is a pointer to a destructor for the pClientData. SQLite will invoke the destructor function (if it is not NULL) when SQLite no longer needs the pClientData pointer. The destructor will also be invoked if the call to sqlite3_create_module_v2() fails. The sqlite3_create_module() interface is equivalent to sqlite3_create_module_v2() with a NULL destructor.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Number of columns in a result set

int sqlite3_data_count(sqlite3_stmt *pStmt);

The sqlite3_data_count(P) interface returns the number of columns in the current row of the result set of prepared statement P. If prepared statement P does not have results ready to return (via calls to the sqlite3_column_*() of interfaces) then sqlite3_data_count(P) returns 0. The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. The sqlite3_data_count(P) routine returns 0 if the previous call to sqlite3_step(P) returned SQLITE_DONE. The sqlite3_data_count(P) will return non-zero if previous call to sqlite3_step(P) returned SQLITE_ROW, except in the case of the PRAGMA incremental_vacuum where it always returns zero since each step of that multi-step pragma returns 0 columns of data.

See also: sqlite3_column_count()

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Configure database connections

int sqlite3_db_config(sqlite3*, int op, ...);

The sqlite3_db_config() interface is used to make configuration changes to a database connection. The interface is similar to sqlite3_config() except that the changes apply to a single database connection (specified in the first argument).

The second argument to sqlite3_db_config(D,V,...) is the configuration verb - an integer code that indicates what aspect of the database connection is being configured. Subsequent arguments vary depending on the configuration verb.

Calls to sqlite3_db_config() return SQLITE_OK if and only if the call is considered successful.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Find The Database Handle Of A Prepared Statement

sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

The sqlite3_db_handle interface returns the database connection handle to which a prepared statement belongs. The database connection returned by sqlite3_db_handle is the same database connection that was the first argument to the sqlite3_prepare_v2() call (or its variants) that was used to create the statement in the first place.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Retrieve the mutex for a database connection

sqlite3_mutex *sqlite3_db_mutex(sqlite3*);

This interface returns a pointer the sqlite3_mutex object that serializes access to the database connection given in the argument when the threading mode is Serialized. If the threading mode is Single-thread or Multi-thread then this routine returns a NULL pointer.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Database Connection Status

int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);

This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQLITE_DBSTATUS options, that determines the parameter to interrogate. The set of SQLITE_DBSTATUS options is likely to grow in future releases of SQLite.

The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.

The sqlite3_db_status() routine returns SQLITE_OK on success and a non-zero error code on failure.

See also: sqlite3_status() and sqlite3_stmt_status().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Declare The Schema Of A Virtual Table

int sqlite3_declare_vtab(sqlite3*, const char *zSQL);

The xCreate and xConnect methods of a virtual table module call this interface to declare the format (the names and datatypes of the columns) of the virtual tables they implement.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Enable Or Disable Extension Loading

int sqlite3_enable_load_extension(sqlite3 *db, int onoff);

So as not to open security holes in older applications that are unprepared to deal with extension loading, and as a means of disabling extension loading while evaluating user-entered SQL, the following API is provided to turn the sqlite3_load_extension() mechanism on and off.

Extension loading is off by default. See ticket #1863. Call the sqlite3_enable_load_extension() routine with onoff==1 to turn extension loading on and call it with onoff==0 to turn it back off again.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Enable Or Disable Shared Pager Cache

int sqlite3_enable_shared_cache(int);

This routine enables or disables the sharing of the database cache and schema data structures between connections to the same database. Sharing is enabled if the argument is true and disabled if the argument is false.

Cache sharing is enabled and disabled for an entire process. This is a change as of SQLite version 3.5.0. In prior versions of SQLite, sharing was enabled or disabled for each thread separately.

The cache sharing mode set by this interface effects all subsequent calls to sqlite3_open(), sqlite3_open_v2(), and sqlite3_open16(). Existing database connections continue use the sharing mode that was in effect at the time they were opened.

This routine returns SQLITE_OK if shared cache was enabled or disabled successfully. An error code is returned otherwise.

Shared cache is disabled by default. But this might change in future releases of SQLite. Applications that care about shared cache setting should set it explicitly.

See Also: SQLite Shared-Cache Mode

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Error Codes And Messages

int sqlite3_errcode(sqlite3 *db);
int sqlite3_extended_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);

The sqlite3_errcode() interface returns the numeric result code or extended result code for the most recent failed sqlite3_* API call associated with a database connection. If a prior API call failed but the most recent API call succeeded, the return value from sqlite3_errcode() is undefined. The sqlite3_extended_errcode() interface is the same except that it always returns the extended result code even when extended result codes are disabled.

The sqlite3_errmsg() and sqlite3_errmsg16() return English-language text that describes the error, as either UTF-8 or UTF-16 respectively. Memory to hold the error message string is managed internally. The application does not need to worry about freeing the result. However, the error string might be overwritten or deallocated by subsequent calls to other SQLite interface functions.

When the serialized threading mode is in use, it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to these interfaces. When that happens, the second error will be reported since these interfaces always report the most recent result. To avoid this, each thread can obtain exclusive use of the database connection D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) after all calls to the interfaces listed here are completed.

If an interface fails with SQLITE_MISUSE, that means the interface was invoked incorrectly by the application. In that case, the error code and message may or may not be set.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

One-Step Query Execution Interface

int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

The sqlite3_exec() interface is a convenience wrapper around sqlite3_prepare_v2(), sqlite3_step(), and sqlite3_finalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code.

The sqlite3_exec() interface runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed into its 2nd argument, in the context of the database connection passed in as its 1st argument. If the callback function of the 3rd argument to sqlite3_exec() is not NULL, then it is invoked for each result row coming out of the evaluated SQL statements. The 4th argument to sqlite3_exec() is relayed through to the 1st argument of each callback invocation. If the callback pointer to sqlite3_exec() is NULL, then no callback is ever invoked and result rows are ignored.

If an error occurs while evaluating the SQL statements passed into sqlite3_exec(), then execution of the current statement stops and subsequent statements are skipped. If the 5th parameter to sqlite3_exec() is not NULL then any error message is written into memory obtained from sqlite3_malloc() and passed back through the 5th parameter. To avoid memory leaks, the application should invoke sqlite3_free() on error message strings returned through the 5th parameter of of sqlite3_exec() after the error message string is no longer needed. If the 5th parameter to sqlite3_exec() is not NULL and no errors occur, then sqlite3_exec() sets the pointer in its 5th parameter to NULL before returning.

If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() routine returns SQLITE_ABORT without invoking the callback again and without running any subsequent SQL statements.

The 2nd argument to the sqlite3_exec() callback function is the number of columns in the result. The 3rd argument to the sqlite3_exec() callback is an array of pointers to strings obtained as if from sqlite3_column_text(), one for each column. If an element of a result row is NULL then the corresponding string pointer for the sqlite3_exec() callback is a NULL pointer. The 4th argument to the sqlite3_exec() callback is an array of pointers to strings where each entry represents the name of corresponding result column as obtained from sqlite3_column_name().

If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer to an empty string, or a pointer that contains only whitespace and/or SQL comments, then no SQL statements are evaluated and the database is not changed.

Restrictions:

  • The application must insure that the 1st parameter to sqlite3_exec() is a valid and open database connection.
  • The application must not close database connection specified by the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
  • The application must not modify the SQL statement text passed into the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.

See also lists of Objects, Constants, and Functions.


Experimental Interfaces

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Experimental And Deprecated Interfaces

SQLite interfaces can be subdivided into three categories:

  1. Stable
  2. Experimental
  3. Deprecated

Stable interfaces will be maintained indefinitely in a backwards compatible way. An application that uses only stable interfaces should always be able to relink against a newer version of SQLite without any changes.

Experimental interfaces are subject to change. Applications that use experimental interfaces may need to be modified when upgrading to a newer SQLite release, though this is rare. When new interfaces are added to SQLite, they generally begin as experimental interfaces. After an interface has been in use for a while and the developers are confident that the design of the interface is sound and worthy of long-term support, the interface is marked as stable.

Deprecated interfaces have been superceded by better methods of accomplishing the same thing and should be avoided in new applications. Deprecated interfaces continue to be supported for the sake of backwards compatibility. At some point in the future, it is possible that deprecated interfaces may be removed.

Key points:

  • Experimental interfaces are subject to change and/or removal at any time.
  • Deprecated interfaces should not be used in new code and might be removed in some future release.


Choose any three.

SQLite C Interface

Enable Or Disable Extended Result Codes

int sqlite3_extended_result_codes(sqlite3*, int onoff);

The sqlite3_extended_result_codes() routine enables or disables the extended result codes feature of SQLite. The extended result codes are disabled by default for historical compatibility.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

OS Interface Open File Handle

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

An sqlite3_file object represents an open file in the OS interface layer. Individual OS interface implementations will want to subclass this object by appending additional fields for their own use. The pMethods entry is a pointer to an sqlite3_io_methods object that defines methods for performing I/O operations on the open file.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Low-Level Control Of Database Files

int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

The sqlite3_file_control() interface makes a direct call to the xFileControl method for the sqlite3_io_methods object associated with a particular database identified by the second argument. The name of the database is "main" for the main database or "temp" for the TEMP database, or the name that appears after the AS keyword for databases that are added using the ATTACH SQL command. A NULL pointer can be used in place of "main" to refer to the main database file. The third and fourth parameters to this routine are passed directly through to the second and third parameters of the xFileControl method. The return value of the xFileControl method becomes the return value of this routine.

The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes a pointer to the underlying sqlite3_file object to be written into the space pointed to by the 4th parameter. The SQLITE_FCNTL_FILE_POINTER case is a short-circuit path which does not actually invoke the underlying sqlite3_io_methods.xFileControl method.

If the second parameter (zDbName) does not match the name of any open database file, then SQLITE_ERROR is returned. This error code is not remembered and will not be recalled by sqlite3_errcode() or sqlite3_errmsg(). The underlying xFileControl method might also return SQLITE_ERROR. There is no way to distinguish between an incorrect zDbName and an SQLITE_ERROR return from the underlying xFileControl method.

See also: SQLITE_FCNTL_LOCKSTATE

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Destroy A Prepared Statement Object

int sqlite3_finalize(sqlite3_stmt *pStmt);

The sqlite3_finalize() function is called to delete a prepared statement. If the most recent evaluation of the statement encountered no errors or if the statement is never been evaluated, then sqlite3_finalize() returns SQLITE_OK. If the most recent evaluation of statement S failed, then sqlite3_finalize(S) returns the appropriate error code or extended error code.

The sqlite3_finalize(S) routine can be called at any point during the life cycle of prepared statement S: before statement S is ever evaluated, after one or more calls to sqlite3_reset(), or after any call to sqlite3_step() regardless of whether or not the statement has completed execution.

Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.

The application must finalize every prepared statement in order to avoid resource leaks. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Memory Allocation Subsystem

void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);

The SQLite core uses these three routines for all of its own internal memory allocation needs. "Core" in the previous sentence does not include operating-system specific VFS implementation. The Windows VFS uses native malloc() and free() for some operations.

The sqlite3_malloc() routine returns a pointer to a block of memory at least N bytes in length, where N is the parameter. If sqlite3_malloc() is unable to obtain sufficient free memory, it returns a NULL pointer. If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() returns a NULL pointer.

Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() or sqlite3_realloc() releases that memory so that it might be reused. The sqlite3_free() routine is a no-op if is called with a NULL pointer. Passing a NULL pointer to sqlite3_free() is harmless. After being freed, memory should neither be read nor written. Even reading previously freed memory might result in a segmentation fault or other severe error. Memory corruption, a segmentation fault, or other severe error might result if sqlite3_free() is called with a non-NULL pointer that was not obtained from sqlite3_malloc() or sqlite3_realloc().

The sqlite3_realloc() interface attempts to resize a prior memory allocation to be at least N bytes, where N is the second parameter. The memory allocation to be resized is the first parameter. If the first parameter to sqlite3_realloc() is a NULL pointer then its behavior is identical to calling sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). If the second parameter to sqlite3_realloc() is zero or negative then the behavior is exactly the same as calling sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). sqlite3_realloc() returns a pointer to a memory allocation of at least N bytes in size or NULL if sufficient memory is unavailable. If M is the size of the prior allocation, then min(N,M) bytes of the prior allocation are copied into the beginning of buffer returned by sqlite3_realloc() and the prior allocation is freed. If sqlite3_realloc() returns NULL, then the prior allocation is not freed.

The memory returned by sqlite3_malloc() and sqlite3_realloc() is always aligned to at least an 8 byte boundary, or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC compile-time option is used.

In SQLite version 3.5.0 and 3.5.1, it was possible to define the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in implementation of these routines to be omitted. That capability is no longer provided. Only built-in memory allocators can be used.

The Windows OS interface layer calls the system malloc() and free() directly when converting filenames between the UTF-8 encoding used by SQLite and whatever filename encoding is used by the particular Windows installation. Memory allocation errors are detected, but they are reported back as SQLITE_CANTOPEN or SQLITE_IOERR rather than SQLITE_NOMEM.

The pointer arguments to sqlite3_free() and sqlite3_realloc() must be either NULL or else pointers obtained from a prior invocation of sqlite3_malloc() or sqlite3_realloc() that have not yet been released.

The application must not read or write any part of a block of memory after it has been released using sqlite3_free() or sqlite3_realloc().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Convenience Routines For Running Queries

int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);
void sqlite3_free_table(char **result);

This is a legacy interface that is preserved for backwards compatibility. Use of this interface is not recommended.

Definition: A result table is memory data structure created by the sqlite3_get_table() interface. A result table records the complete query results from one or more queries.

The table conceptually has a number of rows and columns. But these numbers are not part of the result table itself. These numbers are obtained separately. Let N be the number of rows and M be the number of columns.

A result table is an array of pointers to zero-terminated UTF-8 strings. There are (N+1)*M elements in the array. The first M pointers point to zero-terminated strings that contain the names of the columns. The remaining entries all point to query results. NULL values result in NULL pointers. All other values are in their UTF-8 zero-terminated string representation as returned by sqlite3_column_text().

A result table might consist of one or more memory allocations. It is not safe to pass a result table directly to sqlite3_free(). A result table should be deallocated using sqlite3_free_table().

As an example of the result table format, suppose a query result is as follows:

Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21

There are two column (M==2) and three rows (N==3). Thus the result table has 8 entries. Suppose the result table is stored in an array names azResult. Then azResult holds this content:

azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";

The sqlite3_get_table() function evaluates one or more semicolon-separated SQL statements in the zero-terminated UTF-8 string of its 2nd parameter and returns a result table to the pointer given in its 3rd parameter.

After the application has finished with the result from sqlite3_get_table(), it must pass the result table pointer to sqlite3_free_table() in order to release the memory that was malloced. Because of the way the sqlite3_malloc() happens within sqlite3_get_table(), the calling function must not try to call sqlite3_free() directly. Only sqlite3_free_table() is able to release the memory properly and safely.

The sqlite3_get_table() interface is implemented as a wrapper around sqlite3_exec(). The sqlite3_get_table() routine does not have access to any internal data structures of SQLite. It uses only the public interface defined here. As a consequence, errors that occur in the wrapper layer outside of the internal sqlite3_exec() call are not reflected in subsequent calls to sqlite3_errcode() or sqlite3_errmsg().

See also lists of Objects, Constants, and Functions.


List Of SQLite Functions

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Functions:

Note: Functions marked with "(exp)" are experimental and functions marked with (obs) are deprecated.

  • sqlite3_aggregate_context
  • sqlite3_aggregate_count (obs)
  • sqlite3_auto_extension
  • sqlite3_backup_finish
  • sqlite3_backup_init
  • sqlite3_backup_pagecount
  • sqlite3_backup_remaining
  • sqlite3_backup_step
  • sqlite3_bind_blob
  • sqlite3_bind_double
  • sqlite3_bind_int
  • sqlite3_bind_int64
  • sqlite3_bind_null
  • sqlite3_bind_parameter_count
  • sqlite3_bind_parameter_index
  • sqlite3_bind_parameter_name
  • sqlite3_bind_text
  • sqlite3_bind_text16
  • sqlite3_bind_value
  • sqlite3_bind_zeroblob
  • sqlite3_blob_bytes
  • sqlite3_blob_close
  • sqlite3_blob_open
  • sqlite3_blob_read
  • sqlite3_blob_reopen
  • sqlite3_blob_write
  • sqlite3_busy_handler
  • sqlite3_busy_timeout
  • sqlite3_changes
  • sqlite3_clear_bindings
  • sqlite3_close
  • sqlite3_collation_needed
  • sqlite3_collation_needed16
  • sqlite3_column_blob
  • sqlite3_column_bytes
  • sqlite3_column_bytes16
  • sqlite3_column_count
  • sqlite3_column_database_name
  • sqlite3_column_database_name16
  • sqlite3_column_decltype
  • sqlite3_column_decltype16
  • sqlite3_column_double
  • sqlite3_column_int
  • sqlite3_column_int64
  • sqlite3_column_name
  • sqlite3_column_name16
  • sqlite3_column_origin_name
  • sqlite3_column_origin_name16
  • sqlite3_column_table_name
  • sqlite3_column_table_name16
  • sqlite3_column_text
  • sqlite3_column_text16
  • sqlite3_column_type
  • sqlite3_column_value
  • sqlite3_commit_hook
  • sqlite3_compileoption_get
  • sqlite3_compileoption_used
  • sqlite3_complete
  • sqlite3_complete16
  • sqlite3_config
  • sqlite3_context_db_handle
  • sqlite3_create_collation
  • sqlite3_create_collation16
  • sqlite3_create_collation_v2
  • sqlite3_create_function
  • sqlite3_create_function16
  • sqlite3_create_function_v2
  • sqlite3_create_module
  • sqlite3_create_module_v2
  • sqlite3_data_count
  • sqlite3_db_config
  • sqlite3_db_handle
  • sqlite3_db_mutex
  • sqlite3_db_status
  • sqlite3_declare_vtab
  • sqlite3_enable_load_extension
  • sqlite3_enable_shared_cache
  • sqlite3_errcode
  • sqlite3_errmsg
  • sqlite3_errmsg16
  • sqlite3_exec
  • sqlite3_expired (obs)
  • sqlite3_extended_errcode
  • sqlite3_extended_result_codes
  • sqlite3_file_control
  • sqlite3_finalize
  • sqlite3_free
  • sqlite3_free_table
  • sqlite3_get_autocommit
  • sqlite3_get_auxdata
  • sqlite3_get_table
  • sqlite3_global_recover (obs)
  • sqlite3_initialize
  • sqlite3_interrupt
  • sqlite3_last_insert_rowid
  • sqlite3_libversion
  • sqlite3_libversion_number
  • sqlite3_limit
  • sqlite3_load_extension
  • sqlite3_log
  • sqlite3_malloc
  • sqlite3_memory_alarm (obs)
  • sqlite3_memory_highwater
  • sqlite3_memory_used
  • sqlite3_mprintf
  • sqlite3_mutex_alloc
  • sqlite3_mutex_enter
  • sqlite3_mutex_free
  • sqlite3_mutex_held
  • sqlite3_mutex_leave
  • sqlite3_mutex_notheld
  • sqlite3_mutex_try
  • sqlite3_next_stmt
  • sqlite3_open
  • sqlite3_open16
  • sqlite3_open_v2
  • sqlite3_os_end
  • sqlite3_os_init
  • sqlite3_overload_function
  • sqlite3_prepare
  • sqlite3_prepare16
  • sqlite3_prepare16_v2
  • sqlite3_prepare_v2
  • sqlite3_profile
  • sqlite3_progress_handler
  • sqlite3_randomness
  • sqlite3_realloc
  • sqlite3_release_memory
  • sqlite3_reset
  • sqlite3_reset_auto_extension
  • sqlite3_result_blob
  • sqlite3_result_double
  • sqlite3_result_error
  • sqlite3_result_error16
  • sqlite3_result_error_code
  • sqlite3_result_error_nomem
  • sqlite3_result_error_toobig
  • sqlite3_result_int
  • sqlite3_result_int64
  • sqlite3_result_null
  • sqlite3_result_text
  • sqlite3_result_text16
  • sqlite3_result_text16be
  • sqlite3_result_text16le
  • sqlite3_result_value
  • sqlite3_result_zeroblob
  • sqlite3_rollback_hook
  • sqlite3_set_authorizer
  • sqlite3_set_auxdata
  • sqlite3_shutdown
  • sqlite3_sleep
  • sqlite3_snprintf
  • sqlite3_soft_heap_limit (obs)
  • sqlite3_soft_heap_limit64
  • sqlite3_sourceid
  • sqlite3_sql
  • sqlite3_status
  • sqlite3_step
  • sqlite3_stmt_readonly
  • sqlite3_stmt_status
  • sqlite3_strnicmp
  • sqlite3_table_column_metadata
  • sqlite3_test_control
  • sqlite3_thread_cleanup (obs)
  • sqlite3_threadsafe
  • sqlite3_total_changes
  • sqlite3_trace
  • sqlite3_transfer_bindings (obs)
  • sqlite3_unlock_notify
  • sqlite3_update_hook
  • sqlite3_uri_parameter
  • sqlite3_user_data
  • sqlite3_value_blob
  • sqlite3_value_bytes
  • sqlite3_value_bytes16
  • sqlite3_value_double
  • sqlite3_value_int
  • sqlite3_value_int64
  • sqlite3_value_numeric_type
  • sqlite3_value_text
  • sqlite3_value_text16
  • sqlite3_value_text16be
  • sqlite3_value_text16le
  • sqlite3_value_type
  • sqlite3_version,
  • sqlite3_vfs_find
  • sqlite3_vfs_register
  • sqlite3_vfs_unregister
  • sqlite3_vmprintf
  • sqlite3_vsnprintf
  • sqlite3_vtab_config
  • sqlite3_vtab_on_conflict
  • sqlite3_wal_autocheckpoint
  • sqlite3_wal_checkpoint
  • sqlite3_wal_checkpoint_v2
  • sqlite3_wal_hook

Other lists: Constants and Objects.


Choose any three.

SQLite C Interface

Test For Auto-Commit Mode

int sqlite3_get_autocommit(sqlite3*);

The sqlite3_get_autocommit() interface returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively. Autocommit mode is on by default. Autocommit mode is disabled by a BEGIN statement. Autocommit mode is re-enabled by a COMMIT or ROLLBACK.

If certain kinds of errors occur on a statement within a multi-statement transaction (errors including SQLITE_FULL, SQLITE_IOERR, SQLITE_NOMEM, SQLITE_BUSY, and SQLITE_INTERRUPT) then the transaction might be rolled back automatically. The only way to find out whether SQLite automatically rolled back the transaction after an error is to use this function.

If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Function Auxiliary Data

void *sqlite3_get_auxdata(sqlite3_context*, int N);
void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

The following two functions may be used by scalar SQL functions to associate metadata with argument values. If the same value is passed to multiple invocations of the same SQL function during query execution, under some circumstances the associated metadata may be preserved. This may be used, for example, to add a regular-expression matching scalar function. The compiled version of the regular expression is stored as metadata associated with the SQL value passed as the regular expression pattern. The compiled regular expression can be reused on multiple invocations of the same function so that the original pattern string does not need to be recompiled on each invocation.

The sqlite3_get_auxdata() interface returns a pointer to the metadata associated by the sqlite3_set_auxdata() function with the Nth argument value to the application-defined function. If no metadata has been ever been set for the Nth argument of the function, or if the corresponding function parameter has changed since the meta-data was set, then sqlite3_get_auxdata() returns a NULL pointer.

The sqlite3_set_auxdata() interface saves the metadata pointed to by its 3rd parameter as the metadata for the N-th argument of the application-defined function. Subsequent calls to sqlite3_get_auxdata() might return this data, if it has not been destroyed. If it is not NULL, SQLite will invoke the destructor function given by the 4th parameter to sqlite3_set_auxdata() on the metadata when the corresponding function parameter changes or when the SQL statement completes, whichever comes first.

SQLite is free to call the destructor and drop metadata on any parameter of any function at any time. The only guarantee is that the destructor will be called before the metadata is dropped.

In practice, metadata is preserved between function calls for expressions that are constant at compile time. This includes literal values and parameters.

These routines must be called from the same thread in which the SQL function is running.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Indexing Information

struct sqlite3_index_info {
  /* Inputs */
  int nConstraint;           /* Number of entries in aConstraint */
  struct sqlite3_index_constraint {
     int iColumn;              /* Column on left-hand side of constraint */
     unsigned char op;         /* Constraint operator */
     unsigned char usable;     /* True if this constraint is usable */
     int iTermOffset;          /* Used internally - xBestIndex should ignore */
  } *aConstraint;            /* Table of WHERE clause constraints */
  int nOrderBy;              /* Number of terms in the ORDER BY clause */
  struct sqlite3_index_orderby {
     int iColumn;              /* Column number */
     unsigned char desc;       /* True for DESC.  False for ASC. */
  } *aOrderBy;               /* The ORDER BY clause */
  /* Outputs */
  struct sqlite3_index_constraint_usage {
    int argvIndex;           /* if >0, constraint is part of argv to xFilter */
    unsigned char omit;      /* Do not code a test for this constraint */
  } *aConstraintUsage;
  int idxNum;                /* Number used to identify the index */
  char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
  int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
  int orderByConsumed;       /* True if output is already ordered */
  double estimatedCost;      /* Estimated cost of using this index */
};

The sqlite3_index_info structure and its substructures is used as part of the virtual table interface to pass information into and receive the reply from the xBestIndex method of a virtual table module. The fields under **Inputs** are the inputs to xBestIndex and are read-only. xBestIndex inserts its results into the **Outputs** fields.

The aConstraint[] array records WHERE clause constraints of the form:

column OP expr

where OP is =, <, <=, >, or >=. The particular operator is stored in aConstraint[].op using one of the SQLITE_INDEX_CONSTRAINT_ values. The index of the column is stored in aConstraint[].iColumn. aConstraint[].usable is TRUE if the expr on the right-hand side can be evaluated (and thus the constraint is usable) and false if it cannot.

The optimizer automatically inverts terms of the form "expr OP column" and makes other simplifications to the WHERE clause in an attempt to get as many WHERE clause terms into the form shown above as possible. The aConstraint[] array only reports WHERE clause terms that are relevant to the particular virtual table being queried.

Information about the ORDER BY clause is stored in aOrderBy[]. Each term of aOrderBy records a column of the ORDER BY clause.

The xBestIndex method must fill aConstraintUsage[] with information about what parameters to pass to xFilter. If argvIndex>0 then the right-hand side of the corresponding aConstraint[] is evaluated and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit is true, then the constraint is assumed to be fully handled by the virtual table and is not checked again by SQLite.

The idxNum and idxPtr values are recorded and passed into the xFilter method. sqlite3_free() is used to free idxPtr if and only if needToFreeIdxPtr is true.

The orderByConsumed means that output from xFilter/xNext will occur in the correct order to satisfy the ORDER BY clause so that no separate sorting step is required.

The estimatedCost value is an estimate of the cost of doing the particular lookup. A full scan of a table with N entries should have a cost of N. A binary search of a table of N entries should have a cost of approximately log(N).

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Initialize The SQLite Library

int sqlite3_initialize(void);
int sqlite3_shutdown(void);
int sqlite3_os_init(void);
int sqlite3_os_end(void);

The sqlite3_initialize() routine initializes the SQLite library. The sqlite3_shutdown() routine deallocates any resources that were allocated by sqlite3_initialize(). These routines are designed to aid in process initialization and shutdown on embedded systems. Workstation applications using SQLite normally do not need to invoke either of these routines.

A call to sqlite3_initialize() is an "effective" call if it is the first time sqlite3_initialize() is invoked during the lifetime of the process, or if it is the first time sqlite3_initialize() is invoked following a call to sqlite3_shutdown(). Only an effective call of sqlite3_initialize() does any initialization. All other calls are harmless no-ops.

A call to sqlite3_shutdown() is an "effective" call if it is the first call to sqlite3_shutdown() since the last sqlite3_initialize(). Only an effective call to sqlite3_shutdown() does any deinitialization. All other valid calls to sqlite3_shutdown() are harmless no-ops.

The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() is not. The sqlite3_shutdown() interface must only be called from a single thread. All open database connections must be closed and all other SQLite resources must be deallocated prior to invoking sqlite3_shutdown().

Among other things, sqlite3_initialize() will invoke
sqlite3_os_init().  Similarly, sqlite3_shutdown()
will invoke sqlite3_os_end().

The sqlite3_initialize() routine returns SQLITE_OK on success. If for some reason, sqlite3_initialize() is unable to initialize the library (perhaps it is unable to allocate a needed resource such as a mutex) it returns an error code other than SQLITE_OK.

The sqlite3_initialize() routine is called internally by many other SQLite interfaces so that an application usually does not need to invoke sqlite3_initialize() directly. For example, sqlite3_open() calls sqlite3_initialize() so the SQLite library will be automatically initialized when sqlite3_open() is called if it has not be initialized already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT compile-time option, then the automatic calls to sqlite3_initialize() are omitted and the application must call sqlite3_initialize() directly prior to using any other SQLite interface. For maximum portability, it is recommended that applications always invoke sqlite3_initialize() directly prior to using any other SQLite interface. Future releases of SQLite may require this. In other words, the behavior exhibited when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the default behavior in some future release of SQLite.

The sqlite3_os_init() routine does operating-system specific initialization of the SQLite library. The sqlite3_os_end() routine undoes the effect of sqlite3_os_init(). Typical tasks performed by these routines include allocation or deallocation of static resources, initialization of global variables, setting up a default sqlite3_vfs module, or setting up a default configuration using sqlite3_config().

The application should never invoke either sqlite3_os_init() or sqlite3_os_end() directly. The application should only invoke sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() interface is called automatically by sqlite3_initialize() and sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate implementations for sqlite3_os_init() and sqlite3_os_end() are built into SQLite when it is compiled for Unix, Windows, or OS/2. When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time option) the application must supply a suitable implementation for sqlite3_os_init() and sqlite3_os_end(). An application-supplied implementation of sqlite3_os_init() or sqlite3_os_end() must return SQLITE_OK on success and some other error code upon failure.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

64-Bit Integer Types

#ifdef SQLITE_INT64_TYPE
  typedef SQLITE_INT64_TYPE sqlite_int64;
  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
#elif defined(_MSC_VER) || defined(__BORLANDC__)
  typedef __int64 sqlite_int64;
  typedef unsigned __int64 sqlite_uint64;
#else
  typedef long long int sqlite_int64;
  typedef unsigned long long int sqlite_uint64;
#endif
typedef sqlite_int64 sqlite3_int64;
typedef sqlite_uint64 sqlite3_uint64;

Because there is no cross-platform way to specify 64-bit integer types SQLite includes typedefs for 64-bit signed and unsigned integers.

The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. The sqlite_int64 and sqlite_uint64 types are supported for backwards compatibility only.

The sqlite3_int64 and sqlite_int64 types can store integer values between -9223372036854775808 and +9223372036854775807 inclusive. The sqlite3_uint64 and sqlite_uint64 types can store integer values between 0 and +18446744073709551615 inclusive.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Interrupt A Long-Running Query

void sqlite3_interrupt(sqlite3*);

This function causes any pending database operation to abort and return at its earliest opportunity. This routine is typically called in response to a user action such as pressing "Cancel" or Ctrl-C where the user wants a long query operation to halt immediately.

It is safe to call this routine from a thread different from the thread that is currently running the database operation. But it is not safe to call this routine with a database connection that is closed or might close before sqlite3_interrupt() returns.

If an SQL operation is very nearly finished at the time when sqlite3_interrupt() is called, then it might not have an opportunity to be interrupted and might continue to completion.

An SQL operation that is interrupted will return SQLITE_INTERRUPT. If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that is inside an explicit transaction, then the entire transaction will be rolled back automatically.

The sqlite3_interrupt(D) call is in effect until all currently running SQL statements on database connection D complete. Any new SQL statements that are started after the sqlite3_interrupt() call and before the running statements reaches zero are interrupted as if they had been running prior to the sqlite3_interrupt() call. New SQL statements that are started after the running statement count reaches zero are not effected by the sqlite3_interrupt(). A call to sqlite3_interrupt(D) that occurs when there are no running SQL statements is a no-op and has no effect on SQL statements that are started after the sqlite3_interrupt() call returns.

If the database connection closes while sqlite3_interrupt() is running then bad things will likely happen.

See also lists of Objects, Constants, and Functions.


Introduction

Choose any three.
About Sitemap Documentation Download License News Support

These pages define the C-language interface to SQLite.

This is not a tutorial. These pages are designed to be precise, not easy to read. For a tutorial introduction see SQLite In 3 Minutes Or Less and/or the Introduction To The SQLite C/C++ Interface.

This version of the C-language interface reference is broken down into small pages for easy viewing. The same content is also available as a single large HTML file for those who prefer that format.

The content on these pages is extracted from comments in the source code.

The interface is broken down into three categories:

  1. List Of Objects. This is a list of all abstract objects and datatypes used by the SQLite library. There are couple dozen objects in total, but the three most important objects are: A database connection object sqlite3, prepared statement object sqlite3_stmt, and the 64-bit integer type sqlite3_int64.

  2. List Of Constants. This is a list of numeric constants used by SQLite and represented by #defines in the sqlite3.h header file. These constants are things such as numeric return parameters from various interfaces (ex: SQLITE_OK or flags passed into functions to control behavior (ex: SQLITE_OPEN_READONLY).

  3. List Of Functions. This is a list of all functions and methods operating on the objects and using and/or returning constants. There are many functions, but most applications only use a handful.


SQLite Logo
Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

OS Interface File Virtual Methods Object

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* Methods above are valid for version 2 */
  /* Additional methods may be added in future releases */
};

Every file opened by the sqlite3_vfs.xOpen method populates an sqlite3_file object (or, more commonly, a subclass of the sqlite3_file object) with a pointer to an instance of this object. This object defines the methods used to perform various operations against the open file represented by the sqlite3_file object.

If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods element to a non-NULL pointer, then the sqlite3_io_methods.xClose method may be invoked even if the sqlite3_vfs.xOpen reported that it failed. The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods element to NULL.

The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or SQLITE_SYNC_FULL. The first choice is the normal fsync(). The second choice is a Mac OS X style fullsync. The SQLITE_SYNC_DATAONLY flag may be ORed in to indicate that only the data of the file and not its inode needs to be synced.

The integer values to xLock() and xUnlock() are one of

  • SQLITE_LOCK_NONE,
  • SQLITE_LOCK_SHARED,
  • SQLITE_LOCK_RESERVED,
  • SQLITE_LOCK_PENDING, or
  • SQLITE_LOCK_EXCLUSIVE.
xLock() increases the lock. xUnlock() decreases the lock. The xCheckReservedLock() method checks whether any database connection, either in this process or in some other process, is holding a RESERVED, PENDING, or EXCLUSIVE lock on the file. It returns true if such a lock exists and false otherwise.

The xFileControl() method is a generic interface that allows custom VFS implementations to directly control an open file using the sqlite3_file_control() interface. The second "op" argument is an integer opcode. The third argument is a generic pointer intended to point to a structure that may contain arguments or space in which to write return values. Potential uses for xFileControl() might be functions to enable blocking locks with timeouts, to change the locking strategy (for example to use dot-file locks), to inquire about the status of a lock, or to break stale locks. The SQLite core reserves all opcodes less than 100 for its own use. A list of opcodes less than 100 is available. Applications that define a custom xFileControl method should use opcodes greater than 100 to avoid conflicts. VFS implementations should return SQLITE_NOTFOUND for file control opcodes that they do not recognize.

The xSectorSize() method returns the sector size of the device that underlies the file. The sector size is the minimum write that can be performed without disturbing other bytes in the file. The xDeviceCharacteristics() method returns a bit vector describing behaviors of the underlying device:

  • SQLITE_IOCAP_ATOMIC
  • SQLITE_IOCAP_ATOMIC512
  • SQLITE_IOCAP_ATOMIC1K
  • SQLITE_IOCAP_ATOMIC2K
  • SQLITE_IOCAP_ATOMIC4K
  • SQLITE_IOCAP_ATOMIC8K
  • SQLITE_IOCAP_ATOMIC16K
  • SQLITE_IOCAP_ATOMIC32K
  • SQLITE_IOCAP_ATOMIC64K
  • SQLITE_IOCAP_SAFE_APPEND
  • SQLITE_IOCAP_SEQUENTIAL

The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQLITE_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite().

If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the unread portions of the buffer with zeros. A VFS that fails to zero-fill short reads might seem to work. However, failure to zero-fill short reads will eventually lead to database corruption.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Last Insert Rowid

sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);

Each entry in an SQLite table has a unique 64-bit signed integer key called the "rowid". The rowid is always available as an undeclared column named ROWID, OID, or _ROWID_ as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.

This routine returns the rowid of the most recent successful INSERT into the database from the database connection in the first argument. As of SQLite version 3.7.7, this routines records the last insert rowid of both ordinary tables and virtual tables. If no successful INSERTs have ever occurred on that database connection, zero is returned.

If an INSERT occurs within a trigger or within a virtual table method, then this routine will return the rowid of the inserted row as long as the trigger or virtual table method is running. But once the trigger or virtual table method ends, the value returned by this routine reverts to what it was before the trigger or virtual table method began.

An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.

For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.

This function is accessible to SQL statements via the last_insert_rowid() SQL function.

If a separate thread performs a new INSERT on the same database connection while the sqlite3_last_insert_rowid() function is running and thus changes the last insert rowid, then the value returned by sqlite3_last_insert_rowid() is unpredictable and might not equal either the old or the new last insert rowid.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Run-Time Library Version Numbers

SQLITE_EXTERN const char sqlite3_version[];
const char *sqlite3_libversion(void);
const char *sqlite3_sourceid(void);
int sqlite3_libversion_number(void);

These interfaces provide the same information as the SQLITE_VERSION, SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros but are associated with the library instead of the header file. Cautious programmers might include assert() statements in their application to verify that values returned by these interfaces match the macros in the header, and thus insure that the application is compiled with matching library and header files.

assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

The sqlite3_version[] string constant contains the text of SQLITE_VERSION macro. The sqlite3_libversion() function returns a pointer to the to the sqlite3_version[] string constant. The sqlite3_libversion() function is provided for use in DLLs since DLL users usually do not have direct access to string constants within the DLL. The sqlite3_libversion_number() function returns an integer equal to SQLITE_VERSION_NUMBER. The sqlite3_sourceid() function returns a pointer to a string constant whose value is the same as the SQLITE_SOURCE_ID C preprocessor macro.

See also: sqlite_version() and sqlite_source_id().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Run-time Limits

int sqlite3_limit(sqlite3*, int id, int newVal);

This interface allows the size of various constructs to be limited on a connection by connection basis. The first parameter is the database connection whose limit is to be set or queried. The second parameter is one of the limit categories that define a class of constructs to be size limited. The third parameter is the new limit for that construct.

If the new limit is a negative number, the limit is unchanged. For each limit category SQLITE_LIMIT_NAME there is a hard upper bound set at compile-time by a C preprocessor macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to "_MAX_".) Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound.

Regardless of whether or not the limit was changed, the sqlite3_limit() interface returns the prior value of the limit. Hence, to find the current value of a limit without changing it, simply invoke this interface with the third parameter set to -1.

Run-time limits are intended for use in applications that manage both their own internal database and also databases that are controlled by untrusted external sources. An example application might be a web browser that has its own databases for storing history and separate databases controlled by JavaScript applications downloaded off the Internet. The internal databases can be given the large, default limits. Databases managed by external sources can be given much smaller limits designed to prevent a denial of service attack. Developers might also want to use the sqlite3_set_authorizer() interface to further control untrusted SQL. The size of the database created by an untrusted script can be contained using the max_page_count PRAGMA.

New run-time limit categories may be added in future releases.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Load An Extension

int sqlite3_load_extension(
  sqlite3 *db,          /* Load the extension into this database connection */
  const char *zFile,    /* Name of the shared library containing extension */
  const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  char **pzErrMsg       /* Put error message here if not 0 */
);

This interface loads an SQLite extension library from the named file.

The sqlite3_load_extension() interface attempts to load an SQLite extension library contained in the file zFile.

The entry point is zProc. zProc may be 0, in which case the name of the entry point defaults to "sqlite3_extension_init". The sqlite3_load_extension() interface returns SQLITE_OK on success and SQLITE_ERROR if something goes wrong. If an error occurs and pzErrMsg is not 0, then the sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with error message text stored in memory obtained from sqlite3_malloc(). The calling function should free this memory by calling sqlite3_free().

Extension loading must be enabled using sqlite3_enable_load_extension() prior to calling this API, otherwise an error will be returned.

See also the load_extension() SQL function.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Error Logging Interface

void sqlite3_log(int iErrCode, const char *zFormat, ...);

The sqlite3_log() interface writes a message into the error log established by the SQLITE_CONFIG_LOG option to sqlite3_config(). If logging is enabled, the zFormat string and subsequent arguments are used with sqlite3_snprintf() to generate the final output string.

The sqlite3_log() interface is intended for use by extensions such as virtual tables, collating functions, and SQL functions. While there is nothing to prevent an application from calling sqlite3_log(), doing so is considered bad form.

The zFormat string must not be NULL.

To avoid deadlocks and other threading problems, the sqlite3_log() routine will not use dynamically allocated memory. The log message is stored in a fixed-length buffer on the stack. If the log message is longer than a few hundred characters, it will be truncated to the length of the buffer.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Memory Allocation Routines

typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int);         /* Memory allocation function */
  void (*xFree)(void*);          /* Free a prior allocation */
  void *(*xRealloc)(void*,int);  /* Resize an allocation */
  int (*xSize)(void*);           /* Return the size of an allocation */
  int (*xRoundup)(int);          /* Round up request size to allocation size */
  int (*xInit)(void*);           /* Initialize the memory allocator */
  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  void *pAppData;                /* Argument to xInit() and xShutdown() */
};

An instance of this object defines the interface between SQLite and low-level memory allocation routines.

This object is used in only one place in the SQLite interface. A pointer to an instance of this object is the argument to sqlite3_config() when the configuration option is SQLITE_CONFIG_MALLOC or SQLITE_CONFIG_GETMALLOC. By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC) during configuration, an application can specify an alternative memory allocation subsystem for SQLite to use for all of its dynamic memory needs.

Note that SQLite comes with several built-in memory allocators that are perfectly adequate for the overwhelming majority of applications and that this object is only useful to a tiny minority of applications with specialized memory allocation requirements. This object is also used during testing of SQLite in order to specify an alternative memory allocator that simulates memory out-of-memory conditions in order to verify that SQLite recovers gracefully from such conditions.

The xMalloc, xRealloc, and xFree methods must work like the malloc(), realloc() and free() functions from the standard C library. SQLite guarantees that the second argument to xRealloc is always a value returned by a prior call to xRoundup.

xSize should return the allocated size of a memory allocation previously obtained from xMalloc or xRealloc. The allocated size is always at least as big as the requested size but may be larger.

The xRoundup method returns what would be the allocated size of a memory allocation given a particular requested size. Most memory allocators round up memory allocations at least to the next multiple of 8. Some allocators round up to a larger multiple or to a power of 2. Every memory allocation request coming in through sqlite3_malloc() or sqlite3_realloc() first calls xRoundup. If xRoundup returns 0, that causes the corresponding memory allocation to fail.

The xInit method initializes the memory allocator. (For example, it might allocate any require mutexes or initialize internal data structures. The xShutdown method is invoked (indirectly) by sqlite3_shutdown() and should deallocate any resources acquired by xInit. The pAppData pointer is used as the only parameter to xInit and xShutdown.

SQLite holds the SQLITE_MUTEX_STATIC_MASTER mutex when it invokes the xInit method, so the xInit method need not be threadsafe. The xShutdown method is only called from sqlite3_shutdown() so it does not need to be threadsafe either. For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM mutex as long as the SQLITE_CONFIG_MEMSTATUS configuration option is turned on (which it is by default) and so the methods are automatically serialized. However, if SQLITE_CONFIG_MEMSTATUS is disabled, then the other methods must be threadsafe or else make their own arrangements for serialization.

SQLite will never invoke xInit() more than once without an intervening call to xShutdown().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Memory Allocator Statistics

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

SQLite provides these two interfaces for reporting on the status of the sqlite3_malloc(), sqlite3_free(), and sqlite3_realloc() routines, which form the built-in memory allocation subsystem.

The sqlite3_memory_used() routine returns the number of bytes of memory currently outstanding (malloced but not freed). The sqlite3_memory_highwater() routine returns the maximum value of sqlite3_memory_used() since the high-water mark was last reset. The values returned by sqlite3_memory_used() and sqlite3_memory_highwater() include any overhead added by SQLite in its implementation of sqlite3_malloc(), but not overhead added by the any underlying system library routines that sqlite3_malloc() may call.

The memory high-water mark is reset to the current value of sqlite3_memory_used() if and only if the parameter to sqlite3_memory_highwater() is true. The value returned by sqlite3_memory_highwater(1) is the high-water mark prior to the reset.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Object

struct sqlite3_module {
  int iVersion;
  int (*xCreate)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  int (*xDisconnect)(sqlite3_vtab *pVTab);
  int (*xDestroy)(sqlite3_vtab *pVTab);
  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  int (*xClose)(sqlite3_vtab_cursor*);
  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                int argc, sqlite3_value **argv);
  int (*xNext)(sqlite3_vtab_cursor*);
  int (*xEof)(sqlite3_vtab_cursor*);
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  int (*xBegin)(sqlite3_vtab *pVTab);
  int (*xSync)(sqlite3_vtab *pVTab);
  int (*xCommit)(sqlite3_vtab *pVTab);
  int (*xRollback)(sqlite3_vtab *pVTab);
  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
                       void **ppArg);
  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  /* The methods above are in version 1 of the sqlite_module object. Those
  ** below are for version 2 and greater. */
  int (*xSavepoint)(sqlite3_vtab *pVTab, int);
  int (*xRelease)(sqlite3_vtab *pVTab, int);
  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
};

This structure, sometimes called a "virtual table module", defines the implementation of a virtual tables. This structure consists mostly of methods for the module.

A virtual table module is created by filling in a persistent instance of this structure and passing a pointer to that instance to sqlite3_create_module() or sqlite3_create_module_v2(). The registration remains valid until it is replaced by a different module or until the database connection closes. The content of this structure must not change while it is registered with any database connection.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Formatted String Printing Functions

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);

These routines are work-alikes of the "printf()" family of functions from the standard C library.

The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results into memory obtained from sqlite3_malloc(). The strings returned by these two routines should be released by sqlite3_free(). Both routines return a NULL pointer if sqlite3_malloc() is unable to allocate enough memory to hold the resulting string.

The sqlite3_snprintf() routine is similar to "snprintf()" from the standard C library. The result is written into the buffer supplied as the second parameter whose size is given by the first parameter. Note that the order of the first two parameters is reversed from snprintf(). This is an historical accident that cannot be fixed without breaking backwards compatibility. Note also that sqlite3_snprintf() returns a pointer to its buffer instead of the number of characters actually written into the buffer. We admit that the number of characters written would be a more useful return value but we cannot change the implementation of sqlite3_snprintf() now without breaking compatibility.

As long as the buffer size is greater than zero, sqlite3_snprintf() guarantees that the buffer is always zero-terminated. The first parameter "n" is the total size of the buffer, including space for the zero terminator. So the longest string that can be completely written will be n-1 characters.

The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().

These routines all implement some additional formatting options that are useful for constructing SQL statements. All of the usual printf() formatting options apply. In addition, there is are "%q", "%Q", and "%z" options.

The %q option works like %s in that it substitutes a null-terminated string from the argument list. But %q also doubles every '\'' character. %q is designed for use inside a string literal. By doubling each '\'' character it escapes that character and allows it to be inserted into the string.

For example, assume the string variable zText contains text as follows:

char *zText = "It's a happy day!";

One can use this text in an SQL statement as follows:

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);

Because the %q format string is used, the '\'' character in zText is escaped and the SQL generated is as follows:

INSERT INTO table1 VALUES('It''s a happy day!')

This is correct. Had we used %s instead of %q, the generated SQL would have looked like this:

INSERT INTO table1 VALUES('It's a happy day!');

This second example is an SQL syntax error. As a general rule you should always use %q instead of %s when inserting text into a string literal.

The %Q option works like %q except it also adds single quotes around the outside of the total string. Additionally, if the parameter in the argument list is a NULL pointer, %Q substitutes the text "NULL" (without single quotes). So, for example, one could say:

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);

The code above will render a correct SQL statement in the zSQL variable even if the zText variable is a NULL pointer.

The "%z" formatting option works like "%s" but with the addition that after the string has been read and copied into the result, sqlite3_free() is called on the input string.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Mutex Handle

typedef struct sqlite3_mutex sqlite3_mutex;

The mutex module within SQLite defines sqlite3_mutex to be an abstract type for a mutex object. The SQLite core never looks at the internal representation of an sqlite3_mutex. It only deals with pointers to the sqlite3_mutex object.

Mutexes are created using sqlite3_mutex_alloc().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Mutexes

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);

The SQLite core uses these routines for thread synchronization. Though they are intended for internal use by SQLite, code that links against SQLite is permitted to use any of these routines.

The SQLite source code contains multiple implementations of these mutex routines. An appropriate implementation is selected automatically at compile-time. The following implementations are available in the SQLite core:

  • SQLITE_MUTEX_OS2
  • SQLITE_MUTEX_PTHREAD
  • SQLITE_MUTEX_W32
  • SQLITE_MUTEX_NOOP

The SQLITE_MUTEX_NOOP implementation is a set of routines that does no real locking and is appropriate for use in a single-threaded application. The SQLITE_MUTEX_OS2, SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations are appropriate for use on OS/2, Unix, and Windows.

If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex implementation is included with the library. In this case the application must supply a custom mutex implementation using the SQLITE_CONFIG_MUTEX option of the sqlite3_config() function before calling sqlite3_initialize() or any other public sqlite3_ function that calls sqlite3_initialize().

The sqlite3_mutex_alloc() routine allocates a new mutex and returns a pointer to it. If it returns NULL that means that a mutex could not be allocated. SQLite will unwind its stack and return an error. The argument to sqlite3_mutex_alloc() is one of these integer constants:

  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_MUTEX_STATIC_LRU
  • SQLITE_MUTEX_STATIC_LRU2

The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) cause sqlite3_mutex_alloc() to create a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but not necessarily so when SQLITE_MUTEX_FAST is used. The mutex implementation does not need to make a distinction between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. SQLite will only request a recursive mutex in cases where it really needs one. If a faster non-recursive mutex implementation is available on the host platform, the mutex subsystem might return such a mutex in response to SQLITE_MUTEX_FAST.

The other allowed parameters to sqlite3_mutex_alloc() (anything other than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer to a static preexisting mutex. Six static mutexes are used by the current version of SQLite. Future versions of SQLite may add additional static mutexes. Static mutexes are for internal use by SQLite only. Applications that use SQLite mutexes should use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE.

Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns a different mutex on every call. But for the static mutex types, the same mutex is returned on every call that has the same type number.

The sqlite3_mutex_free() routine deallocates a previously allocated dynamic mutex. SQLite is careful to deallocate every dynamic mutex that it allocates. The dynamic mutexes must not be in use when they are deallocated. Attempting to deallocate a static mutex results in undefined behavior. SQLite never deallocates a static mutex.

The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt to enter a mutex. If another thread is already within the mutex, sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. In such cases the, mutex must be exited an equal number of times before another thread can enter. If the same thread tries to enter any other kind of mutex more than once, the behavior is undefined. SQLite will never exhibit such behavior in its own use of mutexes.

Some systems (for example, Windows 95) do not support the operation implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. The SQLite core only ever uses sqlite3_mutex_try() as an optimization so this is acceptable behavior.

The sqlite3_mutex_leave() routine exits a mutex that was previously entered by the same thread. The behavior is undefined if the mutex is not currently entered by the calling thread or is not currently allocated. SQLite will never do either.

If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or sqlite3_mutex_leave() is a NULL pointer, then all three routines behave as no-ops.

See also: sqlite3_mutex_held() and sqlite3_mutex_notheld().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Mutex Verification Routines

#ifndef NDEBUG
int sqlite3_mutex_held(sqlite3_mutex*);
int sqlite3_mutex_notheld(sqlite3_mutex*);
#endif

The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended for use inside assert() statements. The SQLite core never uses these routines except inside an assert() and applications are advised to follow the lead of the core. The SQLite core only provides implementations for these routines when it is compiled with the SQLITE_DEBUG flag. External mutex implementations are only required to provide these routines if SQLITE_DEBUG is defined and if NDEBUG is not defined.

These routines should return true if the mutex in their argument is held or not held, respectively, by the calling thread.

The implementation is not required to provided versions of these routines that actually work. If the implementation does not provide working versions of these routines, it should at least provide stubs that always return true so that one does not get spurious assertion failures.

If the argument to sqlite3_mutex_held() is a NULL pointer then the routine should return 1. This seems counter-intuitive since clearly the mutex cannot be held if it does not exist. But the reason the mutex does not exist is because the build is not using mutexes. And we do not want the assert() containing the call to sqlite3_mutex_held() to fail, so a non-zero return is the appropriate thing to do. The sqlite3_mutex_notheld() interface should also return 1 when given a NULL pointer.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Mutex Methods Object

typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
struct sqlite3_mutex_methods {
  int (*xMutexInit)(void);
  int (*xMutexEnd)(void);
  sqlite3_mutex *(*xMutexAlloc)(int);
  void (*xMutexFree)(sqlite3_mutex *);
  void (*xMutexEnter)(sqlite3_mutex *);
  int (*xMutexTry)(sqlite3_mutex *);
  void (*xMutexLeave)(sqlite3_mutex *);
  int (*xMutexHeld)(sqlite3_mutex *);
  int (*xMutexNotheld)(sqlite3_mutex *);
};

An instance of this structure defines the low-level routines used to allocate and use mutexes.

Usually, the default mutex implementations provided by SQLite are sufficient, however the user has the option of substituting a custom implementation for specialized deployments or systems for which SQLite does not provide a suitable implementation. In this case, the user creates and populates an instance of this structure to pass to sqlite3_config() along with the SQLITE_CONFIG_MUTEX option. Additionally, an instance of this structure can be used as an output variable when querying the system for the current mutex implementation, using the SQLITE_CONFIG_GETMUTEX option.

The xMutexInit method defined by this structure is invoked as part of system initialization by the sqlite3_initialize() function. The xMutexInit routine is called by SQLite exactly once for each effective call to sqlite3_initialize().

The xMutexEnd method defined by this structure is invoked as part of system shutdown by the sqlite3_shutdown() function. The implementation of this method is expected to release all outstanding resources obtained by the mutex methods implementation, especially those obtained by the xMutexInit method. The xMutexEnd() interface is invoked exactly once for each call to sqlite3_shutdown().

The remaining seven methods defined by this structure (xMutexAlloc, xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and xMutexNotheld) implement the following interfaces (respectively):

  • sqlite3_mutex_alloc()
  • sqlite3_mutex_free()
  • sqlite3_mutex_enter()
  • sqlite3_mutex_try()
  • sqlite3_mutex_leave()
  • sqlite3_mutex_held()
  • sqlite3_mutex_notheld()

The only difference is that the public sqlite3_XXX functions enumerated above silently ignore any invocations that pass a NULL pointer instead of a valid mutex handle. The implementations of the methods defined by this structure are not required to handle this case, the results of passing a NULL pointer instead of a valid mutex handle are undefined (i.e. it is acceptable to provide an implementation that segfaults if it is passed a NULL pointer).

The xMutexInit() method must be threadsafe. It must be harmless to invoke xMutexInit() multiple times within the same process and without intervening calls to xMutexEnd(). Second and subsequent calls to xMutexInit() must be no-ops.

xMutexInit() must not use SQLite memory allocation (sqlite3_malloc() and its associates). Similarly, xMutexAlloc() must not use SQLite memory allocation for a static mutex. However xMutexAlloc() may use SQLite memory allocation for a fast or recursive mutex.

SQLite will invoke the xMutexEnd() method when sqlite3_shutdown() is called, but only if the prior call to xMutexInit returned SQLITE_OK. If xMutexInit fails in any way, it is expected to clean up after itself prior to returning.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Find the next prepared statement

sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);

This interface returns a pointer to the next prepared statement after pStmt associated with the database connection pDb. If pStmt is NULL then this interface returns a pointer to the first prepared statement associated with the database connection pDb. If no prepared statement satisfies the conditions of this routine, it returns NULL.

The database connection pointer D in a call to sqlite3_next_stmt(D,S) must refer to an open database connection and in particular must not be a NULL pointer.

See also lists of Objects, Constants, and Functions.


List Of SQLite Objects

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Objects:

Note: Objects marked with "exp" are experimental and objects marked with "(obs)" are deprecated.

  • sqlite3
  • sqlite3_backup
  • sqlite3_blob
  • sqlite3_context
  • sqlite3_file
  • sqlite3_index_info
  • sqlite3_int64
  • sqlite3_uint64
  • sqlite_int64
  • sqlite_uint64
  • sqlite3_io_methods
  • sqlite3_mem_methods
  • sqlite3_module
  • sqlite3_mutex
  • sqlite3_mutex_methods
  • sqlite3_pcache
  • sqlite3_pcache_methods
  • sqlite3_stmt
  • sqlite3_temp_directory
  • sqlite3_value
  • sqlite3_vfs
  • sqlite3_vtab
  • sqlite3_vtab_cursor

Other lists: Constants and Functions.


Choose any three.

SQLite C Interface

Opening A New Database Connection

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the sqlite3 object, a NULL will be written into *ppDb instead of a pointer to the sqlite3 object. If the database is opened (and/or created) successfully, then SQLITE_OK is returned. Otherwise an error code is returned. The sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.

The default encoding for the database will be UTF-8 if sqlite3_open() or sqlite3_open_v2() is called and UTF-16 in the native byte order if sqlite3_open16() is used.

Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close() when it is no longer required.

The sqlite3_open_v2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to sqlite3_open_v2() can take one of the following three values, optionally combined with the SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, SQLITE_OPEN_PRIVATECACHE, and/or SQLITE_OPEN_URI flags:

SQLITE_OPEN_READONLY
The database is opened in read-only mode. If the database does not already exist, an error is returned.

SQLITE_OPEN_READWRITE
The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
The database is opened for reading and writing, and is created if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().

If the 3rd parameter to sqlite3_open_v2() is not one of the combinations shown above optionally combined with other SQLITE_OPEN_* bits then the behavior is undefined.

If the SQLITE_OPEN_NOMUTEX flag is set, then the database connection opens in the multi-thread threading mode as long as the single-thread mode has not been set at compile-time or start-time. If the SQLITE_OPEN_FULLMUTEX flag is set then the database connection opens in the serialized threading mode unless single-thread was previously selected at compile-time or start-time. The SQLITE_OPEN_SHAREDCACHE flag causes the database connection to be eligible to use shared cache mode, regardless of whether or not shared cache is enabled using sqlite3_enable_shared_cache(). The SQLITE_OPEN_PRIVATECACHE flag causes the database connection to not participate in shared cache mode even if it is enabled.

The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.

If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

URI Filenames

If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQLITE_OPEN_URI flag is set in the fourth argument to sqlite3_open_v2(), or if it has been enabled globally using the SQLITE_CONFIG_URI option with the sqlite3_config() method or by the SQLITE_USE_URI compile-time option. As of SQLite version 3.7.7, URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "URI filenames" for additional information.

URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.

SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").

The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite interprets the following three query parameters:

  • vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If sqlite3_open_v2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to sqlite3_open_v2().

  • mode: The mode parameter may be set to either "ro", "rw" or "rwc". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQLITE_OPEN_READONLY flag had been set in the third argument to sqlite3_prepare_v2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If sqlite3_open_v2() is used, it is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed as the third parameter.

  • cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to sqlite3_open_v2(). Setting the cache parameter to "private" is equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. If sqlite3_open_v2() is used and the "cache" parameter is present in a URI filename, its value overrides any behaviour requested by setting SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.

Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "query parameters with special meaning to SQLite" for additional information.

URI filename examples

URI filenames | Results
file:data.db | Open the file "data.db" in the current directory.
file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db".
file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames.
file:data.db?mode=ro&cache=private | Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache.
file:/home/fred/data.db?vfs=unix-nolock | Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter.

URI hexadecimal escape sequences (%HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.

Note to Windows users: The encoding used for the filename argument of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Overload A Function For A Virtual Table

int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);

Virtual tables can provide alternative implementations of functions using the xFindFunction method of the virtual table module. But global versions of those functions must exist in order to be overloaded.

This API makes sure a global version of a function with a particular name and number of parameters exists. If no such function exists before this API is called, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself. Its only purpose is to be a placeholder function that can be overloaded by a virtual table.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Custom Page Cache Object

typedef struct sqlite3_pcache sqlite3_pcache;

The sqlite3_pcache type is opaque. It is implemented by the pluggable module. The SQLite core has no knowledge of its size or internal structure and never deals with the sqlite3_pcache object except by holding and passing pointers to the object.

See sqlite3_pcache_methods for additional information.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Application Defined Page Cache.

typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
struct sqlite3_pcache_methods {
  void *pArg;
  int (*xInit)(void*);
  void (*xShutdown)(void*);
  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  int (*xPagecount)(sqlite3_pcache*);
  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  void (*xDestroy)(sqlite3_pcache*);
};

The sqlite3_config(SQLITE_CONFIG_PCACHE, ...) interface can register an alternative page cache implementation by passing in an instance of the sqlite3_pcache_methods structure. In many applications, most of the heap memory allocated by SQLite is used for the page cache. By implementing a custom page cache using this API, an application can better control the amount of memory consumed by SQLite, the way in which that memory is allocated and released, and the policies used to determine exactly which parts of a database file are cached and for how long.

The alternative page cache mechanism is an extreme measure that is only needed by the most demanding applications. The built-in page cache is recommended for most uses.

The contents of the sqlite3_pcache_methods structure are copied to an internal buffer by SQLite within the call to sqlite3_config. Hence the application may discard the parameter after the call to sqlite3_config() returns.

The xInit() method is called once for each effective call to sqlite3_initialize() (usually only once during the lifetime of the process). The xInit() method is passed a copy of the sqlite3_pcache_methods.pArg value. The intent of the xInit() method is to set up global data structures required by the custom page cache implementation. If the xInit() method is NULL, then the built-in default page cache is used instead of the application defined page cache.

The xShutdown() method is called by sqlite3_shutdown(). It can be used to clean up any outstanding resources before process shutdown, if required. The xShutdown() method may be NULL.

SQLite automatically serializes calls to the xInit method, so the xInit method need not be threadsafe. The xShutdown method is only called from sqlite3_shutdown() so it does not need to be threadsafe either. All other methods must be threadsafe in multithreaded applications.

SQLite will never invoke xInit() more than once without an intervening call to xShutdown().

SQLite invokes the xCreate() method to construct a new cache instance. SQLite will typically create one cache instance for each open database file, though this is not guaranteed. The first parameter, szPage, is the size in bytes of the pages that must be allocated by the cache. szPage will not be a power of two. szPage will the page size of the database file that is to be cached plus an increment (here called "R") of less than 250. SQLite will use the extra R bytes on each page to store metadata about the underlying database page on disk. The value of R depends on the SQLite version, the target platform, and how SQLite was compiled. R is constant for a particular build of SQLite. Except, there are two distinct values of R when SQLite is compiled with the proprietary ZIPVFS extension. The second argument to xCreate(), bPurgeable, is true if the cache being created will be used to cache database pages of a file stored on disk, or false if it is used for an in-memory database. The cache implementation does not have to do anything special based with the value of bPurgeable; it is purely advisory. On a cache where bPurgeable is false, SQLite will never invoke xUnpin() except to deliberately delete a page. In other words, calls to xUnpin() on a cache with bPurgeable set to false will always have the "discard" flag set to true. Hence, a cache created with bPurgeable false will never contain any unpinned pages.

The xCachesize() method may be called at any time by SQLite to set the suggested maximum cache-size (number of pages stored by) the cache instance passed as the first argument. This is the value configured using the SQLite "PRAGMA cache_size" command. As with the bPurgeable parameter, the implementation is not required to do anything with this value; it is advisory only.

The xPagecount() method must return the number of pages currently stored in the cache, both pinned and unpinned.

The xFetch() method locates a page in the cache and returns a pointer to the page, or a NULL pointer. A "page", in this context, means a buffer of szPage bytes aligned at an 8-byte boundary. The page to be fetched is determined by the key. The minimum key value is 1. After it has been retrieved using xFetch, the page is considered to be "pinned".

If the requested page is already in the page cache, then the page cache implementation must return a pointer to the page buffer with its content intact. If the requested page is not already in the cache, then the cache implementation should use the value of the createFlag parameter to help it determined what action to take:

createFlag | Behaviour when page is not already in cache
0 | Do not allocate a new page. Return NULL.
1 | Allocate a new page if it easy and convenient to do so. Otherwise return NULL.
2 | Make every effort to allocate a new page. Only return NULL if allocating a new page is effectively impossible.

SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite will only use a createFlag of 2 after a prior call with a createFlag of 1 failed. In between the to xFetch() calls, SQLite may attempt to unpin one or more cache pages by spilling the content of pinned pages to disk and synching the operating system disk cache.

xUnpin() is called by SQLite with a pointer to a currently pinned page as its second argument. If the third parameter, discard, is non-zero, then the page must be evicted from the cache. If the discard parameter is zero, then the page may be discarded or retained at the discretion of page cache implementation. The page cache implementation may choose to evict unpinned pages at any time.

The cache must not perform any reference counting. A single call to xUnpin() unpins the page regardless of the number of prior calls to xFetch().

The xRekey() method is used to change the key value associated with the page passed as the second argument. If the cache previously contains an entry associated with newKey, it must be discarded. Any prior cache entry associated with newKey is guaranteed not to be pinned.

When SQLite calls the xTruncate() method, the cache must discard all existing cache entries with page numbers (keys) greater than or equal to the value of the iLimit parameter passed to xTruncate(). If any of these pages are pinned, they are implicitly unpinned, meaning that they can be safely discarded.

The xDestroy() method is used to delete a cache allocated by xCreate(). All resources associated with the specified cache should be freed. After calling the xDestroy() method, SQLite considers the sqlite3_pcache* handle invalid, and will not use it with any other sqlite3_pcache_methods functions.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Compiling An SQL Statement

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open(), sqlite3_open_v2() or sqlite3_open16(). The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() use UTF-16.

If the nByte argument is less than zero, then zSql is read up to the first zero terminator. If nByte is non-negative, then it is the maximum number of bytes read from zSql. When nByte is non-negative, the zSql string ends at either the first '\000' or '\u0000' character or the nByte-th byte, whichever comes first. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to be gained by passing an nByte parameter that is equal to the number of bytes in the input string including the nul-terminator bytes as this saves SQLite from having to make a copy of the input string.

If pzTail is not NULL then *pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compile the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.

*ppStmt is left pointing to a compiled prepared statement that can be executed using sqlite3_step(). If there is an error, *ppStmt is set to NULL. If the input text contains no SQL (if the input is an empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting the compiled SQL statement using sqlite3_finalize() after it has finished with it. ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQLITE_OK; otherwise an error code is returned.

The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are recommended for all new programs. The two older interfaces are retained for backwards compatibility, but their use is discouraged. In the "v2" interfaces, the prepared statement that is returned (the sqlite3_stmt object) contains a copy of the original SQL text. This causes the sqlite3_step() interface to behave differently in three ways:

  1. If the database schema changes, instead of returning SQLITE_SCHEMA as it always used to do, sqlite3_step() will automatically recompile the SQL statement and try to run it again.

  2. When an error occurs, sqlite3_step() will return one of the detailed error codes or extended error codes. The legacy behavior was that sqlite3_step() would only return a generic SQLITE_ERROR result code and the application would have to make a second call to sqlite3_reset() in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

  3. If the specific value bound to host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first sqlite3_step() call following any change to the bindings of that parameter. The specific value of WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT3 compile-time option is enabled. the

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Tracing And Profiling Functions

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
void *sqlite3_profile(sqlite3*,
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);

These routines register callback functions that can be used for tracing and profiling the execution of SQL statements.

The callback function registered by sqlite3_trace() is invoked at various times when an SQL statement is being run by sqlite3_step(). The sqlite3_trace() callback is invoked with a UTF-8 rendering of the SQL statement text as the statement first begins executing. Additional sqlite3_trace() callbacks might occur as each triggered subprogram is entered. The callbacks for triggers contain a UTF-8 SQL comment that identifies the trigger.

The callback function registered by sqlite3_profile() is invoked as each SQL statement finishes. The profile callback contains the original statement text and an estimate of wall-clock time of how long that statement took to run. The profile callback time is in units of nanoseconds, however the current implementation is only capable of millisecond resolution so the six least significant digits in the time are meaningless. Future versions of SQLite might provide greater resolution on the profiler callback. The sqlite3_profile() function is considered experimental and is subject to change in future versions of SQLite.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Query Progress Callbacks

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

The sqlite3_progress_handler(D,N,X,P) interface causes the callback function X to be invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table() for database connection D. An example use for this interface is to keep a GUI updated during a large query.

The parameter P is passed through as the only parameter to the callback function X. The parameter N is the number of virtual machine instructions that are evaluated between successive invocations of the callback X.

Only a single progress handler may be defined at one time per database connection; setting a new progress handler cancels the old one. Setting parameter X to NULL disables the progress handler. The progress handler is also disabled by setting N to a value less than 1.

If the progress callback returns non-zero, the operation is interrupted. This feature can be used to implement a "Cancel" button on a GUI progress dialog box.

The progress handler callback must not do anything that will modify the database connection that invoked the progress handler. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Pseudo-Random Number Generator

void sqlite3_randomness(int N, void *P);

SQLite contains a high-quality pseudo-random number generator (PRNG) used to select random ROWIDs when inserting new records into a table that already uses the largest possible ROWID. The PRNG is also used for the build-in random() and randomblob() SQL functions. This interface allows applications to access the same PRNG for other purposes.

A call to this routine stores N bytes of randomness into buffer P.

The first time this routine is invoked (either internally or by the application) the PRNG is seeded using randomness obtained from the xRandomness method of the default sqlite3_vfs object. On all subsequent invocations, the pseudo-randomness is generated internally and without recourse to the sqlite3_vfs xRandomness method.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Attempt To Free Heap Memory

int sqlite3_release_memory(int);

The sqlite3_release_memory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database library. Memory used to cache database pages to improve performance is an example of non-essential memory. sqlite3_release_memory() returns the number of bytes actually freed, which might be more or less than the amount requested. The sqlite3_release_memory() routine is a no-op returning zero if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Reset A Prepared Statement Object

int sqlite3_reset(sqlite3_stmt *pStmt);

The sqlite3_reset() function is called to reset a prepared statement object back to its initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind_*() API retain their values. Use sqlite3_clear_bindings() to reset the bindings.

The sqlite3_reset(S) interface resets the prepared statement S back to the beginning of its program.

If the most recent call to sqlite3_step(S) for the prepared statement S returned SQLITE_ROW or SQLITE_DONE, or if sqlite3_step(S) has never before been called on S, then sqlite3_reset(S) returns SQLITE_OK.

If the most recent call to sqlite3_step(S) for the prepared statement S indicated an error, then sqlite3_reset(S) returns an appropriate error code.

The sqlite3_reset(S) interface does not change the values of any bindings on the prepared statement S.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Reset Automatic Extension Loading

void sqlite3_reset_auto_extension(void);

This interface disables all automatic extensions previously registered using sqlite3_auto_extension().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Setting The Result Of An SQL Function

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_zeroblob(sqlite3_context*, int n);

These routines are used by the xFunc or xFinal callbacks that implement SQL functions and aggregates. See sqlite3_create_function() and sqlite3_create_function16() for additional information.

These functions work very much like the parameter binding family of functions used to bind values to host parameters in prepared statements. Refer to the SQL parameter documentation for additional information.

The sqlite3_result_blob() interface sets the result from an application-defined function to be the BLOB whose content is pointed to by the second parameter and which is N bytes long where N is the third parameter.

The sqlite3_result_zeroblob() interfaces set the result of the application-defined function to be a BLOB containing all zero bytes and N bytes in size, where N is the value of the 2nd parameter.

The sqlite3_result_double() interface sets the result from an application-defined function to be a floating point value specified by its 2nd argument.

The sqlite3_result_error() and sqlite3_result_error16() functions cause the implemented SQL function to throw an exception. SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() as the text of an error message. SQLite interprets the error message string from sqlite3_result_error() as UTF-8. SQLite interprets the string from sqlite3_result_error16() as UTF-16 in native byte order. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is negative then SQLite takes as the error message all text up through the first zero character. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is non-negative then SQLite takes that many bytes (not characters) from the 2nd parameter as the error message. The sqlite3_result_error() and sqlite3_result_error16() routines make a private copy of the error message text before they return. Hence, the calling function can deallocate or modify the text after they return without harm. The sqlite3_result_error_code() function changes the error code returned by SQLite as a result of an error in a function. By default, the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() or sqlite3_result_error16() resets the error code to SQLITE_ERROR.

The sqlite3_result_toobig() interface causes SQLite to throw an error indicating that a string or BLOB is too long to represent.

The sqlite3_result_nomem() interface causes SQLite to throw an error indicating that a memory allocation failed.

The sqlite3_result_int() interface sets the return value of the application-defined function to be the 32-bit signed integer value given in the 2nd argument. The sqlite3_result_int64() interface sets the return value of the application-defined function to be the 64-bit signed integer value given in the 2nd argument.

The sqlite3_result_null() interface sets the return value of the application-defined function to be NULL.

The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces set the return value of the application-defined function to be a text string which is represented as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 big endian, respectively. SQLite takes the text result from the application from the 2nd parameter of the sqlite3_result_text* interfaces. If the 3rd parameter to the sqlite3_result_text* interfaces is negative, then SQLite takes result text from the 2nd parameter through the first zero character. If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, then as many bytes (not characters) of the text pointed to by the 2nd parameter are taken as the application-defined function result. If the 3rd parameter is non-negative, then it must be the byte offset into the string where the NUL terminator would appear if the string where NUL terminated. If any NUL characters occur in the string at a byte offset that is less than the value of the 3rd parameter, then the resulting string will contain embedded NULs and the result of expressions operating on strings with embedded NULs is undefined. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that function as the destructor on the text or BLOB result when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite assumes that the text or BLOB result is in constant space and does not copy the content of the parameter nor call a destructor on the content when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_TRANSIENT then SQLite makes a copy of the result into space obtained from from sqlite3_malloc() before it returns.

The sqlite3_result_value() interface sets the result of the application-defined function to be a copy the unprotected sqlite3_value object specified by the 2nd parameter. The sqlite3_result_value() interface makes a copy of the sqlite3_value so that the sqlite3_value specified in the parameter may change or be deallocated after sqlite3_result_value() returns without harm. A protected sqlite3_value object may always be used where an unprotected sqlite3_value object is required, so either kind of sqlite3_value object can be used with this interface.

If these routines are called from within the different thread than the one containing the application-defined function that received the sqlite3_context pointer, the results are undefined.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Compile-Time Authorization Callbacks

int sqlite3_set_authorizer(
  sqlite3*,
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  void *pUserData
);

This routine registers an authorizer callback with a particular database connection, supplied in the first argument. The authorizer callback is invoked as SQL statements are being compiled by sqlite3_prepare() or its variants sqlite3_prepare_v2(), sqlite3_prepare16() and sqlite3_prepare16_v2(). At various points during the compilation process, as logic is being created to perform various actions, the authorizer callback is invoked to see if those actions are allowed. The authorizer callback should return SQLITE_OK to allow the action, SQLITE_IGNORE to disallow the specific action but allow the SQL statement to continue to be compiled, or SQLITE_DENY to cause the entire SQL statement to be rejected with an error. If the authorizer callback returns any value other than SQLITE_IGNORE, SQLITE_OK, or SQLITE_DENY then the sqlite3_prepare_v2() or equivalent call that triggered the authorizer will fail with an error message.

When the callback returns SQLITE_OK, that means the operation requested is ok. When the callback returns SQLITE_DENY, the sqlite3_prepare_v2() or equivalent call that triggered the authorizer will fail with an error message explaining that access is denied.

The first parameter to the authorizer callback is a copy of the third parameter to the sqlite3_set_authorizer() interface. The second parameter to the callback is an integer action code that specifies the particular action to be authorized. The third through sixth parameters to the callback are zero-terminated strings that contain additional details about the action to be authorized.

If the action code is SQLITE_READ and the callback returns SQLITE_IGNORE then the prepared statement statement is constructed to substitute a NULL value in place of the table column that would have been read if SQLITE_OK had been returned. The SQLITE_IGNORE return can be used to deny an untrusted user access to individual columns of a table. If the action code is SQLITE_DELETE and the callback returns SQLITE_IGNORE then the DELETE operation proceeds but the truncate optimization is disabled and all rows are deleted individually.

An authorizer is used when preparing SQL statements from an untrusted source, to ensure that the SQL statements do not try to access data they are not allowed to see, or that they do not try to execute malicious statements that damage the database. For example, an application may allow a user to enter arbitrary SQL queries for evaluation by a database. But the application does not want the user to be able to make arbitrary changes to the database. An authorizer could then be put in place while the user-entered SQL is being prepared that disallows everything except SELECT statements.

Applications that need to process SQL from untrusted sources might also consider lowering resource limits using sqlite3_limit() and limiting database size using the max_page_count PRAGMA in addition to using an authorizer.

Only a single authorizer can be in place on a database connection at a time. Each call to sqlite3_set_authorizer overrides the previous call. Disable the authorizer by installing a NULL callback. The authorizer is disabled by default.

The authorizer callback must not do anything that will modify the database connection that invoked the authorizer callback. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

When sqlite3_prepare_v2() is used to prepare a statement, the statement might be re-prepared during sqlite3_step() due to a schema change. Hence, the application should ensure that the correct authorizer callback remains in place during the sqlite3_step().

Note that the authorizer callback is invoked only during sqlite3_prepare() or its variants. Authorization is not performed during statement evaluation in sqlite3_step(), unless as stated in the previous paragraph, sqlite3_step() invokes sqlite3_prepare_v2() to reprepare a statement after a schema change.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Suspend Execution For A Short Time

int sqlite3_sleep(int);

The sqlite3_sleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter.

If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. The number of milliseconds of sleep actually requested from the operating system is returned.

SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. If the xSleep() method of the default VFS is not implemented correctly, or not implemented at all, then the behavior of sqlite3_sleep() may deviate from the description in the previous paragraphs.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Deprecated Soft Heap Limit Interface

void sqlite3_soft_heap_limit(int N);

This is a deprecated version of the sqlite3_soft_heap_limit64() interface. This routine is provided for historical compatibility only. All new applications should use the sqlite3_soft_heap_limit64() interface rather than this one.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Impose A Limit On Heap Size

sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);

The sqlite3_soft_heap_limit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQLITE_NOMEM error. In other words, the soft heap limit is advisory only.

The return value from sqlite3_soft_heap_limit64() is the size of the soft heap limit prior to the call. If the argument N is negative then no change is made to the soft heap limit. Hence, the current size of the soft heap limit can be determined by invoking sqlite3_soft_heap_limit64() with a negative argument.

If the argument N is zero then the soft heap limit is disabled.

The soft heap limit is not enforced in the current implementation if one or more of following conditions are true:

  • The soft heap limit is set to zero.
  • Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) start-time option and the SQLITE_DEFAULT_MEMSTATUS compile-time option.
  • An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE,...).
  • The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) rather than from the heap.

Beginning with SQLite version 3.7.3, the soft heap limit is enforced regardless of whether or not the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option is invoked. With SQLITE_ENABLE_MEMORY_MANAGEMENT, the soft heap limit is enforced on every memory allocation. Without SQLITE_ENABLE_MEMORY_MANAGEMENT, the soft heap limit is only enforced when memory is allocated by the page cache. Testing suggests that because the page cache is the predominate memory user in SQLite, most applications will achieve adequate soft heap limit enforcement without the use of SQLITE_ENABLE_MEMORY_MANAGEMENT.

The circumstances under which SQLite will enforce the soft heap limit may changes in future releases of SQLite.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Retrieving Statement SQL

const char *sqlite3_sql(sqlite3_stmt *pStmt);

This interface can be used to retrieve a saved copy of the original SQL text used to create a prepared statement if that statement was compiled using either sqlite3_prepare_v2() or sqlite3_prepare16_v2().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Database Connection Handle

typedef struct sqlite3 sqlite3;

Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3". It is useful to think of an sqlite3 pointer as an object. The sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces are its constructors, and sqlite3_close() is its destructor. There are many other interfaces (such as sqlite3_prepare_v2(), sqlite3_create_function(), and sqlite3_busy_timeout() to name but three) that are methods on an sqlite3 object.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

SQLite Runtime Status

int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);

This interface is used to retrieve runtime status information about the performance of SQLite, and optionally to reset various highwater marks. The first argument is an integer code for the specific parameter to measure. Recognized integer codes are of the form SQLITE_STATUS_.... The current value of the parameter is returned into *pCurrent. The highest recorded value is returned in *pHighwater. If the resetFlag is true, then the highest record value is reset after *pHighwater is written. Some parameters do not record the highest value. For those parameters nothing is written into *pHighwater and the resetFlag is ignored. Other parameters record only the highwater mark and not the current value. For these latter parameters nothing is written into *pCurrent.

The sqlite3_status() routine returns SQLITE_OK on success and a non-zero error code on failure.

This routine is threadsafe but is not atomic. This routine can be called while other threads are running the same or different SQLite interfaces. However the values returned in *pCurrent and *pHighwater reflect the status of SQLite at different points in time and it is possible that another thread might change the parameter in between the times when *pCurrent and *pHighwater are written.

See also: sqlite3_db_status()

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Evaluate An SQL Statement

int sqlite3_step(sqlite3_stmt*);

After a prepared statement has been prepared using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() or one of the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(), this function must be called one or more times to evaluate the statement.

The details of the behavior of the sqlite3_step() interface depend on whether the statement was prepared using the newer "v2" interface sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy interface sqlite3_prepare() and sqlite3_prepare16(). The use of the new "v2" interface is recommended for new applications but the legacy interface will continue to be supported.

In the legacy interface, the return value will be either SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. With the "v2" interface, any of the other result codes or extended result codes might be returned as well.

SQLITE_BUSY means that the database engine was unable to acquire the database locks it needs to do its job. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within an explicit transaction then you should rollback the transaction before continuing.

SQLITE_DONE means that the statement has finished executing successfully. sqlite3_step() should not be called again on this virtual machine without first calling sqlite3_reset() to reset the virtual machine back to its initial state.

If the SQL statement being executed returns any data, then SQLITE_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. sqlite3_step() is called again to retrieve the next row of data.

SQLITE_ERROR means that a run-time error (such as a constraint violation) has occurred. sqlite3_step() should not be called again on the VM. More information may be found by calling sqlite3_errmsg(). With the legacy interface, a more specific error code (for example, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, and so forth) can be obtained by calling sqlite3_reset() on the prepared statement. In the "v2" interface, the more specific error code is returned directly by sqlite3_step().

SQLITE_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a prepared statement that has already been finalized or on one that had previously returned SQLITE_ERROR or SQLITE_DONE. Or it could be the case that the same database connection is being used by two or more threads at the same moment in time.

For all versions of SQLite up to and including 3.6.23.1, a call to sqlite3_reset() was required after sqlite3_step() returned anything other than SQLITE_ROW before any subsequent invocation of sqlite3_step(). Failure to reset the prepared statement using sqlite3_reset() would result in an SQLITE_MISUSE return from sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began calling sqlite3_reset() automatically in this circumstance rather than returning SQLITE_MISUSE. This is not considered a compatibility break because any application that ever receives an SQLITE_MISUSE error is broken by definition. The SQLITE_OMIT_AUTORESET compile-time option can be used to restore the legacy behavior.

Goofy Interface Alert: In the legacy interface, the sqlite3_step() API always returns a generic error code, SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE. You must call sqlite3_reset() or sqlite3_finalize() in order to find one of the specific error codes that better describes the error. We admit that this is a goofy design. The problem has been fixed with the "v2" interface. If you prepare all of your SQL statements using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead of the legacy sqlite3_prepare() and sqlite3_prepare16() interfaces, then the more specific error codes are returned directly by sqlite3_step(). The use of the "v2" interface is recommended.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

SQL Statement Object

typedef struct sqlite3_stmt sqlite3_stmt;

An instance of this object represents a single SQL statement. This object is variously known as a "prepared statement" or a "compiled SQL statement" or simply as a "statement".

The life of a statement object goes something like this:

  1. Create the object using sqlite3_prepare_v2() or a related function.
  2. Bind values to host parameters using the sqlite3_bind_*() interfaces.
  3. Run the SQL by calling sqlite3_step() one or more times.
  4. Reset the statement using sqlite3_reset() then go back to step 2. Do this zero or more times.
  5. Destroy the object using sqlite3_finalize().

Refer to documentation on individual methods above for additional information.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Determine If An SQL Statement Writes The Database

int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);

The sqlite3_stmt_readonly(X) interface returns true (non-zero) if and only if the prepared statement X makes no direct changes to the content of the database file.

Note that application-defined SQL functions or virtual tables might change the database indirectly as a side effect. For example, if an application defines a function "eval()" that calls sqlite3_exec(), then the following SQL statement would change the database file through side-effects:

SELECT eval('DELETE FROM t1') FROM t2;

But because the SELECT statement does not change the database file directly, sqlite3_stmt_readonly() would still return true.

Transaction control statements such as BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE cause sqlite3_stmt_readonly() to return true, since the statements themselves do not actually modify the database but rather they control the timing of when other statements modify the database. The ATTACH and DETACH statements also cause sqlite3_stmt_readonly() to return true since, while those statements change the configuration of a database connection, they do not make changes to the content of the database files on disk.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Prepared Statement Status

int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);

Each prepared statement maintains various SQLITE_STMTSTATUS counters that measure the number of times it has performed specific operations. These counters can be used to monitor the performance characteristics of the prepared statements. For example, if the number of table steps greatly exceeds the number of table searches or result rows, that would tend to indicate that the prepared statement is using a full table scan rather than an index.

This interface is used to retrieve and reset counter values from a prepared statement. The first argument is the prepared statement object to be interrogated. The second argument is an integer code for a specific SQLITE_STMTSTATUS counter to be interrogated. The current value of the requested counter is returned. If the resetFlg is true, then the counter is reset to zero after this interface call returns.

See also: sqlite3_status() and sqlite3_db_status().

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

String Comparison

int sqlite3_strnicmp(const char *, const char *, int);

The sqlite3_strnicmp() API allows applications and extensions to compare the contents of two buffers containing UTF-8 strings in a case-independent fashion, using the same definition of case independence that SQLite uses internally when comparing identifiers.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Extract Metadata About A Column Of A Table

int sqlite3_table_column_metadata(
  sqlite3 *db,                /* Connection handle */
  const char *zDbName,        /* Database name or NULL */
  const char *zTableName,     /* Table name */
  const char *zColumnName,    /* Column name */
  char const **pzDataType,    /* OUTPUT: Declared data type */
  char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
  int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
  int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
  int *pAutoinc               /* OUTPUT: True if column is auto-increment */
);

This routine returns metadata about a specific column of a specific database table accessible using the database connection handle passed as the first function argument.

The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp", or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm used by the database engine to resolve unqualified table references.

The third and fourth parameters to this function are the table and column name of the desired column, respectively. Neither of these parameters may be NULL.

Metadata is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of metadata is omitted.

Parameter Output
Type 		Description

5th | const char* | Data type
6th | const char* | Name of default collation sequence
7th | int | True if column has a NOT NULL constraint
8th | int | True if column is part of the PRIMARY KEY
9th | int | True if column is AUTOINCREMENT

The memory pointed to by the character pointers returned for the declaration type and collation sequence is valid only until the next call to any SQLite API function.

If the specified table is actually a view, an error code is returned.

If the specified column is "rowid", "oid" or "_rowid_" and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no explicitly declared INTEGER PRIMARY KEY column, then the output parameters are set as follows:

data type: "INTEGER"
collation sequence: "BINARY"
not null: 0
primary key: 1
auto increment: 0

This function may load one or more schemas from database files. If an error occurs during this process, or if the requested table or column cannot be found, an error code is returned and an error message left in the database connection (to be retrieved using sqlite3_errmsg()).

This API is only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol defined.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Name Of The Folder Holding Temporary Files

SQLITE_EXTERN char *sqlite3_temp_directory;

If this global variable is made to point to a string which is the name of a folder (a.k.a. directory), then all temporary files created by SQLite when using a built-in VFS will be placed in that directory. If this variable is a NULL pointer, then SQLite performs a search for an appropriate temporary file directory.

It is not safe to read or modify this variable in more than one thread at a time. It is not safe to read or modify this variable if a database connection is being used at the same time in a separate thread. It is intended that this variable be set once as part of process initialization and before any SQLite interface routines have been called and that this variable remain unchanged thereafter.

The temp_store_directory pragma may modify this variable and cause it to point to memory obtained from sqlite3_malloc. Furthermore, the temp_store_directory pragma always assumes that any string that this variable points to is held in memory obtained from sqlite3_malloc and the pragma may attempt to free that memory using sqlite3_free. Hence, if this variable is modified directly, either it should be made NULL or made to point to memory obtained from sqlite3_malloc or else the use of the temp_store_directory pragma should be avoided.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Testing Interface

int sqlite3_test_control(int op, ...);

The sqlite3_test_control() interface is used to read out internal state of SQLite and to inject faults into SQLite for testing purposes. The first parameter is an operation code that determines the number, meaning, and operation of all subsequent parameters.

This interface is not for use by applications. It exists solely for verifying the correct operation of the SQLite library. Depending on how the SQLite library is compiled, this interface might not exist.

The details of the operation codes, their meanings, the parameters they take, and what they do are all subject to change without notice. Unlike most of the SQLite API, this function is not guaranteed to operate consistently from one release to the next.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Test To See If The Library Is Threadsafe

int sqlite3_threadsafe(void);

The sqlite3_threadsafe() function returns zero if and only if SQLite was compiled mutexing code omitted due to the SQLITE_THREADSAFE compile-time option being set to 0.

SQLite can be compiled with or without mutexes. When the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes are enabled and SQLite is threadsafe. When the SQLITE_THREADSAFE macro is 0, the mutexes are omitted. Without the mutexes, it is not safe to use SQLite concurrently from more than one thread.

Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes. But for maximum safety, mutexes should be enabled. The default behavior is for mutexes to be enabled.

This interface can be used by an application to make sure that the version of SQLite that it is linking against was compiled with the desired setting of the SQLITE_THREADSAFE macro.

This interface only reports on the compile-time mutex setting of the SQLITE_THREADSAFE flag. If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but can be fully or partially disabled using a call to sqlite3_config() with the verbs SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, or SQLITE_CONFIG_MUTEX. The return value of the sqlite3_threadsafe() function shows only the compile-time setting of thread safety, not any run-time changes to that setting made by sqlite3_config(). In other words, the return value from sqlite3_threadsafe() is unchanged by calls to sqlite3_config().

See the threading mode documentation for additional information.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Total Number Of Rows Modified

int sqlite3_total_changes(sqlite3*);

This function returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened. The count returned by sqlite3_total_changes() includes all changes from all trigger contexts and changes made by foreign key actions. However, the count does not include changes used to implement REPLACE constraints, do rollbacks or ABORT processing, or DROP TABLE processing. The count does not include rows of views that fire an INSTEAD OF trigger, though if the INSTEAD OF trigger makes changes of its own, those changes are counted. The sqlite3_total_changes() function counts the changes as soon as the statement that makes them is completed (when the statement handle is passed to sqlite3_reset() or sqlite3_finalize()).

See also the sqlite3_changes() interface, the count_changes pragma, and the total_changes() SQL function.

If a separate thread makes changes on the same database connection while sqlite3_total_changes() is running then the value returned is unpredictable and not meaningful.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Unlock Notification

int sqlite3_unlock_notify(
  sqlite3 *pBlocked,                          /* Waiting connection */
  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
  void *pNotifyArg                            /* Argument to pass to xNotify */
);

When running in shared-cache mode, a database operation may fail with an SQLITE_LOCKED error if the required locks on the shared-cache or individual tables within the shared-cache cannot be obtained. See SQLite Shared-Cache Mode for a description of shared-cache locking. This API may be used to register a callback that SQLite will invoke when the connection currently holding the required lock relinquishes it. This API is only available if the library was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor symbol defined.

See Also: Using the SQLite Unlock Notification Feature.

Shared-cache locks are released when a database connection concludes its current transaction, either by committing it or rolling it back.

When a connection (known as the blocked connection) fails to obtain a shared-cache lock and SQLITE_LOCKED is returned to the caller, the identity of the database connection (the blocking connection) that has locked the required resource is stored internally. After an application receives an SQLITE_LOCKED error, it may call the sqlite3_unlock_notify() method with the blocked connection handle as the first argument to register for a callback that will be invoked when the blocking connections current transaction is concluded. The callback is invoked from within the sqlite3_step or sqlite3_close call that concludes the blocking connections transaction.

If sqlite3_unlock_notify() is called in a multi-threaded application, there is a chance that the blocking connection will have already concluded its transaction by the time sqlite3_unlock_notify() is invoked. If this happens, then the specified callback is invoked immediately, from within the call to sqlite3_unlock_notify().

If the blocked connection is attempting to obtain a write-lock on a shared-cache table, and more than one other connection currently holds a read-lock on the same table, then SQLite arbitrarily selects one of the other connections to use as the blocking connection.

There may be at most one unlock-notify callback registered by a blocked connection. If sqlite3_unlock_notify() is called when the blocked connection already has a registered unlock-notify callback, then the new callback replaces the old. If sqlite3_unlock_notify() is called with a NULL pointer as its second argument, then any existing unlock-notify callback is canceled. The blocked connections unlock-notify callback may also be canceled by closing the blocked connection using sqlite3_close().

The unlock-notify callback is not reentrant. If an application invokes any sqlite3_xxx API functions from within an unlock-notify callback, a crash or deadlock may be the result.

Unless deadlock is detected (see below), sqlite3_unlock_notify() always returns SQLITE_OK.

Callback Invocation Details

When an unlock-notify callback is registered, the application provides a single void* pointer that is passed to the callback when it is invoked. However, the signature of the callback function allows SQLite to pass it an array of void* context pointers. The first argument passed to an unlock-notify callback is a pointer to an array of void* pointers, and the second is the number of entries in the array.

When a blocking connections transaction is concluded, there may be more than one blocked connection that has registered for an unlock-notify callback. If two or more such blocked connections have specified the same callback function, then instead of invoking the callback function multiple times, it is invoked once with the set of void* context pointers specified by the blocked connections bundled together into an array. This gives the application an opportunity to prioritize any actions related to the set of unblocked database connections.

Deadlock Detection

Assuming that after registering for an unlock-notify callback a database waits for the callback to be issued before taking any further action (a reasonable assumption), then using this API may cause the application to deadlock. For example, if connection X is waiting for connection Y's transaction to be concluded, and similarly connection Y is waiting on connection X's transaction, then neither connection will proceed and the system may remain deadlocked indefinitely.

To avoid this scenario, the sqlite3_unlock_notify() performs deadlock detection. If a given call to sqlite3_unlock_notify() would put the system in a deadlocked state, then SQLITE_LOCKED is returned and no unlock-notify callback is registered. The system is said to be in a deadlocked state if connection A has registered for an unlock-notify callback on the conclusion of connection B's transaction, and connection B has itself registered for an unlock-notify callback when connection A's transaction is concluded. Indirect deadlock is also detected, so the system is also considered to be deadlocked if connection B has registered for an unlock-notify callback on the conclusion of connection C's transaction, where connection C is waiting on connection A. Any number of levels of indirection are allowed.

The "DROP TABLE" Exception

When a call to sqlite3_step() returns SQLITE_LOCKED, it is almost always appropriate to call sqlite3_unlock_notify(). There is however, one exception. When executing a "DROP TABLE" or "DROP INDEX" statement, SQLite checks if there are any currently executing SELECT statements that belong to the same connection. If there are, SQLITE_LOCKED is returned. In this case there is no "blocking connection", so invoking sqlite3_unlock_notify() results in the unlock-notify callback being invoked immediately. If the application then re-attempts the "DROP TABLE" or "DROP INDEX" query, an infinite loop might be the result.

One way around this problem is to check the extended error code returned by an sqlite3_step() call. If there is a blocking connection, then the extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in the special "DROP TABLE/INDEX" case, the extended error code is just SQLITE_LOCKED.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Data Change Notification Callbacks

void *sqlite3_update_hook(
  sqlite3*,
  void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  void*
);

The sqlite3_update_hook() interface registers a callback function with the database connection identified by the first argument to be invoked whenever a row is updated, inserted or deleted. Any callback set by a previous call to this function for the same database connection is overridden.

The second argument is a pointer to the function to invoke when a row is updated, inserted or deleted. The first argument to the callback is a copy of the third argument to sqlite3_update_hook(). The second callback argument is one of SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE, depending on the operation that caused the callback to be invoked. The third and fourth arguments to the callback contain pointers to the database and table name containing the affected row. The final callback parameter is the rowid of the row. In the case of an update, this is the rowid after the update takes place.

The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).

In the current implementation, the update hook is not invoked when duplication rows are deleted because of an ON CONFLICT REPLACE clause. Nor is the update hook invoked when rows are deleted using the truncate optimization. The exceptions defined in this paragraph might change in a future release of SQLite.

The update hook implementation must not do anything that will modify the database connection that invoked the update hook. Any actions to modify the database connection must be deferred until after the completion of the sqlite3_step() call that triggered the update hook. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

The sqlite3_update_hook(D,C,P) function returns the P argument from the previous call on the same database connection D, or NULL for the first call on D.

See also the sqlite3_commit_hook() and sqlite3_rollback_hook() interfaces.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Obtain Values For URI Parameters

const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);

This is a utility routine, useful to VFS implementations, that checks to see if a database file was a URI that contained a specific query parameter, and if so obtains the value of the query parameter.

The zFilename argument is the filename pointer passed into the xOpen() method of a VFS implementation. The zParam argument is the name of the query parameter we seek. This routine returns the value of the zParam parameter if it exists. If the parameter does not exist, this routine returns a NULL pointer.

If the zFilename argument to this function is not a pointer that SQLite passed into the xOpen VFS method, then the behavior of this routine is undefined and probably undesirable.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

User Data For Functions

void *sqlite3_user_data(sqlite3_context*);

The sqlite3_user_data() interface returns a copy of the pointer that was the pUserData parameter (the 5th parameter) of the sqlite3_create_function() and sqlite3_create_function16() routines that originally registered the application defined function.

This routine must be called from the same thread in which the application-defined function is running.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Dynamically Typed Value Object

typedef struct Mem sqlite3_value;

SQLite uses the sqlite3_value object to represent all values that can be stored in a database table. SQLite uses dynamic typing for the values it stores. Values stored in sqlite3_value objects can be integers, floating point values, strings, BLOBs, or NULL.

An sqlite3_value object may be either "protected" or "unprotected". Some interfaces require a protected sqlite3_value. Other interfaces will accept either a protected or an unprotected sqlite3_value. Every interface that accepts sqlite3_value arguments specifies whether or not it requires a protected sqlite3_value.

The terms "protected" and "unprotected" refer to whether or not a mutex is held. An internal mutex is held for a protected sqlite3_value object but no mutex is held for an unprotected sqlite3_value object. If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0 and with sqlite3_threadsafe() returning 0) or if SQLite is run in one of reduced mutex modes SQLITE_CONFIG_SINGLETHREAD or SQLITE_CONFIG_MULTITHREAD then there is no distinction between protected and unprotected sqlite3_value objects and they can be used interchangeably. However, for maximum code portability it is recommended that applications still make the distinction between protected and unprotected sqlite3_value objects even when not strictly required.

The sqlite3_value objects that are passed as parameters into the implementation of application-defined SQL functions are protected. The sqlite3_value object returned by sqlite3_column_value() is unprotected. Unprotected sqlite3_value objects may only be used with sqlite3_result_value() and sqlite3_bind_value(). The sqlite3_value_type() family of interfaces require protected sqlite3_value objects.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Obtaining SQL Function Parameter Values

const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
const void *sqlite3_value_text16be(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);

The C-language implementation of SQL functions and aggregates uses this set of interface routines to access the parameter values on the function or aggregate.

The xFunc (for scalar functions) or xStep (for aggregates) parameters to sqlite3_create_function() and sqlite3_create_function16() define callbacks that implement the SQL functions and aggregates. The 3rd parameter to these callbacks is an array of pointers to protected sqlite3_value objects. There is one sqlite3_value object for each parameter to the SQL function. These routines are used to extract values from the sqlite3_value objects.

These routines work only with protected sqlite3_value objects. Any attempt to use these routines on an unprotected sqlite3_value object results in undefined behavior.

These routines work just like the corresponding column access functions except that these routines take a single protected sqlite3_value object pointer instead of a sqlite3_stmt* pointer and an integer column number.

The sqlite3_value_text16() interface extracts a UTF-16 string in the native byte-order of the host machine. The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces extract UTF-16 strings as big-endian and little-endian respectively.

The sqlite3_value_numeric_type() interface attempts to apply numeric affinity to the value. This means that an attempt is made to convert the value to an integer or floating point. If such a conversion is possible without loss of information (in other words, if the value is a string that looks like a number) then the conversion is performed. Otherwise no conversion occurs. The datatype after conversion is returned.

Please pay particular attention to the fact that the pointer returned from sqlite3_value_blob(), sqlite3_value_text(), or sqlite3_value_text16() can be invalidated by a subsequent call to sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text(), or sqlite3_value_text16().

These routines must be called from the same thread as the SQL function that supplied the sqlite3_value* parameters.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

OS Interface Object

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens.
  */
};

An instance of the sqlite3_vfs object defines the interface between the SQLite core and the underlying operating system. The "vfs" in the name of the object stands for "virtual file system". See the VFS documentation for further information.

The value of the iVersion field is initially 1 but may be larger in future versions of SQLite. Additional fields may be appended to this object when the iVersion value is increased. Note that the structure of the sqlite3_vfs object changes in the transaction between SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not modified.

The szOsFile field is the size of the subclassed sqlite3_file structure used by this VFS. mxPathname is the maximum length of a pathname in this VFS.

Registered sqlite3_vfs objects are kept on a linked list formed by the pNext pointer. The sqlite3_vfs_register() and sqlite3_vfs_unregister() interfaces manage this list in a thread-safe way. The sqlite3_vfs_find() interface searches the list. Neither the application code nor the VFS implementation should use the pNext pointer.

The pNext field is the only field in the sqlite3_vfs structure that SQLite will ever modify. SQLite will only access or modify this field while holding a particular static mutex. The application should never modify anything within the sqlite3_vfs object once the object has been registered.

The zName field holds the name of the VFS module. The name must be unique across all VFS modules.

SQLite guarantees that the zFilename parameter to xOpen is either a NULL pointer or string obtained from xFullPathname() with an optional suffix added. If a suffix is added to the zFilename parameter, it will consist of a single "-" character followed by no more than 10 alphanumeric and/or "-" characters. SQLite further guarantees that the string will be valid and unchanged until xClose() is called. Because of the previous sentence, the sqlite3_file can safely store a pointer to the filename if it needs to remember the filename for some reason. If the zFilename parameter to xOpen is a NULL pointer then xOpen must invent its own temporary name for the file. Whenever the xFilename parameter is NULL it will also be the case that the flags parameter will include SQLITE_OPEN_DELETEONCLOSE.

The flags argument to xOpen() includes all bits set in the flags argument to sqlite3_open_v2(). Or if sqlite3_open() or sqlite3_open16() is used, then flags includes at least SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. If xOpen() opens a file read-only then it sets *pOutFlags to include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be set.

SQLite will also add one of the following flags to the xOpen() call, depending on the object being opened:

  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
  • SQLITE_OPEN_WAL

The file I/O implementation can use the object type flags to change the way it deals with files. For example, an application that does not care about crash recovery or rollback might make the open of a journal file a no-op. Writes to this journal would also be no-ops, and any attempt to read the journal would return SQLITE_IOERR. Or the implementation might recognize that a database file will be doing page-aligned sector reads and writes in a random order and set up its I/O subsystem accordingly.

SQLite might also add one of the following flags to the xOpen method:

  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE

The SQLITE_OPEN_DELETEONCLOSE flag means the file should be deleted when it is closed. The SQLITE_OPEN_DELETEONCLOSE will be set for TEMP databases and their journals, transient databases, and subjournals.

The SQLITE_OPEN_EXCLUSIVE flag is always used in conjunction with the SQLITE_OPEN_CREATE flag, which are both directly analogous to the O_EXCL and O_CREAT flags of the POSIX open() API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the SQLITE_OPEN_CREATE, is used to indicate that file should always be created, and that it is an error if it already exists. It is not used to indicate the file should be opened for exclusive access.

At least szOsFile bytes of memory are allocated by SQLite to hold the sqlite3_file structure passed as the third argument to xOpen. The xOpen method does not have to allocate the structure; it should just fill it in. Note that the xOpen method must set the sqlite3_file.pMethods to either a valid sqlite3_io_methods object or to NULL. xOpen must do this even if the open fails. SQLite expects that the sqlite3_file.pMethods element will be valid after xOpen returns regardless of the success or failure of the xOpen call.

The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS to test for the existence of a file, or SQLITE_ACCESS_READWRITE to test whether a file is readable and writable, or SQLITE_ACCESS_READ to test whether a file is at least readable. The file can be a directory.

SQLite will always allocate at least mxPathname+1 bytes for the output buffer xFullPathname. The exact size of the output buffer is also passed as a parameter to both methods. If the output buffer is not large enough, SQLITE_CANTOPEN should be returned. Since this is handled as a fatal error by SQLite, vfs implementations should endeavor to prevent this by setting mxPathname to a sufficiently large value.

The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() interfaces are not strictly a part of the filesystem, but they are included in the VFS structure for completeness. The xRandomness() function attempts to return nBytes bytes of good-quality randomness into zOut. The return value is the actual number of bytes of randomness obtained. The xSleep() method causes the calling thread to sleep for at least the number of microseconds given. The xCurrentTime() method returns a Julian Day Number for the current date and time as a floating point value. The xCurrentTimeInt64() method returns, as an integer, the Julian Day Number multiplied by 86400000 (the number of milliseconds in a 24-hour day). SQLite will use the xCurrentTimeInt64() method to get the current date and time if that method is available (if iVersion is 2 or greater and the function pointer is not NULL) and will fall back to xCurrentTime() if xCurrentTimeInt64() is unavailable.

The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces are not used by the SQLite core. These optional interfaces are provided by some VFSes to facilitate testing of the VFS code. By overriding system calls with functions under its control, a test program can simulate faults and error conditions that would otherwise be difficult or impossible to induce. The set of system calls that can be overridden varies from one VFS to another, and from one version of the same VFS to the next. Applications that use these interfaces must be prepared for any or all of these interfaces to be NULL or for their behavior to change from one release to the next. Applications must not attempt to access any of these methods if the iVersion of the VFS is less than 3.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual File System Objects

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
int sqlite3_vfs_unregister(sqlite3_vfs*);

A virtual filesystem (VFS) is an sqlite3_vfs object that SQLite uses to interact with the underlying operating system. Most SQLite builds come with a single default VFS that is appropriate for the host computer. New VFSes can be registered and existing VFSes can be unregistered. The following interfaces are provided.

The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. Names are case sensitive. Names are zero-terminated UTF-8 strings. If there is no match, a NULL pointer is returned. If zVfsName is NULL then the default VFS is returned.

New VFSes are registered with sqlite3_vfs_register(). Each new VFS becomes the default VFS if the makeDflt flag is set. The same VFS can be registered multiple times without injury. To make an existing VFS into the default VFS, register it again with the makeDflt flag set. If two different VFSes with the same name are registered, the behavior is undefined. If a VFS is registered with a name that is NULL or an empty string, then the behavior is undefined.

Unregister a VFS with the sqlite3_vfs_unregister() interface. If the default VFS is unregistered, another VFS is chosen as the default. The choice for the new VFS is arbitrary.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Instance Object

struct sqlite3_vtab {
  const sqlite3_module *pModule;  /* The module for this virtual table */
  int nRef;                       /* NO LONGER USED */
  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  /* Virtual table implementations will typically add additional fields */
};

Every virtual table module implementation uses a subclass of this object to describe a particular instance of the virtual table. Each subclass will be tailored to the specific needs of the module implementation. The purpose of this superclass is to define certain fields that are common to all module implementations.

Virtual tables methods can set an error message by assigning a string obtained from sqlite3_mprintf() to zErrMsg. The method should take care that any prior string is freed by a call to sqlite3_free() prior to assigning a new string to zErrMsg. After the error message is delivered up to the client application, the string will be automatically freed by sqlite3_free() and the zErrMsg field will be zeroed.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Interface Configuration

int sqlite3_vtab_config(sqlite3*, int op, ...);

This function may be called by either the xConnect or xCreate method of a virtual table implementation to configure various facets of the virtual table interface.

If this interface is invoked outside the context of an xConnect or xCreate virtual table method then the behavior is undefined.

At present, there is only one option that may be configured using this function. (See SQLITE_VTAB_CONSTRAINT_SUPPORT.) Further options may be added in the future.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Virtual Table Cursor Object

struct sqlite3_vtab_cursor {
  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  /* Virtual table implementations will typically add additional fields */
};

Every virtual table module implementation uses a subclass of the following structure to describe cursors that point into the virtual table and are used to loop through the virtual table. Cursors are created using the xOpen method of the module and are destroyed by the xClose method. Cursors are used by the xFilter, xNext, xEof, xColumn, and xRowid methods of the module. Each module implementation will define the content of a cursor structure to suit its own needs.

This superclass exists in order to define fields of the cursor that are common to all implementations.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Determine The Virtual Table Conflict Policy

int sqlite3_vtab_on_conflict(sqlite3 *);

This function may only be called from within a call to the xUpdate method of a virtual table implementation for an INSERT or UPDATE operation. The value returned is one of SQLITE_ROLLBACK, SQLITE_IGNORE, SQLITE_FAIL, SQLITE_ABORT, or SQLITE_REPLACE, according to the ON CONFLICT mode of the SQL statement that triggered the call to the xUpdate method of the virtual table.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Configure an auto-checkpoint

int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

The sqlite3_wal_autocheckpoint(D,N) is a wrapper around sqlite3_wal_hook() that causes any database on database connection D to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.

The callback registered by this function replaces any existing callback registered using sqlite3_wal_hook(). Likewise, registering a callback using sqlite3_wal_hook() disables the automatic checkpoint mechanism configured by this function.

The wal_autocheckpoint pragma can be used to invoke this interface from SQL.

Every new database connection defaults to having the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT pages. The use of this interface is only necessary if the default setting is found to be suboptimal for a particular application.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Checkpoint a database

int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);

The sqlite3_wal_checkpoint(D,X) interface causes database named X on database connection D to be checkpointed. If X is NULL or an empty string, then a checkpoint is run on all databases of connection D. If the database connection D is not in write-ahead log mode then this interface is a harmless no-op.

The wal_checkpoint pragma can be used to invoke this interface from SQL. The sqlite3_wal_autocheckpoint() interface and the wal_autocheckpoint pragma can be used to cause this interface to be run whenever the WAL reaches a certain size threshold.

See also: sqlite3_wal_checkpoint_v2()

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Checkpoint a database

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Database handle */
  const char *zDb,                /* Name of attached database (or NULL) */
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
  int *pnLog,                     /* OUT: Size of WAL log in frames */
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
);

Run a checkpoint operation on WAL database zDb attached to database handle db. The specific operation is determined by the value of the eMode parameter:

SQLITE_CHECKPOINT_PASSIVE
Checkpoint as many frames as possible without waiting for any database readers or writers to finish. Sync the db file if all frames in the log are checkpointed. This mode is the same as calling sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.

SQLITE_CHECKPOINT_FULL
This mode blocks (calls the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This call blocks database writers while it is running, but not database readers.

SQLITE_CHECKPOINT_RESTART
This mode works the same way as SQLITE_CHECKPOINT_FULL, except after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next client to write to the database file restarts the log file from the beginning. This call blocks database writers while it is running, but not database readers.

If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to the total number of checkpointed frames (including any that were already checkpointed when this function is called). *pnLog and *pnCkpt may be populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK. If no values are available because of an error, they are both set to -1 before returning to communicate this to the caller.

All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.

The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQLITE_BUSY is returned in this case.

If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQLITE_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQLITE_BUSY is returned to the caller. If any other error occurs while processing an attached database, processing is abandoned and the error code returned to the caller immediately. If no error (SQLITE_BUSY or otherwise) is encountered while processing the attached databases, SQLITE_OK is returned.

If database zDb is the name of an attached database that is not in WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQLITE_ERROR is returned to the caller.

See also lists of Objects, Constants, and Functions.


Choose any three.

SQLite C Interface

Write-Ahead Log Commit Hook

void *sqlite3_wal_hook(
  sqlite3*,
  int(*)(void *,sqlite3*,const char*,int),
  void*
);

The sqlite3_wal_hook() function is used to register a callback that will be invoked each time a database connection commits data to a write-ahead log (i.e. whenever a transaction is committed in journal_mode=WAL mode).

The callback is invoked by SQLite after the commit has taken place and the associated write-lock on the database released, so the implementation may read, write or checkpoint the database as required.

The first parameter passed to the callback function when it is invoked is a copy of the third parameter passed to sqlite3_wal_hook() when registering the callback. The second is a copy of the database handle. The third parameter is the name of the database that was written to - either "main" or the name of an ATTACH-ed database. The fourth parameter is the number of pages currently in the write-ahead log file, including those that were just committed.

The callback function should normally return SQLITE_OK. If an error code is returned, that error will propagate back up through the SQLite code base to cause the statement that provoked the callback to report an error, though the commit will have still occurred. If the callback returns SQLITE_ROW or SQLITE_DONE, or if it returns a value that does not correspond to any valid SQLite error code, the results are undefined.

A single database handle may have at most a single write-ahead log callback registered at one time. Calling sqlite3_wal_hook() replaces any previously registered write-ahead log callback. Note that the sqlite3_wal_autocheckpoint() interface and the wal_autocheckpoint pragma both invoke sqlite3_wal_hook() and will those overwrite any prior sqlite3_wal_hook() settings.

See also lists of Objects, Constants, and Functions.


SQLite Release 3.0.0 On 2004 June 18 (3.0.0 alpha)

  • *** Alpha Release - Research And Testing Use Only ***
  • Support for internationalization including UTF-8, UTF-16, and user defined collating sequences.
  • New file format that is 25% to 35% smaller for typical use.
  • Improved concurrency.
  • Atomic commits for ATTACHed databases.
  • Remove cruft from the APIs.
  • BLOB support.
  • 64-bit rowids.
  • More information.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.1 On 2004 June 22 (3.0.1 alpha)

  • *** Alpha Release - Research And Testing Use Only ***
  • Lots of bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.2 On 2004 June 30 (3.0.2 beta)

  • The first beta release for SQLite 3.0.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.3 On 2004 July 22 (3.0.3 beta)

  • The second beta release for SQLite 3.0.
  • Add support for "PRAGMA page_size" to adjust the page size of the database.
  • Various bug fixes and documentation updates.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.4 On 2004 August 8 (3.0.4 beta)

  • CREATE TABLE and DROP TABLE now work correctly as prepared statements.
  • Fix a bug in VACUUM and UNIQUE indices.
  • Add the ".import" command to the command-line shell.
  • Fix a bug that could cause index corruption when an attempt to delete rows of a table is blocked by a pending query.
  • Library size optimizations.
  • Other minor bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.5 On 2004 August 29 (3.0.5 beta)

  • Support for ":AAA" style bind parameter names.
  • Added the new sqlite3_bind_parameter_name() interface.
  • Support for TCL variable names embedded in SQL statements in the TCL bindings.
  • The TCL bindings transfer data without necessarily doing a conversion to a string.
  • The database for TEMP tables is not created until it is needed.
  • Add the ability to specify an alternative temporary file directory using the "sqlite_temp_directory" global variable.
  • A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy handler to be called when there is contention for a RESERVED lock.
  • Various bug fixes and optimizations

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.6 On 2004 September 02 (3.0.6 beta)

  • Better detection and handling of corrupt database files.
  • The sqlite3_step() interface returns SQLITE_BUSY if it is unable to commit a change because of a lock
  • Combine the implementations of LIKE and GLOB into a single pattern-matching subroutine.
  • Miscellaneous code size optimizations and bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.7 On 2004 September 18 (3.0.7)

  • The BTree module allocates large buffers using malloc() instead of off of the stack, in order to play better on machines with limited stack space.
  • Fixed naming conflicts so that versions 2.8 and 3.0 can be linked and used together in the same ANSI-C source file.
  • New interface: sqlite3_bind_parameter_index()
  • Add support for wildcard parameters of the form: "?nnn"
  • Fix problems found on 64-bit systems.
  • Removed encode.c file (containing unused routines) from the version 3.0 source tree.
  • The sqlite3_trace() callbacks occur before each statement is executed, not when the statement is compiled.
  • Makefile updates and miscellaneous bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.0.8 On 2004 October 11 (3.0.8)

  • Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.
  • Allow new user-defined functions to be created when there are already one or more precompiled SQL statements.
  • Fix portability problems for MinGW/MSYS.
  • Fix a byte alignment problem on 64-bit Sparc machines.
  • Fix the ".import" command of the shell so that it ignores \r characters at the end of lines.
  • The "csv" mode option in the shell puts strings inside double-quotes.
  • Fix typos in documentation.
  • Convert array constants in the code to have type "const".
  • Numerous code optimizations, specially optimizations designed to make the code footprint smaller.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.0 On 2005 January 21 (3.1.0 ALPHA)

  • Autovacuum support added
  • CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added
  • Support for the EXISTS clause added.
  • Support for correlated subqueries added.
  • Added the ESCAPE clause on the LIKE operator.
  • Support for ALTER TABLE ... RENAME TABLE ... added
  • AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY
  • Many SQLITE_OMIT_ macros inserts to omit features at compile-time and reduce the library footprint.
  • The REINDEX command was added.
  • The engine no longer consults the main table if it can get all the information it needs from an index.
  • Many nuisance bugs fixed.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.1 On 2005 February 1 (3.1.1 BETA)

  • Automatic caching of prepared statements in the TCL interface
  • ATTACH and DETACH as well as some other operations cause existing prepared statements to expire.
  • Numerous minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.2 On 2005 February 15 (3.1.2)

  • Fix a bug that can lead to database corruption if there are two open connections to the same database and one connection does a VACUUM and the second makes some change to the database.
  • Allow "?" parameters in the LIMIT clause.
  • Fix VACUUM so that it works with AUTOINCREMENT.
  • Fix a race condition in AUTOVACUUM that can lead to corrupt databases
  • Add a numeric version number to the sqlite3.h include file.
  • Other minor bug fixes and performance enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.3 On 2005 February 19 (3.1.3)

  • Fix a problem with VACUUM on databases from which tables containing AUTOINCREMENT have been dropped.
  • Add forward compatibility to the future version 3.2 database file format.
  • Documentation updates

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.4 On 2005 March 10 (3.1.4)

  • Fix a bug in autovacuum that could cause database corruption if a CREATE UNIQUE INDEX fails because of a constraint violation. This problem only occurs if the new autovacuum feature introduced in version 3.1 is turned on.
  • The F_FULLSYNC ioctl (currently only supported on Mac OS X) is disabled if the synchronous pragma is set to something other than "full".
  • Add additional forward compatibility to the future version 3.2 database file format.
  • Fix a bug in WHERE clauses of the form (rowid<'2')
  • New SQLITE_OMIT_... compile-time options added
  • Updates to the man page
  • Remove the use of strcasecmp() from the shell
  • Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.5 On 2005 March 11 (3.1.5)

  • The ioctl on Mac OS X to control syncing to disk is F_FULLFSYNC, not F_FULLSYNC. The previous release had it wrong.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.1.6 On 2005 March 16 (3.1.6)

  • Fix a bug that could cause database corruption when inserting record into tables with around 125 columns.
  • sqlite3_step() is now much more likely to invoke the busy handler and less likely to return SQLITE_BUSY.
  • Fix memory leaks that used to occur after a malloc() failure.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.0 On 2005 March 21 (3.2.0)

  • Added support for ALTER TABLE ADD COLUMN.
  • Added support for the "T" separator in ISO-8601 date/time strings.
  • Improved support for Cygwin.
  • Numerous bug fixes and documentation updates.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.1 On 2005 March 29 (3.2.1)

  • Fix a memory allocation error in the new ADD COLUMN comment.
  • Documentation updates

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.2 On 2005 June 13 (3.2.2)

  • Added the sqlite3_db_handle() API
  • Added the sqlite3_get_autocommit() API
  • Added a REGEXP operator to the parser. There is no function to back up this operator in the standard build but users can add their own using sqlite3_create_function()
  • Speed improvements and library footprint reductions.
  • Fix byte alignment problems on 64-bit architectures.
  • Many, many minor bug fixes and documentation updates.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.3 On 2005 August 21 (3.2.3)

  • Added support for the CAST operator
  • Tcl interface allows BLOB values to be transferred to user-defined functions
  • Added the "transaction" method to the Tcl interface
  • Allow the DEFAULT value of a column to call functions that have constant operands
  • Added the ANALYZE command for gathering statistics on indices and using those statistics when picking an index in the optimizer
  • Remove the limit (formerly 100) on the number of terms in the WHERE clause
  • The right-hand side of the IN operator can now be a list of expressions instead of just a list of constants
  • Rework the optimizer so that it is able to make better use of indices
  • The order of tables in a join is adjusted automatically to make better use of indices
  • The IN operator is now a candidate for optimization even if the left-hand side is not the left-most term of the index. Multiple IN operators can be used with the same index.
  • WHERE clause expressions using BETWEEN and OR are now candidates for optimization
  • Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE compile-time option to set its default value to "on".
  • Use indices to help with GLOB expressions and LIKE expressions too when the case_sensitive_like pragma is enabled
  • Added support for grave-accent quoting for compatibility with MySQL
  • Improved test coverage
  • Dozens of minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.4 On 2005 August 24 (3.2.4)

  • Fix a bug introduced in the previous release that can cause a segfault while generating code for complex WHERE clauses.
  • Allow floating point literals to begin or end with a decimal point.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.5 On 2005 August 27 (3.2.5)

  • Fix a bug effecting DELETE and UPDATE statements that changed more than 40960 rows.
  • Change the makefile so that it no longer requires GNUmake extensions
  • Fix the --enable-threadsafe option on the configure script
  • Fix a code generator bug that occurs when the left-hand side of an IN operator is constant and the right-hand side is a SELECT statement
  • The PRAGMA synchronous=off statement now disables syncing of the master journal file in addition to the normal rollback journals

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.6 On 2005 September 17 (3.2.6)

  • Fix a bug that can cause database corruption if a VACUUM (or autovacuum) fails and is rolled back on a database that is larger than 1GiB
  • LIKE optimization now works for columns with COLLATE NOCASE
  • ORDER BY and GROUP BY now use bounded memory
  • Added support for COUNT(DISTINCT expr)
  • Change the way SUM() handles NULL values in order to comply with the SQL standard
  • Use fdatasync() instead of fsync() where possible in order to speed up commits slightly
  • Use of the CROSS keyword in a join turns off the table reordering optimization
  • Added the experimental and undocumented EXPLAIN QUERY PLAN capability
  • Use the unicode API in Windows

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.7 On 2005 September 24 (3.2.7)

  • GROUP BY now considers NULLs to be equal again, as it should
  • Now compiles on Solaris and OpenBSD and other Unix variants that lack the fdatasync() function
  • Now compiles on MSVC++6 again
  • Fix uninitialized variables causing malfunctions for various obscure queries
  • Correctly compute a LEFT OUTER JOINs that is constrained on the left table only

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.2.8 On 2005 December 19 (3.2.8)

  • Fix an obscure bug that can cause database corruption under the following unusual circumstances: A large INSERT or UPDATE statement which is part of an even larger transaction fails due to a uniqueness constraint but the containing transaction commits.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.0 On 2006 January 10 (3.3.0 alpha)

  • CHECK constraints
  • IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.
  • DESC indices
  • More efficient encoding of boolean values resulting in smaller database files
  • More aggressive SQLITE_OMIT_FLOATING_POINT
  • Separate INTEGER and REAL affinity
  • Added a virtual function layer for the OS interface
  • "exists" method added to the TCL interface
  • Improved response to out-of-memory errors
  • Database cache can be optionally shared between connections in the same thread
  • Optional READ UNCOMMITTED isolation (instead of the default isolation level of SERIALIZABLE) and table level locking when database connections share a common cache.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.1 On 2006 January 16 (3.3.1 alpha)

  • Countless bug fixes
  • Speed improvements
  • Database connections can now be used by multiple threads, not just the thread in which they were created.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.2 On 2006 January 24 (3.3.2 beta)

  • Bug fixes and speed improvements. Improved test coverage.
  • Changes to the OS-layer interface: mutexes must now be recursive.
  • Discontinue the use of thread-specific data for out-of-memory exception handling

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.3 On 2006 January 31 (3.3.3)

  • Removed support for an ON CONFLICT clause on CREATE INDEX - it never worked correctly so this should not present any backward compatibility problems.
  • Authorizer callback now notified of ALTER TABLE ADD COLUMN commands
  • After any changes to the TEMP database schema, all prepared statements are invalidated and must be recreated using a new call to sqlite3_prepare()
  • Other minor bug fixes in preparation for the first stable release of version 3.3

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.4 On 2006 February 11 (3.3.4)

  • Fix a blunder in the Unix mutex implementation that can lead to deadlock on multithreaded systems.
  • Fix an alignment problem on 64-bit machines
  • Added the fullfsync pragma.
  • Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs to give incorrect results.
  • The SUM function detects integer overflow and converts to accumulating an approximate result using floating point numbers
  • Host parameter names can begin with '@' for compatibility with SQL Server.
  • Other miscellaneous bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.5 On 2006 April 5 (3.3.5)

  • CHECK constraints use conflict resolution algorithms correctly.
  • The SUM() function throws an error on integer overflow.
  • Choose the column names in a compound query from the left-most SELECT instead of the right-most.
  • The sqlite3_create_collation() function honors the SQLITE_UTF16_ALIGNED flag.
  • SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite old data with zeros.
  • Detect integer overflow in abs().
  • The random() function provides 64 bits of randomness instead of only 32 bits.
  • Parser detects and reports automaton stack overflow.
  • Change the round() function to return REAL instead of TEXT.
  • Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to contain aggregate subqueries.
  • Skip over leading spaces in text to numeric conversions.
  • Various minor bug and documentation typo fixes and performance enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.6 On 2006 June 6 (3.3.6)

  • Plays better with virus scanners on Windows
  • Faster :memory: databases
  • Fix an obscure segfault in UTF-8 to UTF-16 conversions
  • Added driver for OS/2
  • Correct column meta-information returned for aggregate queries
  • Enhanced output from EXPLAIN QUERY PLAN
  • LIMIT 0 now works on subqueries
  • Bug fixes and performance enhancements in the query optimizer
  • Correctly handle NULL filenames in ATTACH and DETACH
  • Improved syntax error messages in the parser
  • Fix type coercion rules for the IN operator

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.7 On 2006 August 12 (3.3.7)

  • Added support for virtual tables (beta)
  • Added support for dynamically loaded extensions (beta)
  • The sqlite3_interrupt() routine can be called for a different thread
  • Added the MATCH operator.
  • The default file format is now 1.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.8 On 2006 October 9 (3.3.8)

  • Support for full text search using the FTS1 module (beta)
  • Added Mac OS X locking patches (beta - disabled by default)
  • Introduce extended error codes and add error codes for various kinds of I/O errors.
  • Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW
  • Fix the regression test suite so that it works with Tcl8.5
  • Enhance sqlite3_set_authorizer() to provide notification of calls to SQL functions.
  • Added experimental API: sqlite3_auto_extension()
  • Various minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.9 On 2007 January 4 (3.3.9)

  • Fix bugs in pager.c that could lead to database corruption if two processes both try to recover a hot journal at the same instant
  • Added the sqlite3_prepare_v2() API.
  • Fixed the ".dump" command in the command-line shell to show indices, triggers and views again.
  • Change the table_info pragma so that it returns NULL for the default value if there is no default value
  • Support for non-ASCII characters in win95 filenames
  • Query optimizer enhancements:
    • Optimizer does a better job of using indices to satisfy ORDER BY clauses that sort on the integer primary key
    • Use an index to satisfy an IS NULL operator in the WHERE clause
    • Fix a bug that was causing the optimizer to miss an OR optimization opportunity
    • The optimizer has more freedom to reorder tables in the FROM clause even in there are LEFT joins.
  • Extension loading supported added to WinCE
  • Allow constraint names on the DEFAULT clause in a table definition
  • Added the ".bail" command to the command-line shell
  • Make CSV (comma separate value) output from the command-line shell more closely aligned to accepted practice
  • Experimental FTS2 module added
  • Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies
  • VACUUM uses a temporary file in the official TEMP folder, not in the same directory as the original database
  • The prefix on temporary filenames on Windows is changed from "sqlite" to "etilqs".

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.10 On 2007 January 9 (3.3.10)

  • Fix bugs in the implementation of the new sqlite3_prepare_v2() API that can lead to segfaults.
  • Fix 1-second round-off errors in the strftime() function
  • Enhance the Windows OS layer to provide detailed error codes
  • Work around a win2k problem so that SQLite can use single-character database file names
  • The user_version and schema_version pragmas correctly set their column names in the result set
  • Documentation updates

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.11 On 2007 January 22 (3.3.11)

  • Fix another bug in the implementation of the new sqlite3_prepare_v2() API. We'll get it right eventually...
  • Fix a bug in the IS NULL optimization that was added in version 3.3.9 - the bug was causing incorrect results on certain LEFT JOINs that included in the WHERE clause an IS NULL constraint for the right table of the LEFT JOIN.
  • Make AreFileApisANSI() a no-op macro in WinCE since WinCE does not support this function.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.12 On 2007 January 27 (3.3.12)

  • Fix another bug in the IS NULL optimization that was added in version 3.3.9.
  • Fix an assertion fault that occurred on deeply nested views.
  • Limit the amount of output that PRAGMA integrity_check generates.
  • Minor syntactic changes to support a wider variety of compilers.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.13 On 2007 February 13 (3.3.13)

  • Add a "fragmentation" measurement in the output of sqlite3_analyzer.
  • Add the COLLATE operator used to explicitly set the collating sequence used by an expression. This feature is considered experimental pending additional testing.
  • Allow up to 64 tables in a join - the old limit was 32.
  • Added two new experimental functions: randomBlob() and hex(). Their intended use is to facilitate generating UUIDs.
  • Fix a problem where PRAGMA count_changes was causing incorrect results for updates on tables with triggers
  • Fix a bug in the ORDER BY clause optimizer for joins where the left-most table in the join is constrained by a UNIQUE index.
  • Fixed a bug in the "copy" method of the TCL interface.
  • Bug fixes in fts1 and fts2 modules.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.14 On 2007 April 2 (3.3.14)

  • Fix a bug (ticket #2273) that could cause a segfault when the IN operator is used one one term of a two-column index and the right-hand side of the IN operator contains a NULL.
  • Added a new OS interface method for determining the sector size of underlying media: sqlite3OsSectorSize().
  • A new algorithm for statements of the form INSERT INTO table1 SELECT * FROM table2 is faster and reduces fragmentation. VACUUM uses statements of this form and thus runs faster and defragments better.
  • Performance enhancements through reductions in disk I/O:
    • Do not read the last page of an overflow chain when deleting the row - just add that page to the freelist.
    • Do not store pages being deleted in the rollback journal.
    • Do not read in the (meaningless) content of pages extracted from the freelist.
    • Do not flush the page cache (and thus avoiding a cache refill) unless another process changes the underlying database file.
    • Truncate rather than delete the rollback journal when committing a transaction in exclusive access mode, or when committing the TEMP database.
  • Added support for exclusive access mode using "PRAGMA locking_mode=EXCLUSIVE"
  • Use heap space instead of stack space for large buffers in the pager - useful on embedded platforms with stack-space limitations.
  • Add a makefile target "sqlite3.c" that builds an amalgamation containing the core SQLite library C code in a single file.
  • Get the library working correctly when compiled with GCC option "-fstrict-aliasing".
  • Removed the vestigal SQLITE_PROTOCOL error.
  • Improvements to test coverage, other minor bugs fixed, memory leaks plugged, code refactored and/or recommended in places for easier reading.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.15 On 2007 April 9 (3.3.15)

  • Fix a bug introduced in 3.3.14 that caused a rollback of CREATE TEMP TABLE to leave the database connection wedged.
  • Fix a bug that caused an extra NULL row to be returned when a descending query was interrupted by a change to the database.
  • The FOR EACH STATEMENT clause on a trigger now causes a syntax error. It used to be silently ignored.
  • Fix an obscure and relatively harmless problem that might have caused a resource leak following an I/O error.
  • Many improvements to the test suite. Test coverage now exceeded 98%

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.16 On 2007 April 18 (3.3.16)

  • Fix a bug that caused VACUUM to fail if NULLs appeared in a UNIQUE column.
  • Reinstate performance improvements that were added in Version 3.3.14 but regressed in Version 3.3.15.
  • Fix problems with the handling of ORDER BY expressions on compound SELECT statements in subqueries.
  • Fix a potential segfault when destroying locks on WinCE in a multi-threaded environment.
  • Documentation updates.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.3.17 On 2007 April 25 (3.3.17)

  • When the "write_version" value of the database header is larger than what the library understands, make the database read-only instead of unreadable.
  • Other minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.4.0 On 2007 June 18 (3.4.0)

  • Fix a bug that can lead to database corruption if an SQLITE_BUSY error occurs in the middle of an explicit transaction and that transaction is later committed. Ticket #2409. See the CorruptionFollowingBusyError wiki page for details.
  • Fix a bug that can lead to database corruption if autovacuum mode is on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement which itself follows a cache overflow inside a transaction. See ticket #2418.
  • Added explicit upper bounds on the sizes and quantities of things SQLite can process. This change might cause compatibility problems for applications that use SQLite in the extreme, which is why the current release is 3.4.0 instead of 3.3.18.
  • Added support for Incremental BLOB I/O.
  • Added the sqlite3_bind_zeroblob() API and the zeroblob() SQL function.
  • Added support for Incremental Vacuum.
  • Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to support ARM7 processors with goofy endianness.
  • Removed all instances of sprintf() and strcpy() from the core library.
  • Added support for International Components for Unicode (ICU) to the full-text search extensions.

  • In the Windows OS driver, reacquire a SHARED lock if an attempt to acquire an EXCLUSIVE lock fails. Ticket #2354
  • Fix the REPLACE() function so that it returns NULL if the second argument is an empty string. Ticket #2324.
  • Document the hazards of type conversions in sqlite3_column_blob() and related APIs. Fix unnecessary type conversions. Ticket #2321.
  • Internationalization of the TRIM() function. Ticket #2323
  • Use memmove() instead of memcpy() when moving between memory regions that might overlap. Ticket #2334
  • Fix an optimizer bug involving subqueries in a compound SELECT that has both an ORDER BY and a LIMIT clause. Ticket #2339.
  • Make sure the sqlite3_snprintf() interface does not zero-terminate the buffer if the buffer size is less than 1. Ticket #2341
  • Fix the built-in printf logic so that it prints "NaN" not "Inf" for floating-point NaNs. Ticket #2345
  • When converting BLOB to TEXT, use the text encoding of the main database. Ticket #2349
  • Keep the full precision of integers (if possible) when casting to NUMERIC. Ticket #2364
  • Fix a bug in the handling of UTF16 codepoint 0xE000
  • Consider explicit collate clauses when matching WHERE constraints to indices in the query optimizer. Ticket #2391
  • Fix the query optimizer to correctly handle constant expressions in the ON clause of a LEFT JOIN. Ticket #2403
  • Fix the query optimizer to handle rowid comparisons to NULL correctly. Ticket #2404
  • Fix many potential segfaults that could be caused by malicious SQL statements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.4.1 On 2007 July 20 (3.4.1)

  • Fix a bug in VACUUM that can lead to database corruption if two processes are connected to the database at the same time and one VACUUMs then the other then modifies the database.
  • The expression "+column" is now considered the same as "column" when computing the collating sequence to use on the expression.
  • In the TCL language interface, "@variable" instead of "$variable" always binds as a blob.
  • Added PRAGMA freelist_count for determining the current size of the freelist.
  • The PRAGMA auto_vacuum=incremental setting is now persistent.
  • Add FD_CLOEXEC to all open files under Unix.
  • Fix a bug in the min()/max() optimization when applied to descending indices.
  • Make sure the TCL language interface works correctly with 64-bit integers on 64-bit machines.
  • Allow the value -9223372036854775808 as an integer literal in SQL statements.
  • Add the capability of "hidden" columns in virtual tables.
  • Use the macro SQLITE_PRIVATE (defaulting to "static") on all internal functions in the amalgamation.
  • Add pluggable tokenizers and ICU tokenization support to FTS2
  • Other minor bug fixes and documentation enhancements

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.4.2 On 2007 August 13 (3.4.2)

  • Fix a database corruption bug that might occur if a ROLLBACK command is executed in auto-vacuum mode and a very small sqlite3_soft_heap_limit is set. Ticket #2565.
  • Add the ability to run a full regression test with a small sqlite3_soft_heap_limit.
  • Fix other minor problems with using small soft heap limits.
  • Work-around for GCC bug 32575.
  • Improved error detection of misused aggregate functions.
  • Improvements to the amalgamation generator script so that all symbols are prefixed with either SQLITE_PRIVATE or SQLITE_API.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.0 On 2007 Sep 04 (3.5.0) alpha

  • Redesign the OS interface layer. See 34to35.html for details. *** Potentially incompatible change ***
  • The sqlite3_release_memory(), sqlite3_soft_heap_limit(), and sqlite3_enable_shared_cache() interfaces now work cross all threads in the process, not just the single thread in which they are invoked. *** Potentially incompatible change ***
  • Added the sqlite3_open_v2() interface.
  • Reimplemented the memory allocation subsystem and made it replaceable at compile-time.
  • Created a new mutex subsystem and made it replicable at compile-time.
  • The same database connection may now be used simultaneously by separate threads.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.1 On 2007 Oct 04 (3.5.1)

  • Nota Bene: We are not using terms "alpha" or "beta" on this release because the code is stable and because if we use those terms, nobody will upgrade. However, we still reserve the right to make incompatible changes to the new VFS interface in future releases.
  • Fix a bug in the handling of SQLITE_FULL errors that could lead to database corruption. Ticket #2686.
  • The test_async.c drive now does full file locking and works correctly when used simultaneously by multiple processes on the same database.
  • The CLI ignores whitespace (including comments) at the end of lines
  • Make sure the query optimizer checks dependencies on all terms of a compound SELECT statement. Ticket #2640.
  • Add demonstration code showing how to build a VFS for a raw mass storage without a filesystem.
  • Added an output buffer size parameter to the xGetTempname() method of the VFS layer.
  • Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset when a new transaction is started.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.2 On 2007 Nov 05 (3.5.2)

  • Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time option.
  • Always open files using FILE_FLAG_RANDOM_ACCESS under Windows.
  • The 3rd parameter of the built-in SUBSTR() function is now optional.
  • Bug fix: do not invoke the authorizer when reparsing the schema after a schema change.
  • Added the experimental malloc-free memory allocator in mem3.c.
  • Virtual machine stores 64-bit integer and floating point constants in binary instead of text for a performance boost.
  • Fix a race condition in test_async.c.
  • Added the ".timer" command to the CLI

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.3 On 2007 Nov 27 (3.5.3)

  • Move website and documentation files out of the source tree into a separate CM system.
  • Fix a long-standing bug in INSERT INTO ... SELECT ... statements where the SELECT is compound.
  • Fix a long-standing bug in RAISE(IGNORE) as used in BEFORE triggers.
  • Fixed the operator precedence for the ~ operator.
  • On Win32, do not return an error when attempting to delete a file that does not exist.
  • Allow collating sequence names to be quoted.
  • Modify the TCL interface to use sqlite3_prepare_v2().
  • Fix multiple bugs that can occur following a malloc() failure.
  • sqlite3_step() returns SQLITE_MISUSE instead of crashing when called with a NULL parameter.
  • FTS3 now uses the SQLite memory allocator exclusively. The FTS3 amalgamation can now be appended to the SQLite amalgamation to generate a super-amalgamation containing both.
  • The DISTINCT keyword now will sometimes use an INDEX if an appropriate index is available and the optimizer thinks its use might be advantageous.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.4 On 2007 Dec 14 (3.5.4)

  • Fix a critical bug in UPDATE or DELETE that occurs when an OR REPLACE clause or a trigger causes rows in the same table to be deleted as side effects. (See ticket #2832.) The most likely result of this bug is a segmentation fault, though database corruption is a possibility.
  • Bring the processing of ORDER BY into compliance with the SQL standard for case where a result alias and a table column name are in conflict. Correct behavior is to prefer the result alias. Older versions of SQLite incorrectly picked the table column. (See ticket #2822.)
  • The VACUUM command preserves the setting of the legacy_file_format pragma. (Ticket #2804.)
  • Productize and officially support the group_concat() SQL function.
  • Better optimization of some IN operator expressions.
  • Add the ability to change the auto_vacuum status of a database by setting the auto_vaccum pragma and VACUUMing the database.
  • Prefix search in FTS3 is much more efficient.
  • Relax the SQL statement length restriction in the CLI so that the ".dump" output of databases with very large BLOBs and strings can be played back to recreate the database.
  • Other small bug fixes and optimizations.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.5 On 2008 Jan 31 (3.5.5)

  • Convert the underlying virtual machine to be a register-based machine rather than a stack-based machine. The only user-visible change is in the output of EXPLAIN.
  • Add the build-in RTRIM collating sequence.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.6 On 2008 Feb 6 (3.5.6)

  • Fix a bug (ticket #2913) that prevented virtual tables from working in a LEFT JOIN. The problem was introduced into shortly before the 3.5.5 release.
  • Bring the OS/2 porting layer up-to-date.
  • Add the new sqlite3_result_error_code() API and use it in the implementation of ATTACH so that proper error codes are returned when an ATTACH fails.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.7 On 2008 Mar 17 (3.5.7)

  • Fix a bug (ticket #2927) in the register allocation for compound selects - introduced by the new VM code in version 3.5.5.
  • ALTER TABLE uses double-quotes instead of single-quotes for quoting filenames.
  • Use the WHERE clause to reduce the size of a materialized VIEW in an UPDATE or DELETE statement. (Optimization)
  • Do not apply the flattening optimization if the outer query is an aggregate and the inner query contains ORDER BY. (Ticket #2943)
  • Additional OS/2 updates
  • Added an experimental power-of-two, first-fit memory allocator.
  • Remove all instances of sprintf() from the code
  • Accept "Z" as the zulu timezone at the end of date strings
  • Fix a bug in the LIKE optimizer that occurs when the last character before the first wildcard is an upper-case "Z"
  • Added the "bitvec" object for keeping track of which pages have been journalled. Improves speed and reduces memory consumption, especially for large database files.
  • Get the SQLITE_ENABLE_LOCKING_STYLE macro working again on Mac OS X.
  • Store the statement journal in the temporary file directory instead of collocated with the database file.
  • Many improvements and cleanups to the configure script

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.8 On 2008 Apr 16 (3.5.8)

  • Expose SQLite's internal pseudo-random number generator (PRNG) via the sqlite3_randomness() interface
  • New interface sqlite3_context_db_handle() that returns the database connection handle that has invoked an application-defined SQL function.
  • New interface sqlite3_limit() allows size and length limits to be set on a per-connection basis and at run-time.
  • Improved crash-robustness: write the database page size into the rollback journal header.
  • Allow the VACUUM command to change the page size of a database file.
  • The xAccess() method of the VFS is allowed to return -1 to signal a memory allocation error.
  • Performance improvement: The OP_IdxDelete opcode uses unpacked records, obviating the need for one OP_MakeRecord opcode call for each index record deleted.
  • Performance improvement: Constant subexpressions are factored out of loops.
  • Performance improvement: Results of OP_Column are reused rather than issuing multiple OP_Column opcodes.
  • Fix a bug in the RTRIM collating sequence.
  • Fix a bug in the SQLITE_SECURE_DELETE option that was causing Firefox crashes. Make arrangements to always test SQLITE_SECURE_DELETE prior to each release.
  • Other miscellaneous performance enhancements.
  • Other miscellaneous minor bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.5.9 On 2008 May 14 (3.5.9)

  • Added experimental support for the journal_mode PRAGMA and persistent journal.
  • Journal mode PERSIST is the default behavior in exclusive locking mode.
  • Fix a performance regression on LEFT JOIN (see ticket #3015) that was mistakenly introduced in version 3.5.8.
  • Performance enhancement: Reengineer the internal routines used to interpret and render variable-length integers.
  • Fix a buffer-overrun problem in sqlite3_mprintf() which occurs when a string without a zero-terminator is passed to "%.*s".
  • Always convert IEEE floating point NaN values into NULL during processing. (Ticket #3060)
  • Make sure that when a connection blocks on a RESERVED lock that it is able to continue after the lock is released. (Ticket #3093)
  • The "configure" scripts should now automatically configure Unix systems for large file support. Improved error messages for when large files are encountered and large file support is disabled.
  • Avoid cache pages leaks following disk-full or I/O errors
  • And, many more minor bug fixes and performance enhancements....

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.0 On 2008 July 16 (3.6.0 beta)

  • Modifications to the virtual file system interface to support a wider range of embedded systems. See 35to36.html for additional information. *** Potentially incompatible change ***
  • All C-preprocessor macros used to control compile-time options now begin with the prefix "SQLITE_". This may require changes to applications that compile SQLite using their own makefiles and with custom compile-time options, hence we mark this as a *** Potentially incompatible change ***
  • The SQLITE_MUTEX_APPDEF compile-time option is no longer supported. Alternative mutex implementations can now be added at run-time using the sqlite3_config() interface with the SQLITE_CONFIG_MUTEX verb. *** Potentially incompatible change ***
  • The handling of IN and NOT IN operators that contain a NULL on their right-hand side expression is brought into compliance with the SQL standard and with other SQL database engines. This is a bug fix, but as it has the potential to break legacy applications that depend on the older buggy behavior, we mark that as a *** Potentially incompatible change ***
  • The result column names generated for compound subqueries have been simplified to show only the name of the column of the original table and omit the table name. This makes SQLite operate more like other SQL database engines.
  • Added the sqlite3_config() interface for doing run-time configuration of the entire SQLite library.
  • Added the sqlite3_status() interface used for querying run-time status information about the overall SQLite library and its subsystems.
  • Added the sqlite3_initialize() and sqlite3_shutdown() interfaces.
  • The SQLITE_OPEN_NOMUTEX option was added to sqlite3_open_v2().
  • Added the PRAGMA page_count command.
  • Added the sqlite3_next_stmt() interface.
  • Added a new R*Tree virtual table

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.1 On 2008 Aug 6 (3.6.1)

  • Added the lookaside memory allocator for a speed improvement in excess of 15% on some workloads. (Your mileage may vary.)
  • Added the SQLITE_CONFIG_LOOKASIDE verb to sqlite3_config() to control the default lookaside configuration.
  • Added verbs SQLITE_STATUS_PAGECACHE_SIZE and SQLITE_STATUS_SCRATCH_SIZE to the sqlite3_status() interface.
  • Modified SQLITE_CONFIG_PAGECACHE and SQLITE_CONFIG_SCRATCH to remove the "+4" magic number in the buffer size computation.
  • Added the sqlite3_db_config() and sqlite3_db_status() interfaces for controlling and monitoring the lookaside allocator separately on each database connection.
  • Numerous other performance enhancements
  • Miscellaneous minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.2 On 2008 Aug 30 (3.6.2)

  • Split the pager subsystem into separate pager and pcache subsystems.
  • Factor out identifier resolution procedures into separate files.
  • Bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.3 On 2008 Sep 22 (3.6.3)

  • Fix for a bug in the SELECT DISTINCT logic that was introduced by the prior version.
  • Other minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.4 On 2008 Oct 15 (3.6.4)

  • Add option support for LIMIT and ORDER BY clauses on DELETE and UPDATE statements. Only works if SQLite is compiled with SQLITE_ENABLE_UPDATE_DELETE_LIMIT.
  • Added the sqlite3_stmt_status() interface for performance monitoring.
  • Add the INDEXED BY clause.
  • The LOCKING_STYLE extension is now enabled by default on Mac OS X
  • Added the TRUNCATE option to PRAGMA journal_mode
  • Performance enhancements to tree balancing logic in the B-Tree layer.
  • Added the source code and documentation for the genfkey program for automatically generating triggers to enforce foreign key constraints.
  • Added the SQLITE_OMIT_TRUNCATE_OPTIMIZATION compile-time option.
  • The SQL language documentation is converted to use syntax diagrams instead of BNF.
  • Other minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.5 On 2008 Nov 12 (3.6.5)

  • Add the MEMORY option to the journal_mode pragma.
  • Added the sqlite3_db_mutex() interface.
  • Added the SQLITE_OMIT_TRUNCATE_OPTIMIZATION compile-time option.
  • Fixed the truncate optimization so that sqlite3_changes() and sqlite3_total_changes() interfaces and the count_changes pragma return the correct values.
  • Added the sqlite3_extended_errcode() interface.
  • The COMMIT command now succeeds even if there are pending queries. It returns SQLITE_BUSY if there are pending incremental BLOB I/O requests.
  • The error code is changed to SQLITE_BUSY (instead of SQLITE_ERROR) when an attempt is made to ROLLBACK while one or more queries are still pending.
  • Drop all support for the experimental memory allocators memsys4 and memsys6.
  • Added the SQLITE_ZERO_MALLOC compile-time option.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.6 On 2008 Nov 19 (3.6.6)

  • Fix a #define that prevented memsys5 from compiling
  • Fix a problem in the virtual table commit mechanism that was causing a crash in FTS3. Ticket #3497.
  • Add the application-defined page cache
  • Added built-in support for VxWorks

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.6.1 On 2008 Nov 22 (3.6.6.1)

  • Fix a bug in the page cache that can lead database corruption following a rollback. This bug was first introduced in version 3.6.4.
  • Two other very minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.6.2 On 2008 Nov 26 (3.6.6.2)

  • Fix a bug in the b-tree delete algorithm that seems like it might be able to cause database corruption. The bug was first introduced in version 3.6.6 by check-in [5899] on 2008-11-13.
  • Fix a memory leak that can occur following a disk I/O error.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.7 On 2008 Dec 16 (3.6.7)

  • Reorganize the Unix interface in os_unix.c
  • Added support for "Proxy Locking" on Mac OS X.
  • Changed the prototype of the sqlite3_auto_extension() interface in a way that is backwards compatible but which might cause warnings in new builds of applications that use that interface.
  • Changed the signature of the xDlSym method of the sqlite3_vfs object in a way that is backwards compatible but which might cause compiler warnings.
  • Added superfluous casts and variable initializations in order to suppress nuisance compiler warnings.
  • Fixes for various minor bugs.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.8 On 2009 Jan 12 (3.6.8)

  • Added support for nested transactions
  • Enhanced the query optimizer so that it is able to use multiple indices to efficiently process OR-connected constraints in a WHERE clause.
  • Added support for parentheses in FTS3 query patterns using the SQLITE_ENABLE_FTS3_PARENTHESIS compile-time option.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.9 On 2009 Jan 14 (3.6.9)

  • Fix two bugs, which when combined might result in incorrect query results. Both bugs were harmless by themselves; only when they team up do they cause problems. Ticket #3581.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.10 On 2009 Jan 15 (3.6.10)

  • Fix a cache coherency problem that could lead to database corruption. Ticket #3584.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.11 On 2009 Feb 18 (3.6.11)

  • Added the hot-backup interface.
  • Added new commands ".backup" and ".restore" to the CLI.
  • Added new methods backup and restore to the TCL interface.
  • Improvements to the syntax bubble diagrams
  • Various minor bug fixes

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.12 On 2009 March 31 (3.6.12)

  • Fixed a bug that caused database corruption when an incremental_vacuum is rolled back in an in-memory database. Ticket #3761.
  • Added the sqlite3_unlock_notify() interface.
  • Added the reverse_unordered_selects pragma.
  • The default page size on windows is automatically adjusted to match the capabilities of the underlying filesystem.
  • Add the new ".genfkey" command in the CLI for generating triggers to implement foreign key constraints.
  • Performance improvements for "count(*)" queries.
  • Reduce the amount of heap memory used, especially by TRIGGERs.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.13 On 2009 April 13 (3.6.13)

  • Fix a bug in version 3.6.12 that causes a segfault when running a count(*) on the sqlite_master table of an empty database. Ticket #3774.
  • Fix a bug in version 3.6.12 that causes a segfault that when inserting into a table using a DEFAULT value where there is a function as part of the DEFAULT value expression. Ticket #3791.
  • Fix data structure alignment issues on Sparc. Ticket #3777.
  • Other minor bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.14 On 2009 May 7 (3.6.14)

  • Added the optional asynchronous VFS module.
  • Enhanced the query optimizer so that virtual tables are able to make use of OR and IN operators in the WHERE clause.
  • Speed improvements in the btree and pager layers.
  • Added the SQLITE_HAVE_ISNAN compile-time option which will cause the isnan() function from the standard math library to be used instead of SQLite's own home-brew NaN checker.
  • Countless minor bug fixes, documentation improvements, new and improved test cases, and code simplifications and cleanups.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.14.1 On 2009 May 19 (3.6.14.1)

  • Fix a bug in group_concat(), ticket #3841
  • Fix a performance bug in the pager cache, ticket #3844
  • Fix a bug in the sqlite3_backup implementation that can lead to a corrupt backup database. Ticket #3858.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.14.2 On 2009 May 25 (3.6.14.2)

  • Fix a code generator bug introduced in version 3.6.14. This bug can cause incorrect query results under obscure circumstances. Ticket #3879.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.15 On 2009 June 15 (3.6.15)

  • Refactor the internal representation of SQL expressions so that they use less memory on embedded platforms.
  • Reduce the amount of stack space used
  • Fix an 64-bit alignment bug on HP/UX and Sparc
  • The sqlite3_create_function() family of interfaces now return SQLITE_MISUSE instead of SQLITE_ERROR when passed invalid parameter combinations.
  • When new tables are created using CREATE TABLE ... AS SELECT ... the datatype of the columns is the simplified SQLite datatype (TEXT, INT, REAL, NUMERIC, or BLOB) instead of a copy of the original datatype from the source table.
  • Resolve race conditions when checking for a hot rollback journal.
  • The sqlite3_shutdown() interface frees all mutexes under windows.
  • Enhanced robustness against corrupt database files
  • Continuing improvements to the test suite and fixes to obscure bugs and inconsistencies that the test suite improvements are uncovering.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.16 On 2009 June 27 (3.6.16)

  • Fix a bug (ticket #3929) that occasionally causes INSERT or UPDATE operations to fail on an indexed table that has a self-modifying trigger.
  • Other minor bug fixes and performance optimizations.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.16.1 On 2009 Oct 30 (3.6.16.1)

  • A small patch to version 3.6.16 to fix the OP_If bug.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.17 On 2009 Aug 10 (3.6.17)

  • Expose the sqlite3_strnicmp() interface for use by extensions and applications.
  • Remove the restriction on virtual tables and shared cache mode. Virtual tables and shared cache can now be used at the same time.
  • Many code simplifications and obscure bug fixes in support of providing 100% branch test coverage.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.18 On 2009 Sep 11 (3.6.18)

  • Versioning of the SQLite source code has transitioned from CVS to Fossil.
  • Query planner enhancements.
  • The SQLITE_ENABLE_STAT2 compile-time option causes the ANALYZE command to collect a small histogram of each index, to help SQLite better select among competing range query indices.
  • Recursive triggers can be enabled using the PRAGMA recursive_triggers statement.
  • Delete triggers fire when rows are removed due to a REPLACE conflict resolution. This feature is only enabled when recursive triggers are enabled.
  • Added the SQLITE_OPEN_SHAREDCACHE and SQLITE_OPEN_PRIVATECACHE flags for sqlite3_open_v2() used to override the global shared cache mode settings for individual database connections.
  • Added improved version identification features: C-Preprocessor macro SQLITE_SOURCE_ID, C/C++ interface sqlite3_sourceid(), and SQL function sqlite_source_id().
  • Obscure bug fix on triggers ([efc02f9779]).

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.19 On 2009 Oct 14 (3.6.19)

  • Added support for foreign key constraints. Foreign key constraints are disabled by default. Use the foreign_keys pragma to turn them on.
  • Generalized the IS and IS NOT operators to take arbitrary expressions on their right-hand side.
  • The TCL Interface has been enhanced to use the Non-Recursive Engine (NRE) interface to the TCL interpreter when linked against TCL 8.6 or later.
  • Fix a bug introduced in 3.6.18 that can lead to a segfault when an attempt is made to write on a read-only database.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.20 On 2009 Nov 4 (3.6.20)

  • Optimizer enhancement: prepared statements are automatically re-compiled when a binding on the RHS of a LIKE operator changes or when any range constraint changes under SQLITE_ENABLE_STAT2.
  • Various minor bug fixes and documentation enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.21 On 2009 Dec 07 (3.6.21)

  • The SQL output resulting from sqlite3_trace() is now modified to include the values of bound parameters.
  • Performance optimizations targeting a specific use case from a single high-profile user of SQLite. A 12% reduction in the number of CPU operations is achieved (as measured by Valgrind). Actual performance improvements in practice may vary depending on workload. Changes include:
    • The ifnull() and coalesce() SQL functions are now implemented using in-line VDBE code rather than calling external functions, so that unused arguments need never be evaluated.
    • The substr() SQL function does not bother to measure the length its entire input string if it is only computing a prefix
    • Unnecessary OP_IsNull, OP_Affinity, and OP_MustBeInt VDBE opcodes are suppressed
    • Various code refactorizations for performance
  • The FTS3 extension has undergone a major rework and cleanup. New FTS3 documentation is now available.
  • The SQLITE_SECURE_DELETE compile-time option fixed to make sure that content is deleted even when the truncate optimization applies.
  • Improvements to "dot-command" handling in the Command Line Interface.
  • Other minor bug fixes and documentation enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.22 On 2010 Jan 06 (3.6.22)

  • Fix bugs that can (rarely) lead to incorrect query results when the CAST or OR operators are used in the WHERE clause of a query.
  • Continuing enhancements and improvements to FTS3.
  • Other miscellaneous bug fixes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.23 On 2010 March 09 (3.6.23)

  • Added the secure_delete pragma.
  • Added the sqlite3_compileoption_used() and
    sqlite3_compileoption_get() interfaces as well as the
    compile_options pragma and the sqlite_compileoption_used() and
    sqlite_compileoption_get() SQL functions.
  • Added the sqlite3_log() interface together with the SQLITE_CONFIG_LOG verb to sqlite3_config(). The ".log" command is added to the Command Line Interface.
  • Improvements to FTS3.
  • Improvements and bug-fixes in support for SQLITE_OMIT_FLOATING_POINT.
  • The integrity_check pragma is enhanced to detect out-of-order rowids.
  • The ".genfkey" operator has been removed from the Command Line Interface.
  • Updates to the co-hosted Lemon LALR(1) parser generator. (These updates did not affect SQLite.)
  • Various minor bug fixes and performance enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.6.23.1 On 2010 March 30 (3.6.23.1)

  • Fix a bug in the offsets() function of FTS3
  • Fix a missing "sync" that when omitted could lead to database corruption if a power failure or OS crash occurred just as a ROLLBACK operation was finishing.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.0 On 2010 July 22 (3.7.0)

  • Added support for write-ahead logging.
  • Query planner enhancement - automatic transient indices are created when doing so reduces the estimated query time.
  • Query planner enhancement - the ORDER BY becomes a no-op if the query also contains a GROUP BY clause that forces the correct output order.
  • Add the SQLITE_DBSTATUS_CACHE_USED verb for sqlite3_db_status().
  • The logical database size is now stored in the database header so that bytes can be appended to the end of the database file without corrupting it and so that SQLite will work correctly on systems that lack support for ftruncate().

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.0.1 On 2010 August 04 (3.7.0.1)

  • Fix a potential database corruption bug that can occur if version 3.7.0 and version 3.6.23.1 alternately write to the same database file. Ticket [51ae9cad317a1]
  • Fix a performance regression related to the query planner enhancements of version 3.7.0.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.1 On 2010 August 23 (3.7.1)

  • Added new commands SQLITE_DBSTATUS_SCHEMA_USED and SQLITE_DBSTATUS_STMT_USED to the sqlite3_db_status() interface, in order to report out the amount of memory used to hold the schema and prepared statements of a connection.
  • Increase the maximum size of a database pages from 32KiB to 64KiB.
  • Use the LIKE optimization even if the right-hand side string contains no wildcards.
  • Added the SQLITE_FCNTL_CHUNK_SIZE verb to the sqlite3_file_control() interface for both unix and windows, to cause database files to grow in large chunks in order to reduce disk fragmentation.
  • Fixed a bug in the query planner that caused performance regressions relative to 3.6.23.1 on some complex joins.
  • Fixed a typo in the OS/2 backend.
  • Refactored the pager module.
  • The SQLITE_MAX_PAGE_SIZE compile-time option is now silently ignored. The maximum page size is hard-coded at 65536 bytes.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.2 On 2010 August 24 (3.7.2)

  • Fix an old and very obscure bug that can lead to corruption of the database free-page list when incremental_vacuum is used.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.3 On 2010 October 08 (3.7.3)

  • Added the sqlite3_create_function_v2() interface that includes a destructor callback.
  • Added support for custom r-tree queries using application-supplied callback routines to define the boundary of the query region.
  • The default page cache strives more diligently to avoid using memory beyond what is allocated to it by SQLITE_CONFIG_PAGECACHE. Or if using page cache is allocating from the heap, it strives to avoid going over the sqlite3_soft_heap_limit64(), even if SQLITE_ENABLE_MEMORY_MANAGEMENT is not set.
  • Added the sqlite3_soft_heap_limit64() interface as a replacement for sqlite3_soft_heap_limit().
  • The ANALYZE command now gathers statistics on tables even if they have no indices.
  • Tweaks to the query planner to help it do a better job of finding the most efficient query plan for each query.
  • Enhanced the internal text-to-numeric conversion routines so that they work with UTF8 or UTF16, thereby avoiding some UTF16-to-UTF8 text conversions.
  • Fix a problem that was causing excess memory usage with large WAL transactions in win32 systems.
  • The interface between the VDBE and B-Tree layer is enhanced such that the VDBE provides hints to the B-Tree layer letting the B-Tree layer know when it is safe to use hashing instead of B-Trees for transient tables.
  • Miscellaneous documentation enhancements.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.4 On 2010 December 08 (3.7.4)

  • Added the sqlite3_blob_reopen() interface to allow an existing sqlite3_blob object to be rebound to a new row.
  • Use the new sqlite3_blob_reopen() interface to improve the performance of FTS.
  • VFSes that do not support shared memory are allowed to access WAL databases if PRAGMA locking_mode is set to EXCLUSIVE.
  • Enhancements to EXPLAIN QUERY PLAN.
  • Added the sqlite3_stmt_readonly() interface.
  • Added PRAGMA checkpoint_fullfsync.
  • Added the SQLITE_FCNTL_FILE_POINTER option to sqlite3_file_control().
  • Added support for FTS4 and enhancements to the FTS matchinfo() function.
  • Added the test_superlock.c module which provides example code for obtaining an exclusive lock to a rollback or WAL database.
  • Added the test_multiplex.c module which provides an example VFS that provides multiplexing (sharding) of a DB, splitting it over multiple files of fixed size.
  • A very obscure bug associated with the or optimization was fixed.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.5 On 2011 February 01 (3.7.5)

  • Added the sqlite3_vsnprintf() interface.
  • Added the SQLITE_DBSTATUS_LOOKASIDE_HIT, SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE, and SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL options for the sqlite3_db_status() interface.
  • Added the SQLITE_OMIT_AUTORESET compile-time option.
  • Added the SQLITE_DEFAULT_FOREIGN_KEYS compile-time option.
  • Updates to sqlite3_stmt_readonly() so that its result is well-defined for all prepared statements and so that it works with VACUUM.
  • Added the "-heap" option to the command-line shell
  • Fix a bug involving frequent changes in and out of WAL mode and VACUUM that could (in theory) cause database corruption.
  • Enhance the sqlite3_trace() mechanism so that nested SQL statements such as might be generated by virtual tables are shown but are shown in comments and without parameter expansion. This greatly improves tracing output when using the FTS3/4 and/or RTREE virtual tables.
  • Change the xFileControl() methods on all built-in VFSes to return SQLITE_NOTFOUND instead of SQLITE_ERROR for an unrecognized operation code.
  • The SQLite core invokes the SQLITE_FCNTL_SYNC_OMITTED file control to the VFS in place of a call to xSync if the database has PRAGMA synchronous set to OFF.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.6 On 2011 April 12 (3.7.6)

  • Added the sqlite3_wal_checkpoint_v2() interface and enhanced the wal_checkpoint pragma to support blocking checkpoints.
  • Improvements to the query planner so that it makes better estimates of plan costs and hence does a better job of choosing the right plan, especially when SQLITE_ENABLE_STAT2 is used.
  • Fix a bug which prevented deferred foreign key constraints from being enforced when sqlite3_finalize() was not called by one statement with a failed foreign key constraint prior to another statement with foreign key constraints running.
  • Integer arithmetic operations that would have resulted in overflow are now performed using floating-point instead.
  • Increased the version number on the VFS object to 3 and added new methods xSetSysCall, xGetSysCall, and xNextSysCall used for doing full-coverage testing.
  • Increase the maximum value of SQLITE_MAX_ATTACHED from 30 to 62 (though the default value remains at 10).
  • Enhancements to FTS4:
    1. Added the fts4aux table
    2. Added support for compressed FTS4 content
  • Enhance the ANALYZE command to support the name of an index as its argument, in order to analyze just that one index.
  • Added the "unix-excl" built-in VFS on unix and unix-like platforms.
  • SQLITE_SOURCE_ID: "2011-04-12 01:58:40 f9d43fa363d54beab6f45db005abac0a7c0c47a7"
  • SHA1 for sqlite3.c: f38df08547efae0ff4343da607b723f588bbd66b

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.6.1 On 2011 April 14 (3.7.6.1)

  • Fix a bug in 3.7.6 that only appears if the SQLITE_FCNTL_SIZE_HINT file control is used with a build of SQLite that makes use of the HAVE_POSIX_FALLOCATE compile-time option and which has SQLITE_ENABLE_LOCKING_MODE turned off.
  • SQLITE_SOURCE_ID: "2011-04-13 14:40:25 a35e83eac7b185f4d363d7fa51677f2fdfa27695"
  • SHA1 for sqlite3.c: b81bfa27d3e09caf3251475863b1ce6dd9f6ab66

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.6.2 On 2011 April 17 (3.7.6.2)

  • Fix the function prototype for the open(2) system call to agree with POSIX. Without this fix, pthreads does not work correctly on NetBSD.
  • SQLITE_SOURCE_ID: "2011-04-17 17:25:17 154ddbc17120be2915eb03edc52af1225eb7cb5e"
  • SHA1 for sqlite3.c: 806577fd524dd5f3bfd8d4d27392ed2752bc9701

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.6.3 On 2011 May 19 (3.7.6.3)

  • Fix a problem with WAL mode which could cause transactions to silently rollback if the cache_size is set very small (less than 10) and SQLite comes under memory pressure.

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.7 On 2011 June 24 (3.7.7)

  • Add support for URI filenames
  • Add the sqlite3_vtab_config() interface in support of ON CONFLICT clauses with virtual tables.
  • Add the xSavepoint, xRelease and xRollbackTo methods in virtual tables in support of SAVEPOINT for virtual tables.
  • Update the built-in FTS3/FTS4 and RTREE virtual tables to support ON CONFLICT clauses and REPLACE.
  • Avoid unnecessary reparsing of the database schema.
  • Added support for the FTS4 prefix option and the FTS4 order option.
  • Allow WAL-mode databases to be opened read-only as long as there is an existing read/write connection.
  • Added support for short filenames.
  • SQLITE_SOURCE_ID: "2011-06-23 19:49:22 4374b7e83ea0a3fbc3691f9c0c936272862f32f2"
  • SHA1 for sqlite3.c: 5bbe79e206ae5ffeeca760dbd0d66862228db551

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.7.1 On 2011 June 28 (3.7.7.1)

  • Fix a bug causing PRAGMA case_sensitive_like statements compiled using sqlite3_prepare() to fail with an SQLITE_SCHEMA error.
  • SQLITE_SOURCE_ID: "2011-06-28 17:39:05 af0d91adf497f5f36ec3813f04235a6e195a605f"
  • SHA1 for sqlite3.c: d47594b8a02f6cf58e91fb673e96cb1b397aace0

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.8 On 2011 September 19 (3.7.8)

  • Orders of magnitude performance improvement for CREATE INDEX on very large tables.
  • Improved the windows VFS to better defend against interference from anti-virus software.
  • Improved query plan optimization when the DISTINCT keyword is present.
  • Allow more system calls to be overridden in the unix VFS - to provide better support for chromium sandboxes.
  • Increase the default size of a lookahead cache line from 100 to 128 bytes.
  • Enhancements to the test_quota.c module so that it can track preexisting files.
  • Bug fix: Virtual tables now handle IS NOT NULL constraints correctly.
  • Bug fixes: Correctly handle nested correlated subqueries used with indices in a WHERE clause.
  • SQLITE_SOURCE_ID: "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177"
  • SHA1 for sqlite3.c: bfcd74a655636b592c5dba6d0d5729c0f8e3b4de

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


SQLite Release 3.7.9 On 2011 November 1 (3.7.9)

  • If a search token (on the right-hand side of the MATCH operator) in FTS4 begins with "^" then that token must be the first in its field of the document. ** Potentially Incompatible Change **
  • Added options SQLITE_DBSTATUS_CACHE_HIT and SQLITE_DBSTATUS_CACHE_MISS to the sqlite3_db_status() interface.
  • Removed support for SQLITE_ENABLE_STAT2, replacing it with the much more capable SQLITE_ENABLE_STAT3 option.
  • Enhancements to the sqlite3_analyzer utility program, including the --pageinfo and --stats options and support for multiplexed databases.
  • Enhance the sqlite3_data_count() interface so that it can be used to determine if SQLITE_DONE has been seen on the prepared statement.
  • Added the SQLITE_FCNTL_OVERWRITE file-control by which the SQLite core indicates to the VFS that the current transaction will overwrite the entire database file.
  • Increase the default lookaside memory allocator allocation size from 100 to 128 bytes.
  • Enhanced the query planner so that it can factor terms in and out of OR expressions in the WHERE clause in an effort to find better indices.
  • Added the SQLITE_DIRECT_OVERFLOW_READ compile-time option, causing overflow pages to be read directly from the database file, bypassing the page cache.
  • Remove limits on the magnitude of precision and width value in the format specifiers of the sqlite3_mprintf() family of string rendering routines.
  • Fix a bug that prevent ALTER TABLE ... RENAME from working on some virtual tables in a database with a UTF16 encoding.
  • Fix a bug in ASCII-to-float conversion that causes slow performance and incorrect results when converting numbers with ridiculously large exponents.
  • Fix a bug that causes incorrect results in aggregate queries that use multiple aggregate functions whose arguments contain complicated expressions that differ only in the case of string literals contained within those expressions.
  • Fix a bug that prevented the page_count and quick_check pragmas from working correctly if their names were capitalized.
  • Fix a bug that caused VACUUM to fail if the count_changes pragma was engaged.
  • Fix a bug in virtual table implementation that causes a crash if an FTS4 table is dropped inside a transaction and a SAVEPOINT occurs afterwards.
  • SQLITE_SOURCE_ID: "2011-11-01 00:52:41 c7c6050ef060877ebe77b41d959e9df13f8c9b5e"
  • SHA1 for sqlite3.c: becd16877f4f9b281b91c97e106089497d71bb47

A complete list of SQLite releases in a single page is also available. A detailed history of every check-in is available at http://www.sqlite.org/src/timeline.


List Of SQLite Constants

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Constants:

      Other lists: Objects and Functions.


List Of SQLite Functions

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Functions:

        Other lists: Constants and Objects.


Introduction

Choose any three.
About Sitemap Documentation Download License News Support

These pages define the C-language interface for the SQLite session module. This is not a tutorial. These pages are designed to be precise, not easy to read. Unfortunately, there is currently no tutorial introduction to the session module.

This version of the C-language interface reference is broken down into small pages for easy viewing. The same content is also available as a single large HTML file for those who prefer that format.

The content on these pages is extracted from comments in the source code.

The interface is broken down into three categories:

  1. List Of Objects. This is a list of the two abstract objects used by the SQLite session module.

  2. List Of Constants. This is a list of numeric constants used by the SQLite session module and represented by #defines in the sqlite3session.h header file. There are constants passed to conflict handler callbacks to indicate the type of conflict, and constants returned by the conflict handler to indicate how the conflict should be resolved.

  3. List Of Functions. This is a list of all SQLite session module functions.


List Of SQLite Objects

Choose any three.
About Sitemap Documentation Download License News Support

SQLite C Interface

Objects:

        Other lists: Constants and Functions.