diff options
Diffstat (limited to 'ext/sqlite3/libsqlite/sqlite3.h')
| -rw-r--r-- | ext/sqlite3/libsqlite/sqlite3.h | 240 |
1 files changed, 135 insertions, 105 deletions
diff --git a/ext/sqlite3/libsqlite/sqlite3.h b/ext/sqlite3/libsqlite/sqlite3.h index 9c3e00babd..d56dd07cb0 100644 --- a/ext/sqlite3/libsqlite/sqlite3.h +++ b/ext/sqlite3/libsqlite/sqlite3.h @@ -99,8 +99,8 @@ extern "C" { ** ** Requirements: [H10011] [H10014] */ -#define SQLITE_VERSION "3.6.13" -#define SQLITE_VERSION_NUMBER 3006013 +#define SQLITE_VERSION "3.6.14" +#define SQLITE_VERSION_NUMBER 3006014 /* ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100> @@ -791,6 +791,11 @@ struct sqlite3_vfs { ** 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 calls to sqlite3_shutdown() are harmless no-ops. +** ** Among other things, sqlite3_initialize() shall invoke ** sqlite3_os_init(). Similarly, sqlite3_shutdown() ** shall invoke sqlite3_os_end(). @@ -1218,14 +1223,18 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); ** triggers are not counted. Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** +** 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 +** 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 +** ends with the script of a [CREATE TRIGGER | 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 @@ -1247,16 +1256,8 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); ** However, the number returned does not include changes ** caused by subtriggers since those have their own context. ** -** SQLite implements the command "DELETE FROM table" without a WHERE clause -** by dropping and recreating the table. Doing so is much faster than going -** through and deleting individual elements from the table. Because of this -** optimization, the deletions in "DELETE FROM table" are not row changes and -** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] -** functions, regardless of the number of elements that were originally -** in the table. To get an accurate count of the number of rows deleted, use -** "DELETE FROM table WHERE 1" instead. Or recompile using the -** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the -** optimization on all queries. +** See also the [sqlite3_total_changes()] interface and the +** [count_changes pragma]. ** ** Requirements: ** [H12241] [H12243] @@ -1270,27 +1271,21 @@ int sqlite3_changes(sqlite3*); /* ** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600> ** -** This function returns the number of row changes caused by INSERT, -** UPDATE or DELETE statements since the [database connection] was opened. -** The count includes all changes from all trigger contexts. However, -** the count does not include changes used to implement REPLACE constraints, -** do rollbacks or ABORT processing, or DROP table processing. +** This function returns the number of row changes caused by [INSERT], +** [UPDATE] or [DELETE] statements since the [database connection] was opened. +** The count includes all changes from all +** [CREATE TRIGGER | trigger] contexts. 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 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 changes are counted as soon as the statement that makes them is ** completed (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** -** SQLite implements the command "DELETE FROM table" without a WHERE clause -** by dropping and recreating the table. (This is much faster than going -** through and deleting individual elements from the table.) Because of this -** optimization, the deletions in "DELETE FROM table" are not row changes and -** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] -** functions, regardless of the number of elements that were originally -** in the table. To get an accurate count of the number of rows deleted, use -** "DELETE FROM table WHERE 1" instead. Or recompile using the -** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the -** optimization on all queries. -** -** See also the [sqlite3_changes()] interface. +** See also the [sqlite3_changes()] interface and the +** [count_changes pragma]. ** ** Requirements: ** [H12261] [H12263] @@ -1324,8 +1319,16 @@ int sqlite3_total_changes(sqlite3*); ** that is inside an explicit transaction, then the entire transaction ** will be rolled back automatically. ** -** A call to sqlite3_interrupt() has no effect on SQL statements -** that are started after sqlite3_interrupt() returns. +** 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. ** ** Requirements: ** [H12271] [H12272] @@ -1338,20 +1341,30 @@ void sqlite3_interrupt(sqlite3*); /* ** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200> ** -** These routines are useful for command-line input to determine if the -** currently entered text seems to form complete a SQL statement or +** 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 true if the input string +** 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 fragment of a -** CREATE TRIGGER statement. Semicolons that are embedded within +** 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. +** 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. +** ** Requirements: [H10511] [H10512] ** ** The input to [sqlite3_complete()] must be a zero-terminated @@ -1779,13 +1792,7 @@ void sqlite3_randomness(int N, void *P); ** 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. If the authorizer 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. +** 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 @@ -1794,6 +1801,17 @@ void sqlite3_randomness(int N, void *P); ** 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 [sqlite3_prepare | 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 @@ -1827,7 +1845,9 @@ void sqlite3_randomness(int N, void *P); ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not -** performed during statement evaluation in [sqlite3_step()]. +** 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. ** ** Requirements: ** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510] @@ -3483,12 +3503,14 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n); ** the name is passed as the second function argument. ** ** The third argument may be one of the constants [SQLITE_UTF8], -** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied +** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied ** routine expects to be passed pointers to strings encoded using UTF-8, ** UTF-16 little-endian, or UTF-16 big-endian, respectively. The -** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that +** third argument might also be [SQLITE_UTF16] to indicate that the routine +** expects pointers to be UTF-16 strings in the native byte order, or the +** argument can be [SQLITE_UTF16_ALIGNED] if the ** the routine expects pointers to 16-bit word aligned strings -** of UTF-16 in the native byte order of the host computer. +** of UTF-16 in the native byte order. ** ** A pointer to the user supplied routine must be passed as the fifth ** argument. If it is NULL, this is the same as deleting the collation @@ -3513,6 +3535,8 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n); ** collation creation functions or when the [database connection] is closed ** using [sqlite3_close()]. ** +** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. +** ** Requirements: ** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621] ** [H16624] [H16627] [H16630] @@ -4066,15 +4090,20 @@ typedef struct sqlite3_module sqlite3_module; /* ** CAPI3REF: Virtual Table Object {H18000} <S20400> -** KEYWORDS: sqlite3_module +** KEYWORDS: sqlite3_module {virtual table module} ** EXPERIMENTAL ** -** A module is a class of virtual tables. Each module is defined -** by an instance of the following structure. This structure consists -** mostly of methods for the module. +** This structure, sometimes called a a "virtual table module", +** defines the implementation of a [virtual tables]. +** This structure consists mostly of methods for the module. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** 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. */ struct sqlite3_module { int iVersion; @@ -4112,8 +4141,8 @@ struct sqlite3_module { ** EXPERIMENTAL ** ** The sqlite3_index_info structure and its substructures is used to -** pass information into and receive the reply from the xBestIndex -** method of an sqlite3_module. The fields under **Inputs** are the +** 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. ** @@ -4136,17 +4165,19 @@ struct sqlite3_module { ** 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 +** 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 xFilter. -** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. +** The idxNum and idxPtr values are recorded and passed into the +** [xFilter] method. +** [sqlite3_free()] is used to free idxPtr if and only iff +** needToFreeIdxPtr is true. ** -** The orderByConsumed means that output from xFilter will occur in +** 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. ** @@ -4154,9 +4185,6 @@ struct sqlite3_module { ** 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). -** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. */ struct sqlite3_index_info { /* Inputs */ @@ -4194,34 +4222,44 @@ struct sqlite3_index_info { ** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400> ** EXPERIMENTAL ** -** This routine is used to register a new module name with a -** [database connection]. Module names must be registered before -** creating new virtual tables on the module, or before using -** preexisting virtual tables of the module. +** This routine is used to register a new [virtual table module] name. +** Module names must be registered before +** creating a new [virtual table] using the module, or 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. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** This interface has exactly the same effect as calling +** [sqlite3_create_module_v2()] with a NULL client data destructor. */ SQLITE_EXPERIMENTAL 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 */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData /* Client data for xCreate/xConnect */ ); /* ** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400> ** EXPERIMENTAL ** -** This routine is identical to the [sqlite3_create_module()] method above, -** except that it allows a destructor function to be specified. It is -** even more experimental than the rest of the virtual tables API. +** This routine is identical to the [sqlite3_create_module()] method, +** except that it has an extra parameter to specify +** a destructor function for the client data pointer. SQLite will +** invoke the destructor function (if it is not NULL) when SQLite +** no longer needs the pClientData pointer. */ SQLITE_EXPERIMENTAL 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 */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData, /* Client data for xCreate/xConnect */ void(*xDestroy)(void*) /* Module destructor function */ ); @@ -4230,8 +4268,9 @@ SQLITE_EXPERIMENTAL int sqlite3_create_module_v2( ** KEYWORDS: sqlite3_vtab ** EXPERIMENTAL ** -** Every module implementation uses a subclass of the following structure -** to describe a particular instance of the module. Each subclass will +** Every [virtual table module] implementation uses a subclass +** of the following structure 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. @@ -4241,13 +4280,7 @@ SQLITE_EXPERIMENTAL int sqlite3_create_module_v2( ** 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. Note -** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field -** since virtual tables are commonly implemented in loadable extensions which -** do not have access to sqlite3MPrintf() or sqlite3Free(). -** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** freed by sqlite3_free() and the zErrMsg field will be zeroed. */ struct sqlite3_vtab { const sqlite3_module *pModule; /* The module for this virtual table */ @@ -4258,20 +4291,21 @@ struct sqlite3_vtab { /* ** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400> -** KEYWORDS: sqlite3_vtab_cursor +** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} ** EXPERIMENTAL ** -** Every module implementation uses a subclass of the following structure -** to describe cursors that point into the virtual table and are used +** 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. Each module implementation will define +** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed +** by the [sqlite3_module.xClose | xClose] method. Cussors 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. -** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. */ struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; /* Virtual table of this cursor */ @@ -4282,21 +4316,20 @@ struct sqlite3_vtab_cursor { ** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400> ** EXPERIMENTAL ** -** The xCreate and xConnect methods of a module use the following API +** 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. -** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. */ -SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); +SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL); /* ** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400> ** EXPERIMENTAL ** ** Virtual tables can provide alternative implementations of functions -** using the xFindFunction method. But global versions of those 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 @@ -4305,10 +4338,7 @@ SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable) ** 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 virtual tables. -** -** This API should be considered part of the virtual table interface, -** which is experimental and subject to change. +** by a [virtual table]. */ SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |