persistent-sqlite 2.8.1 → 2.8.1.1
raw patch · 4 files changed
+478/−147 lines, 4 files
Files
- ChangeLog.md +5/−1
- cbits/sqlite3.c too large to diff
- cbits/sqlite3.h +472/−145
- persistent-sqlite.cabal +1/−1
ChangeLog.md view
@@ -1,3 +1,7 @@+## 2.8.1.1++* Update the vendored SQLite C library from 3.19.3 to 3.22.0. See [the SQLite changelog](https://sqlite.org/changes.html) for details.+ ## 2.8.1 * Updated `SqlBackend` definition to set `connPutManySql`. [#770](https://github.com/yesodweb/persistent/pull/770)@@ -26,7 +30,7 @@ ## 2.6.2.1 -* Update `sqlite` cbit sources to 3.19.3 from 3.12.1+* Update the vendored SQLite C library from 3.12.1 to 3.19.3. See [the SQLite changelog](https://sqlite.org/changes.html) for details. ## 2.6.2
cbits/sqlite3.c view
file too large to diff
cbits/sqlite3.h view
@@ -1,5 +1,5 @@ /*-** 2001 September 15+** 2001-09-15 ** ** The author disclaims copyright to this source code. In place of ** a legal notice, here is a blessing:@@ -115,15 +115,17 @@ ** 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 a SHA1-** or SHA3-256 hash of the entire source tree.+** or SHA3-256 hash of the entire source tree. If the source code has+** been edited in any way since it was last checked in, then the last+** four hexadecimal digits of the hash may be modified. ** ** See also: [sqlite3_libversion()], ** [sqlite3_libversion_number()], [sqlite3_sourceid()], ** [sqlite_version()] and [sqlite_source_id()]. */-#define SQLITE_VERSION "3.19.3"-#define SQLITE_VERSION_NUMBER 3019003-#define SQLITE_SOURCE_ID "2017-06-08 14:26:16 0ee482a1e0eae22e08edc8978c9733a96603d4509645f348ebf55b579e89636b"+#define SQLITE_VERSION "3.22.0"+#define SQLITE_VERSION_NUMBER 3022000+#define SQLITE_SOURCE_ID "2018-01-22 18:45:57 0c55d179733b46d8d0ba4d88e01a25e10677046ee3da1d5b1581e86726f2171d" /* ** CAPI3REF: Run-Time Library Version Numbers@@ -139,7 +141,7 @@ ** ** <blockquote><pre> ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );-** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );+** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 ); ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); ** </pre></blockquote>)^ **@@ -149,9 +151,11 @@ ** 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 +** [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.+** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built+** using an edited copy of [the amalgamation], then the last four characters+** of the hash might be different from [SQLITE_SOURCE_ID].)^ ** ** See also: [sqlite_version()] and [sqlite_source_id()]. */@@ -417,7 +421,7 @@ */ #define SQLITE_OK 0 /* Successful result */ /* beginning-of-error-codes */-#define SQLITE_ERROR 1 /* SQL error or missing database */+#define SQLITE_ERROR 1 /* Generic error */ #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 */@@ -432,7 +436,7 @@ #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_EMPTY 16 /* Internal use only */ #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 */@@ -440,7 +444,7 @@ #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_FORMAT 24 /* Not used */ #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_NOTICE 27 /* Notifications from sqlite3_log() */@@ -466,6 +470,8 @@ ** the most recent error can be obtained using ** [sqlite3_extended_errcode()]. */+#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))+#define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8)) #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))@@ -494,6 +500,9 @@ #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8)) #define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8)) #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))+#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))+#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))+#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8)) #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))@@ -506,6 +515,8 @@ #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))+#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))+#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8)) #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8)) #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))@@ -580,6 +591,11 @@ ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on ** read-only media and cannot be changed even by processes with ** elevated privileges.+**+** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying+** filesystem supports doing multiple write operations atomically when those+** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and+** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. */ #define SQLITE_IOCAP_ATOMIC 0x00000001 #define SQLITE_IOCAP_ATOMIC512 0x00000002@@ -595,6 +611,7 @@ #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 #define SQLITE_IOCAP_IMMUTABLE 0x00002000+#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000 /* ** CAPI3REF: File Locking Levels@@ -729,6 +746,7 @@ ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN] ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE] ** <li> [SQLITE_IOCAP_IMMUTABLE]+** <li> [SQLITE_IOCAP_BATCH_ATOMIC] ** </ul> ** ** The SQLITE_IOCAP_ATOMIC property means that all writes of@@ -1012,6 +1030,40 @@ ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by ** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for ** this opcode. +**+** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]+** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then+** the file descriptor is placed in "batch write mode", which+** means all subsequent write operations will be deferred and done+** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems+** that do not support batch atomic writes will return SQLITE_NOTFOUND.+** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to+** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or+** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make+** no VFS interface calls on the same [sqlite3_file] file descriptor+** except for calls to the xWrite method and the xFileControl method+** with [SQLITE_FCNTL_SIZE_HINT].+**+** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]+** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write+** operations since the previous successful call to +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.+** This file control returns [SQLITE_OK] if and only if the writes were+** all performed successfully and have been committed to persistent storage.+** ^Regardless of whether or not it is successful, this file control takes+** the file descriptor out of batch write mode so that all subsequent+** write operations are independent.+** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without+** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].+**+** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]+** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write+** operations since the previous successful call to +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.+** ^This file control takes the file descriptor out of batch write mode+** so that all subsequent write operations are independent.+** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without+** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]. ** </ul> */ #define SQLITE_FCNTL_LOCKSTATE 1@@ -1043,6 +1095,9 @@ #define SQLITE_FCNTL_JOURNAL_POINTER 28 #define SQLITE_FCNTL_WIN32_GET_HANDLE 29 #define SQLITE_FCNTL_PDB 30+#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31+#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32+#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33 /* deprecated names */ #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE@@ -1080,12 +1135,18 @@ ** in the name of the object stands for "virtual file system". See ** the [VFS | 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 VFS interface is sometimes extended by adding new methods onto+** the end. Each time such an extension occurs, the iVersion field+** is incremented. The iVersion value started out as 1 in+** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2+** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased+** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields+** may be appended to the sqlite3_vfs object and the iVersion value+** may increase again in future versions of SQLite.+** Note that the structure+** of the sqlite3_vfs object changes in the transition from+** SQLite [version 3.5.9] to [version 3.6.0] on [dateof: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@@ -1613,6 +1674,16 @@ ** routines with a wrapper that simulations memory allocation failure or ** tracks memory usage, for example. </dd> **+** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>+** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of+** type int, interpreted as a boolean, which if true provides a hint to+** SQLite that it should avoid large memory allocations if possible.+** SQLite will run faster if it is free to make large memory allocations,+** but some application might prefer to run slower in exchange for+** guarantees about memory fragmentation that are possible if large+** allocations are avoided. This hint is normally off.+** </dd>+** ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt> ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int, ** interpreted as a boolean, which enables or disables the collection of@@ -1630,25 +1701,7 @@ ** </dd> ** ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>-** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer-** that SQLite can use for scratch memory. ^(There are three arguments-** to SQLITE_CONFIG_SCRATCH: 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 first argument must be a pointer to an 8-byte aligned buffer-** of at least sz*N bytes of memory.-** ^SQLite will not use more than one scratch buffers per thread.-** ^SQLite will never request 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.<p>-** ^When the application provides any amount of scratch memory using-** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large-** [sqlite3_malloc|heap allocations].-** This can help [Robson proof|prevent memory allocation failures] due to heap-** fragmentation in low-memory embedded systems.+** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used. ** </dd> ** ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>@@ -1684,8 +1737,7 @@ ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt> ** <dd> ^The SQLITE_CONFIG_HEAP 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].+** beyond those provided for by [SQLITE_CONFIG_PAGECACHE]. ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns ** [SQLITE_ERROR] if invoked otherwise.@@ -1878,7 +1930,7 @@ #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_SCRATCH 6 /* No longer used */ #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 */@@ -1899,6 +1951,7 @@ #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */+#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ /* ** CAPI3REF: Database Connection Configuration Options@@ -2006,7 +2059,26 @@ ** into which is written 0 or 1 to indicate whether checkpoints-on-close ** have been disabled - 0 if they are not disabled, 1 if they are. ** </dd>-**+** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>+** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates+** the [query planner stability guarantee] (QPSG). When the QPSG is active,+** a single SQL query statement will always use the same algorithm regardless+** of values of [bound parameters].)^ The QPSG disables some query optimizations+** that look at the values of bound parameters, which can make some queries+** slower. But the QPSG has the advantage of more predictable behavior. With+** the QPSG active, SQLite will always use the same query plan in the field as+** was used during testing in the lab.+** </dd>+** <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>+** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not +** include output for any operations performed by trigger programs. This+** option is used to set or clear (the default) a flag that governs this+** behavior. The first parameter passed to this operation is an integer -+** non-zero to enable output for trigger programs, or zero to disable it.+** The second parameter is a pointer to an integer into which is written +** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if +** it is not disabled, 1 if it is. +** </dd> ** </dl> */ #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */@@ -2016,7 +2088,9 @@ #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */-+#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */+#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */+#define SQLITE_DBCONFIG_MAX 1008 /* Largest DBCONFIG */ /* ** CAPI3REF: Enable Or Disable Extended Result Codes@@ -2679,7 +2753,8 @@ ** [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+** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],+** and [sqlite3_prepare16_v3()]. ^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@@ -2876,8 +2951,8 @@ ** KEYWORDS: SQLITE_TRACE ** ** These constants identify classes of events that can be monitored-** using the [sqlite3_trace_v2()] tracing logic. The third argument-** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of+** using the [sqlite3_trace_v2()] tracing logic. The M argument+** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of ** the following constants. ^The first argument to the trace callback ** is one of the following constants. **@@ -3086,10 +3161,10 @@ ** ^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+** set in the third 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+** 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.@@ -3468,6 +3543,29 @@ #define SQLITE_LIMIT_TRIGGER_DEPTH 10 #define SQLITE_LIMIT_WORKER_THREADS 11 +/*+** CAPI3REF: Prepare Flags+**+** These constants define various flags that can be passed into+** "prepFlags" parameter of the [sqlite3_prepare_v3()] and+** [sqlite3_prepare16_v3()] interfaces.+**+** New flags may be added in future releases of SQLite.+**+** <dl>+** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>+** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner+** that the prepared statement will be retained for a long time and+** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]+** and [sqlite3_prepare16_v3()] assume that the prepared statement will +** be used just once or at most a few times and then destroyed using+** [sqlite3_finalize()] relatively soon. The current implementation acts+** on this hint by avoiding the use of [lookaside memory] so as not to+** deplete the limited store of lookaside memory. Future versions of+** SQLite may act on this hint differently.+** </dl>+*/+#define SQLITE_PREPARE_PERSISTENT 0x01 /* ** CAPI3REF: Compiling An SQL Statement@@ -3475,17 +3573,29 @@ ** METHOD: sqlite3 ** CONSTRUCTOR: sqlite3_stmt **-** To execute an SQL query, it must first be compiled into a byte-code-** program using one of these routines.+** To execute an SQL statement, it must first be compiled into a byte-code+** program using one of these routines. Or, in other words, these routines+** are constructors for the [prepared statement] object. **+** The preferred routine to use is [sqlite3_prepare_v2()]. The+** [sqlite3_prepare()] interface is legacy and should be avoided.+** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used+** for special purposes.+**+** The use of the UTF-8 interfaces is preferred, as SQLite currently+** does all parsing using UTF-8. The UTF-16 interfaces are provided+** as a convenience. The UTF-16 interfaces work by converting the+** input text into UTF-8, then invoking the corresponding UTF-8 interface.+** ** 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.+** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),+** and sqlite3_prepare_v3()+** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),+** and sqlite3_prepare16_v3() use UTF-16. ** ** ^If the nByte argument is negative, then zSql is read up to the ** first zero terminator. ^If nByte is positive, then it is the@@ -3512,10 +3622,11 @@ ** ^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+** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),+** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.+** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())+** are retained for backwards compatibility, but their use is discouraged.+** ^In the "vX" 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:@@ -3548,6 +3659,12 @@ ** or [GLOB] operator or if the parameter is compared to an indexed column ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. ** </li>+**+** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having+** the extra prepFlags parameter, which is a bit array consisting of zero or+** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The+** sqlite3_prepare_v2() interface works exactly the same as+** sqlite3_prepare_v3() with a zero prepFlags parameter. ** </ol> */ SQLITE_API int sqlite3_prepare(@@ -3564,6 +3681,14 @@ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ );+SQLITE_API int sqlite3_prepare_v3(+ sqlite3 *db, /* Database handle */+ const char *zSql, /* SQL statement, UTF-8 encoded */+ int nByte, /* Maximum length of zSql in bytes. */+ unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */+ sqlite3_stmt **ppStmt, /* OUT: Statement handle */+ const char **pzTail /* OUT: Pointer to unused portion of zSql */+); SQLITE_API int sqlite3_prepare16( sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */@@ -3578,6 +3703,14 @@ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ );+SQLITE_API int sqlite3_prepare16_v3(+ sqlite3 *db, /* Database handle */+ const void *zSql, /* SQL statement, UTF-16 encoded */+ int nByte, /* Maximum length of zSql in bytes. */+ unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */+ sqlite3_stmt **ppStmt, /* OUT: Statement handle */+ const void **pzTail /* OUT: Pointer to unused portion of zSql */+); /* ** CAPI3REF: Retrieving Statement SQL@@ -3585,7 +3718,8 @@ ** ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 ** SQL text used to create [prepared statement] P if P was-** created by either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].+** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],+** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()]. ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 ** string containing the SQL text of prepared statement P with ** [bound parameters] expanded.@@ -3704,8 +3838,9 @@ ** 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()].+** Unprotected sqlite3_value objects may only be used as arguments+** to [sqlite3_result_value()], [sqlite3_bind_value()], and+** [sqlite3_value_dup()]. ** The [sqlite3_value_blob | sqlite3_value_type()] family of ** interfaces require protected sqlite3_value objects. */@@ -3811,6 +3946,15 @@ ** [sqlite3_blob_open | incremental BLOB I/O] routines. ** ^A negative value for the zeroblob results in a zero-length BLOB. **+** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in+** [prepared statement] S to have an SQL value of NULL, but to also be+** associated with the pointer P of type T. ^D is either a NULL pointer or+** a pointer to a destructor function for P. ^SQLite will invoke the+** destructor D with a single argument of P when it is finished using+** P. The T parameter should be a static string, preferably a string+** literal. The sqlite3_bind_pointer() routine is part of the+** [pointer passing interface] added for SQLite 3.20.0.+** ** ^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()],@@ -3844,6 +3988,7 @@ SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, void(*)(void*), unsigned char encoding); SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);+SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); @@ -3887,8 +4032,8 @@ ** ^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()].+** originally specified as UTF-16 in [sqlite3_prepare16()],+** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()]. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and@@ -3905,7 +4050,8 @@ ** parameter to [sqlite3_bind_blob|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()].+** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or+** [sqlite3_prepare16_v3()]. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and@@ -4059,16 +4205,18 @@ ** CAPI3REF: Evaluate An SQL Statement ** METHOD: sqlite3_stmt **-** After a [prepared statement] has been prepared using either-** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy+** After a [prepared statement] has been prepared using any of+** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],+** or [sqlite3_prepare16_v3()] 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+** on whether the statement was prepared using the newer "vX" interfaces+** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],+** [sqlite3_prepare16_v2()] or the older legacy+** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the+** new "vX" 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],@@ -4129,10 +4277,11 @@ ** 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+** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]+** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] 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.+** by sqlite3_step(). The use of the "vX" interfaces is recommended. */ SQLITE_API int sqlite3_step(sqlite3_stmt*); @@ -4194,6 +4343,28 @@ ** KEYWORDS: {column access functions} ** METHOD: sqlite3_stmt **+** <b>Summary:</b>+** <blockquote><table border=0 cellpadding=0 cellspacing=0>+** <tr><td><b>sqlite3_column_blob</b><td>→<td>BLOB result+** <tr><td><b>sqlite3_column_double</b><td>→<td>REAL result+** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result+** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result+** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result+** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result+** <tr><td><b>sqlite3_column_value</b><td>→<td>The result as an +** [sqlite3_value|unprotected sqlite3_value] object.+** <tr><td> <td> <td> +** <tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB+** or a UTF-8 TEXT result in bytes+** <tr><td><b>sqlite3_column_bytes16 </b>+** <td>→ <td>Size of UTF-16+** TEXT in bytes+** <tr><td><b>sqlite3_column_type</b><td>→<td>Default+** datatype of the result+** </table></blockquote>+**+** <b>Details:</b>+** ** ^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*]@@ -4215,16 +4386,29 @@ ** are called from a different thread while any of these routines ** are pending, then the results are undefined. **+** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)+** each return the value of a result column in a specific data format. If+** the result column is not initially in the requested format (for example,+** if the query returns an integer but the sqlite3_column_text() interface+** is used to extract the value) then an automatic type conversion is performed.+** ** ^The sqlite3_column_type() routine returns the ** [SQLITE_INTEGER | 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+** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].+** The return value of sqlite3_column_type() can be used to decide which+** of the first six interface should be used to extract the column value.+** The value returned by sqlite3_column_type() is only meaningful if no+** automatic type conversions have occurred for the value in question. +** After a type conversion, the result of calling sqlite3_column_type()+** is undefined, though harmless. Future ** versions of SQLite may change the behavior of sqlite3_column_type() ** following a type conversion. **+** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()+** or sqlite3_column_bytes16() interfaces can be used to determine the size+** of that BLOB or string.+** ** ^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@@ -4261,9 +4445,13 @@ ** [sqlite3_column_value()] is used in any other way, including calls ** to routines like [sqlite3_value_int()], [sqlite3_value_text()], ** or [sqlite3_value_bytes()], the behavior is not threadsafe.+** Hence, the sqlite3_column_value() interface+** is normally only useful within the implementation of +** [application-defined SQL functions] or [virtual tables], not within+** top-level application code. **-** These routines attempt to convert the value where appropriate. ^For-** example, if the internal representation is FLOAT and a text result+** The these routines may attempt to convert the datatype of the result.+** ^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:@@ -4335,7 +4523,7 @@ ** ^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 <em>not</em> pass the pointers returned+** and BLOBs is freed automatically. Do not pass the pointers returned ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into ** [sqlite3_free()]. **@@ -4346,15 +4534,15 @@ ** [SQLITE_NOMEM].)^ */ SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);-SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);-SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);-SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);+SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);+SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);+SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); /* ** CAPI3REF: Destroy A Prepared Statement Object@@ -4588,21 +4776,43 @@ ** CAPI3REF: Obtaining SQL Values ** METHOD: 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. +** <b>Summary:</b>+** <blockquote><table border=0 cellpadding=0 cellspacing=0>+** <tr><td><b>sqlite3_value_blob</b><td>→<td>BLOB value+** <tr><td><b>sqlite3_value_double</b><td>→<td>REAL value+** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value+** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value+** <tr><td><b>sqlite3_value_pointer</b><td>→<td>Pointer value+** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value+** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in+** the native byteorder+** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value+** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value+** <tr><td> <td> <td> +** <tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB+** or a UTF-8 TEXT in bytes+** <tr><td><b>sqlite3_value_bytes16 </b>+** <td>→ <td>Size of UTF-16+** TEXT in bytes+** <tr><td><b>sqlite3_value_type</b><td>→<td>Default+** datatype of the value+** <tr><td><b>sqlite3_value_numeric_type </b>+** <td>→ <td>Best numeric datatype of the value+** <tr><td><b>sqlite3_value_nochange </b>+** <td>→ <td>True if the column is unchanged in an UPDATE+** against a virtual table.+** </table></blockquote> **-** 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.+** <b>Details:</b> **+** These routines extract type, size, and content information from+** [protected sqlite3_value] objects. Protected sqlite3_value objects+** are used to pass parameter information into implementation of+** [application-defined SQL functions] and [virtual tables].+** ** 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.+** is not threadsafe. ** ** ^These routines work just like the corresponding [column access functions] ** except that these routines take a single [protected sqlite3_value] object@@ -4613,6 +4823,24 @@ ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces ** extract UTF-16 strings as big-endian and little-endian respectively. **+** ^If [sqlite3_value] object V was initialized +** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]+** and if X and Y are strings that compare equal according to strcmp(X,Y),+** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,+** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer() +** routine is part of the [pointer passing interface] added for SQLite 3.20.0.+**+** ^(The sqlite3_value_type(V) interface returns the+** [SQLITE_INTEGER | datatype code] for the initial datatype of the+** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],+** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^+** Other interfaces might change the datatype for an sqlite3_value object.+** For example, if the datatype is initially SQLITE_INTEGER and+** sqlite3_value_text(V) is called to extract a text value for that+** integer, then subsequent calls to sqlite3_value_type(V) might return+** SQLITE_TEXT. Whether or not a persistent internal datatype conversion+** occurs is undefined and may change from one release of SQLite to the next.+** ** ^(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@@ -4621,6 +4849,19 @@ ** then the conversion is performed. Otherwise no conversion occurs. ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^ **+** ^Within the [xUpdate] method of a [virtual table], the+** sqlite3_value_nochange(X) interface returns true if and only if+** the column corresponding to X is unchanged by the UPDATE operation+** that the xUpdate method call was invoked to implement and if+** and the prior [xColumn] method call that was invoked to extracted+** the value for that column returned without setting a result (probably+** because it queried [sqlite3_vtab_nochange()] and found that the column+** was unchanging). ^Within an [xUpdate] method, any value for which+** sqlite3_value_nochange(X) is true will in all other respects appear+** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other+** than within an [xUpdate] method call for an UPDATE statement, then+** the return value is arbitrary and meaningless.+** ** 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@@ -4631,17 +4872,19 @@ ** the SQL function that supplied the [sqlite3_value*] parameters. */ SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);-SQLITE_API int sqlite3_value_bytes(sqlite3_value*);-SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); SQLITE_API double sqlite3_value_double(sqlite3_value*); SQLITE_API int sqlite3_value_int(sqlite3_value*); SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);+SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*); SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);+SQLITE_API int sqlite3_value_bytes(sqlite3_value*);+SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); SQLITE_API int sqlite3_value_type(sqlite3_value*); SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);+SQLITE_API int sqlite3_value_nochange(sqlite3_value*); /* ** CAPI3REF: Finding The Subtype Of SQL Values@@ -4652,10 +4895,6 @@ ** information can be used to pass a limited amount of context from ** one SQL function to another. Use the [sqlite3_result_subtype()] ** routine to set the subtype for the return value of an SQL function.-**-** SQLite makes no use of subtype itself. It merely passes the subtype-** from the result of one [application-defined SQL function] into the-** input of another. */ SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*); @@ -4925,7 +5164,7 @@ ** 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+** then SQLite makes a copy of the result into space obtained ** from [sqlite3_malloc()] before it returns. ** ** ^The sqlite3_result_value() interface sets the result of@@ -4938,6 +5177,17 @@ ** [unprotected sqlite3_value] object is required, so either ** kind of [sqlite3_value] object can be used with this interface. **+** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an+** SQL NULL value, just like [sqlite3_result_null(C)], except that it+** also associates the host-language pointer P or type T with that +** NULL value such that the pointer can be retrieved within an+** [application-defined SQL function] using [sqlite3_value_pointer()].+** ^If the D parameter is not NULL, then it is a pointer to a destructor+** for the P parameter. ^SQLite invokes D with P as its only argument+** when SQLite is finished with P. The T parameter should be a static+** string and preferably a string literal. The sqlite3_result_pointer()+** routine is part of the [pointer passing interface] added for SQLite 3.20.0.+** ** 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.@@ -4961,6 +5211,7 @@ SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);+SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*)); SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); @@ -5620,7 +5871,9 @@ ** ^If the column-name parameter to sqlite3_table_column_metadata() is a ** NULL pointer, then this routine simply checks for the existence of the ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it-** does not.+** does not. If the table name parameter T in a call to+** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is+** undefined behavior. ** ** ^The column is identified by the second, third and fourth parameters to ** this function. ^(The second parameter is either the name of the database@@ -6030,15 +6283,20 @@ ** an operator that is part of a constraint term in the wHERE clause of ** a query that uses a [virtual table]. */-#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-#define SQLITE_INDEX_CONSTRAINT_LIKE 65-#define SQLITE_INDEX_CONSTRAINT_GLOB 66-#define SQLITE_INDEX_CONSTRAINT_REGEXP 67+#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+#define SQLITE_INDEX_CONSTRAINT_LIKE 65+#define SQLITE_INDEX_CONSTRAINT_GLOB 66+#define SQLITE_INDEX_CONSTRAINT_REGEXP 67+#define SQLITE_INDEX_CONSTRAINT_NE 68+#define SQLITE_INDEX_CONSTRAINT_ISNOT 69+#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70+#define SQLITE_INDEX_CONSTRAINT_ISNULL 71+#define SQLITE_INDEX_CONSTRAINT_IS 72 /* ** CAPI3REF: Register A Virtual Table Implementation@@ -6729,9 +6987,9 @@ ** 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+** ^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+** 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. **@@ -6743,7 +7001,7 @@ ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. **-** See also: [SQLITE_FCNTL_LOCKSTATE]+** See also: [file control opcodes] */ SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); @@ -6790,7 +7048,7 @@ #define SQLITE_TESTCTRL_RESERVE 14 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 #define SQLITE_TESTCTRL_ISKEYWORD 16-#define SQLITE_TESTCTRL_SCRATCHMALLOC 17+#define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19@@ -6800,7 +7058,8 @@ #define SQLITE_TESTCTRL_ISINIT 23 #define SQLITE_TESTCTRL_SORTER_MMAP 24 #define SQLITE_TESTCTRL_IMPOSTER 25-#define SQLITE_TESTCTRL_LAST 25+#define SQLITE_TESTCTRL_PARSER_COVERAGE 26+#define SQLITE_TESTCTRL_LAST 26 /* Largest TESTCTRL */ /* ** CAPI3REF: SQLite Runtime Status@@ -6849,8 +7108,7 @@ ** <dd>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+** and internal memory usage by the SQLite library. 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].</dd>)^@@ -6888,29 +7146,14 @@ ** *pHighwater parameter to [sqlite3_status()] is of interest. ** The value written into the *pCurrent parameter is undefined.</dd>)^ **-** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>-** <dd>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.</dd>)^+** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>+** <dd>No longer used.</dd> ** ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>-** <dd>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.-** </dd>)^+** <dd>No longer used.</dd> **-** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>-** <dd>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.</dd>)^+** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>+** <dd>No longer used.</dd> ** ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt> ** <dd>The *pHighwater parameter records the deepest parser stack. @@ -6923,12 +7166,12 @@ #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_SCRATCH_USED 3 /* NOT USED */+#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */ #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_SCRATCH_SIZE 8 /* NOT USED */ #define SQLITE_STATUS_MALLOC_COUNT 9 /*@@ -7133,6 +7376,24 @@ ** used as a proxy for the total work done by the prepared statement. ** If the number of virtual machine operations exceeds 2147483647 ** then the value returned by this statement status code is undefined.+**+** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>+** <dd>^This is the number of times that the prepare statement has been+** automatically regenerated due to schema changes or change to +** [bound parameters] that might affect the query plan.+**+** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>+** <dd>^This is the number of times that the prepared statement has+** been run. A single "run" for the purposes of this counter is one+** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].+** The counter is incremented on the first [sqlite3_step()] call of each+** cycle.+**+** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>+** <dd>^This is the approximate number of bytes of heap memory+** used to store the prepared statement. ^This value is not actually+** a counter, and so the resetFlg parameter to sqlite3_stmt_status()+** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED. ** </dd> ** </dl> */@@ -7140,6 +7401,9 @@ #define SQLITE_STMTSTATUS_SORT 2 #define SQLITE_STMTSTATUS_AUTOINDEX 3 #define SQLITE_STMTSTATUS_VM_STEP 4+#define SQLITE_STMTSTATUS_REPREPARE 5+#define SQLITE_STMTSTATUS_RUN 6+#define SQLITE_STMTSTATUS_MEMUSED 99 /* ** CAPI3REF: Custom Page Cache Object@@ -8050,6 +8314,40 @@ SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); /*+** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE+**+** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]+** method of a [virtual table], then it returns true if and only if the+** column is being fetched as part of an UPDATE operation during which the+** column value will not change. Applications might use this to substitute+** a lighter-weight value to return that the corresponding [xUpdate] method+** understands as a "no-change" value.+**+** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that+** the column is not changed by the UPDATE statement, they the xColumn+** method can optionally return without setting a result, without calling+** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].+** In that case, [sqlite3_value_nochange(X)] will return true for the+** same column in the [xUpdate] method.+*/+SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);++/*+** CAPI3REF: Determine The Collation For a Virtual Table Constraint+**+** This function may only be called from within a call to the [xBestIndex]+** method of a [virtual table]. +**+** The first argument must be the sqlite3_index_info object that is the+** first parameter to the xBestIndex() method. The second argument must be+** an index into the aConstraint[] array belonging to the sqlite3_index_info+** structure passed to xBestIndex. This function returns a pointer to a buffer +** containing the name of the collation sequence for the corresponding+** constraint.+*/+SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);++/* ** CAPI3REF: Conflict resolution modes ** KEYWORDS: {conflict resolution mode} **@@ -8776,6 +9074,35 @@ ** ** SQLITE_OK is returned if the call completes without error. Or, if an error ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.+**+** <h3>Special sqlite_stat1 Handling</h3>+**+** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to +** some of the rules above. In SQLite, the schema of sqlite_stat1 is:+** <pre>+** CREATE TABLE sqlite_stat1(tbl,idx,stat) +** </pre>+**+** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are +** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes +** are recorded for rows for which (idx IS NULL) is true. However, for such+** rows a zero-length blob (SQL value X'') is stored in the changeset or+** patchset instead of a NULL value. This allows such changesets to be+** manipulated by legacy implementations of sqlite3changeset_invert(),+** concat() and similar.+**+** The sqlite3changeset_apply() function automatically converts the +** zero-length blob back to a NULL value when updating the sqlite_stat1+** table. However, if the application calls sqlite3changeset_new(),+** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset +** iterator directly (including on a changeset iterator passed to a+** conflict-handler callback) then the X'' value is returned. The application+** must translate X'' to NULL itself if required.+**+** Legacy (older than 3.22.0) versions of the sessions module cannot capture+** changes made to the sqlite_stat1 table. Legacy versions of the+** sqlite3changeset_apply() function silently ignore any modifications to the+** sqlite_stat1 table that are part of a changeset or patchset. */ SQLITE_API int sqlite3session_attach( sqlite3_session *pSession, /* Session object */@@ -9004,8 +9331,8 @@ */ SQLITE_API int sqlite3session_patchset( sqlite3_session *pSession, /* Session object */- int *pnPatchset, /* OUT: Size of buffer at *ppChangeset */- void **ppPatchset /* OUT: Buffer containing changeset */+ int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */+ void **ppPatchset /* OUT: Buffer containing patchset */ ); /*@@ -9772,12 +10099,12 @@ ** ** <table border=1 style="margin-left:8ex;margin-right:8ex"> ** <tr><th>Streaming function<th>Non-streaming equivalent</th>-** <tr><td>sqlite3changeset_apply_str<td>[sqlite3changeset_apply] -** <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat] -** <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert] -** <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start] -** <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset] -** <tr><td>sqlite3session_patchset_str<td>[sqlite3session_patchset] +** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply] +** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat] +** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert] +** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start] +** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset] +** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset] ** </table> ** ** Non-streaming functions that accept changesets (or patchsets) as input
persistent-sqlite.cabal view
@@ -1,5 +1,5 @@ name: persistent-sqlite-version: 2.8.1+version: 2.8.1.1 license: MIT license-file: LICENSE author: Michael Snoyman <michael@snoyman.com>