LuaSQLite3

Check-in [21ab5cda4d]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update for Lua 5.4 and SQLite 3.24.0
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 21ab5cda4d8fa060d717dc08240dd5ab9872608f
User & Date: e 2018-06-30 17:23:49
Context
2018-06-30
17:35
Update HISTORY, remove obsolete file. check-in: dd7e65e22e user: e tags: fsl_9y, trunk
17:23
Update for Lua 5.4 and SQLite 3.24.0 check-in: 21ab5cda4d user: e tags: trunk
2016-11-15
17:53
Change conditional tests from WIN32 to _WIN32 for lsqlite_temp_directory. check-in: 6fc7943d1d user: e tags: fsl_9x, trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Deleted lsqlite3-0.9.4-2.rockspec.

     1         -package = "lsqlite3"
     2         -version = "0.9.4-2"
     3         -source = {
     4         -    url = "http://lua.sqlite.org/index.cgi/zip/lsqlite3_fsl09x.zip?uuid=fsl_9x",
     5         -    file = "lsqlite3_fsl09x.zip"
     6         -}
     7         -description = {
     8         -    summary = "A binding for Lua to the SQLite3 database library",
     9         -    detailed = [[
    10         -        lsqlite3 is a thin wrapper around the public domain SQLite3 database engine. SQLite3 is 
    11         -        dynamically linked to lsqlite3. The statically linked alternative is lsqlite3complete.
    12         -        The lsqlite3 module supports the creation and manipulation of SQLite3 databases. 
    13         -        Most sqlite3 functions are called via an object-oriented interface to either 
    14         -        database or SQL statement objects.
    15         -    ]],
    16         -    license = "MIT",
    17         -    homepage = "http://lua.sqlite.org/"
    18         -}
    19         -dependencies = {
    20         -    "lua >= 5.1, < 5.4"
    21         -}
    22         -external_dependencies = {
    23         -    SQLITE = {
    24         -        header = "sqlite3.h"
    25         -    }
    26         -}
    27         -build = {
    28         -    type = "builtin",
    29         -    modules = {
    30         -        lsqlite3 = {
    31         -            sources = { "lsqlite3.c" },
    32         -            defines = {'LSQLITE_VERSION="0.9.4"'},
    33         -            libraries = { "sqlite3" },
    34         -            incdirs = { "$(SQLITE_INCDIR)" },
    35         -            libdirs = { "$(SQLITE_LIBDIR)" }
    36         -        },
    37         -    },
    38         -	copy_directories = { 'doc', 'examples' }
    39         -}

Added lsqlite3-0.9.5-1.rockspec.

            1  +package = "lsqlite3"
            2  +version = "0.9.5-1"
            3  +source = {
            4  +    url = "http://lua.sqlite.org/index.cgi/zip/lsqlite3_fsl09y.zip?uuid=fsl_9y",
            5  +    file = "lsqlite3_fsl09y.zip"
            6  +}
            7  +description = {
            8  +    summary = "A binding for Lua to the SQLite3 database library",
            9  +    detailed = [[
           10  +        lsqlite3 is a thin wrapper around the public domain SQLite3 database engine. SQLite3 is 
           11  +        dynamically linked to lsqlite3. The statically linked alternative is lsqlite3complete.
           12  +        The lsqlite3 module supports the creation and manipulation of SQLite3 databases. 
           13  +        Most sqlite3 functions are called via an object-oriented interface to either 
           14  +        database or SQL statement objects.
           15  +    ]],
           16  +    license = "MIT",
           17  +    homepage = "http://lua.sqlite.org/"
           18  +}
           19  +dependencies = {
           20  +    "lua >= 5.1, < 5.5"
           21  +}
           22  +external_dependencies = {
           23  +    SQLITE = {
           24  +        header = "sqlite3.h"
           25  +    }
           26  +}
           27  +build = {
           28  +    type = "builtin",
           29  +    modules = {
           30  +        lsqlite3 = {
           31  +            sources = { "lsqlite3.c" },
           32  +            defines = {'LSQLITE_VERSION="0.9.5"'},
           33  +            libraries = { "sqlite3" },
           34  +            incdirs = { "$(SQLITE_INCDIR)" },
           35  +            libdirs = { "$(SQLITE_LIBDIR)" }
           36  +        },
           37  +    },
           38  +	copy_directories = { 'doc', 'examples' }
           39  +}

Changes to lsqlite3.c.

    34     34   #include "lua.h"
    35     35   #include "lauxlib.h"
    36     36   
    37     37   #if LUA_VERSION_NUM > 501
    38     38   /*
    39     39   ** Lua 5.2
    40     40   */
           41  +#ifndef lua_strlen
    41     42   #define lua_strlen lua_rawlen
           43  +#endif
    42     44   /* luaL_typerror always used with arg at ndx == NULL */
    43     45   #define luaL_typerror(L,ndx,str) luaL_error(L,"bad argument %d (%s expected, got nil)",ndx,str)
    44     46   /* luaL_register used once, so below expansion is OK for this case */
    45     47   #define luaL_register(L,name,reg) lua_newtable(L);luaL_setfuncs(L,reg,0)
    46     48   /* luaL_openlib always used with name == NULL */
    47     49   #define luaL_openlib(L,name,reg,nup) luaL_setfuncs(L,reg,nup)
    48     50   

Added lsqlite3complete-0.9.5-1.rockspec.

            1  +package = "lsqlite3complete"
            2  +version = "0.9.5-1"
            3  +source = {
            4  +    url = "http://lua.sqlite.org/index.cgi/zip/lsqlite3_fsl09y.zip?uuid=fsl_9y",
            5  +    file = "lsqlite3_fsl09y.zip"
            6  +}
            7  +description = {
            8  +    summary = "A binding for Lua to the SQLite3 database library",
            9  +    detailed = [[
           10  +        lsqlite3complete is a thin wrapper around the public domain SQLite3 database engine. 
           11  +        SQLite3 is included and statically linked. (The dynamically linked alternative is lsqlite3).
           12  +        The lsqlite3complete module supports the creation and manipulation of SQLite3 databases. 
           13  +        Most sqlite3 functions are called via an object-oriented interface to either database
           14  +        or SQL statement objects.
           15  +    ]],
           16  +    license = "MIT",
           17  +    homepage = "http://lua.sqlite.org/"
           18  +}
           19  +dependencies = {
           20  +    "lua >= 5.1, < 5.5"
           21  +}
           22  +build = {
           23  +    type = "builtin",
           24  +    modules = {
           25  +        lsqlite3complete = {
           26  +            sources = { "lsqlite3.c", "sqlite3.c" },
           27  +            defines = {'LSQLITE_VERSION="0.9.5"', 'luaopen_lsqlite3=luaopen_lsqlite3complete'}
           28  +        },
           29  +    },
           30  +    platforms = {
           31  +        unix = {
           32  +            modules = {
           33  +                lsqlite3complete = {
           34  +                    libraries = { "pthread", "m", "dl" }
           35  +                }
           36  +            }
           37  +        }
           38  +    },
           39  +    copy_directories = { 'doc', 'examples' }
           40  +}

Changes to sqlite3.c.

more than 10,000 changes

Changes to sqlite3.h.

     1      1   /*
     2         -** 2001 September 15
            2  +** 2001-09-15
     3      3   **
     4      4   ** The author disclaims copyright to this source code.  In place of
     5      5   ** a legal notice, here is a blessing:
     6      6   **
     7      7   **    May you do good and not evil.
     8      8   **    May you find forgiveness for yourself and forgive others.
     9      9   **    May you share freely, never taking more than you give.
................................................................................
   110    110   **
   111    111   ** Since [version 3.6.18] ([dateof:3.6.18]), 
   112    112   ** SQLite source code has been stored in the
   113    113   ** <a href="http://www.fossil-scm.org/">Fossil configuration management
   114    114   ** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
   115    115   ** a string which identifies a particular check-in of SQLite
   116    116   ** within its configuration management system.  ^The SQLITE_SOURCE_ID
   117         -** string contains the date and time of the check-in (UTC) and an SHA1
   118         -** hash of the entire source tree.
          117  +** string contains the date and time of the check-in (UTC) and a SHA1
          118  +** or SHA3-256 hash of the entire source tree.  If the source code has
          119  +** been edited in any way since it was last checked in, then the last
          120  +** four hexadecimal digits of the hash may be modified.
   119    121   **
   120    122   ** See also: [sqlite3_libversion()],
   121    123   ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
   122    124   ** [sqlite_version()] and [sqlite_source_id()].
   123    125   */
   124         -#define SQLITE_VERSION        "3.15.1"
   125         -#define SQLITE_VERSION_NUMBER 3015001
   126         -#define SQLITE_SOURCE_ID      "2016-11-04 12:08:49 1136863c76576110e710dd5d69ab6bf347c65e36"
          126  +#define SQLITE_VERSION        "3.24.0"
          127  +#define SQLITE_VERSION_NUMBER 3024000
          128  +#define SQLITE_SOURCE_ID      "2018-06-04 19:24:41 c7ee0833225bfd8c5ec2f9bf62b97c4e04d03bd9566366d5221ac8fb199a87ca"
   127    129   
   128    130   /*
   129    131   ** CAPI3REF: Run-Time Library Version Numbers
   130         -** KEYWORDS: sqlite3_version, sqlite3_sourceid
          132  +** KEYWORDS: sqlite3_version sqlite3_sourceid
   131    133   **
   132    134   ** These interfaces provide the same information as the [SQLITE_VERSION],
   133    135   ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
   134    136   ** but are associated with the library instead of the header file.  ^(Cautious
   135    137   ** programmers might include assert() statements in their application to
   136    138   ** verify that values returned by these interfaces match the macros in
   137    139   ** the header, and thus ensure that the application is
   138    140   ** compiled with matching library and header files.
   139    141   **
   140    142   ** <blockquote><pre>
   141    143   ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
   142         -** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
          144  +** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
   143    145   ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
   144    146   ** </pre></blockquote>)^
   145    147   **
   146    148   ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
   147    149   ** macro.  ^The sqlite3_libversion() function returns a pointer to the
   148    150   ** to the sqlite3_version[] string constant.  The sqlite3_libversion()
   149    151   ** function is provided for use in DLLs since DLL users usually do not have
   150    152   ** direct access to string constants within the DLL.  ^The
   151    153   ** sqlite3_libversion_number() function returns an integer equal to
   152         -** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 
          154  +** [SQLITE_VERSION_NUMBER].  ^(The sqlite3_sourceid() function returns 
   153    155   ** a pointer to a string constant whose value is the same as the 
   154         -** [SQLITE_SOURCE_ID] C preprocessor macro.
          156  +** [SQLITE_SOURCE_ID] C preprocessor macro.  Except if SQLite is built
          157  +** using an edited copy of [the amalgamation], then the last four characters
          158  +** of the hash might be different from [SQLITE_SOURCE_ID].)^
   155    159   **
   156    160   ** See also: [sqlite_version()] and [sqlite_source_id()].
   157    161   */
   158    162   SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
   159    163   SQLITE_API const char *sqlite3_libversion(void);
   160    164   SQLITE_API const char *sqlite3_sourceid(void);
   161    165   SQLITE_API int sqlite3_libversion_number(void);
................................................................................
   255    259   ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
   256    260   ** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
   257    261   ** sqlite3_uint64 and sqlite_uint64 types can store integer values 
   258    262   ** between 0 and +18446744073709551615 inclusive.
   259    263   */
   260    264   #ifdef SQLITE_INT64_TYPE
   261    265     typedef SQLITE_INT64_TYPE sqlite_int64;
   262         -  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
          266  +# ifdef SQLITE_UINT64_TYPE
          267  +    typedef SQLITE_UINT64_TYPE sqlite_uint64;
          268  +# else  
          269  +    typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
          270  +# endif
   263    271   #elif defined(_MSC_VER) || defined(__BORLANDC__)
   264    272     typedef __int64 sqlite_int64;
   265    273     typedef unsigned __int64 sqlite_uint64;
   266    274   #else
   267    275     typedef long long int sqlite_int64;
   268    276     typedef unsigned long long int sqlite_uint64;
   269    277   #endif
................................................................................
   409    417   **
   410    418   ** New error codes may be added in future versions of SQLite.
   411    419   **
   412    420   ** See also: [extended result code definitions]
   413    421   */
   414    422   #define SQLITE_OK           0   /* Successful result */
   415    423   /* beginning-of-error-codes */
   416         -#define SQLITE_ERROR        1   /* SQL error or missing database */
          424  +#define SQLITE_ERROR        1   /* Generic error */
   417    425   #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
   418    426   #define SQLITE_PERM         3   /* Access permission denied */
   419    427   #define SQLITE_ABORT        4   /* Callback routine requested an abort */
   420    428   #define SQLITE_BUSY         5   /* The database file is locked */
   421    429   #define SQLITE_LOCKED       6   /* A table in the database is locked */
   422    430   #define SQLITE_NOMEM        7   /* A malloc() failed */
   423    431   #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
................................................................................
   424    432   #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
   425    433   #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
   426    434   #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
   427    435   #define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
   428    436   #define SQLITE_FULL        13   /* Insertion failed because database is full */
   429    437   #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
   430    438   #define SQLITE_PROTOCOL    15   /* Database lock protocol error */
   431         -#define SQLITE_EMPTY       16   /* Database is empty */
          439  +#define SQLITE_EMPTY       16   /* Internal use only */
   432    440   #define SQLITE_SCHEMA      17   /* The database schema changed */
   433    441   #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
   434    442   #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
   435    443   #define SQLITE_MISMATCH    20   /* Data type mismatch */
   436    444   #define SQLITE_MISUSE      21   /* Library used incorrectly */
   437    445   #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
   438    446   #define SQLITE_AUTH        23   /* Authorization denied */
   439         -#define SQLITE_FORMAT      24   /* Auxiliary database format error */
          447  +#define SQLITE_FORMAT      24   /* Not used */
   440    448   #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
   441    449   #define SQLITE_NOTADB      26   /* File opened that is not a database file */
   442    450   #define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
   443    451   #define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
   444    452   #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
   445    453   #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
   446    454   /* end-of-error-codes */
................................................................................
   458    466   ** support for additional result codes that provide more detailed information
   459    467   ** about errors. These [extended result codes] are enabled or disabled
   460    468   ** on a per database connection basis using the
   461    469   ** [sqlite3_extended_result_codes()] API.  Or, the extended code for
   462    470   ** the most recent error can be obtained using
   463    471   ** [sqlite3_extended_errcode()].
   464    472   */
          473  +#define SQLITE_ERROR_MISSING_COLLSEQ   (SQLITE_ERROR | (1<<8))
          474  +#define SQLITE_ERROR_RETRY             (SQLITE_ERROR | (2<<8))
   465    475   #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
   466    476   #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
   467    477   #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
   468    478   #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
   469    479   #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
   470    480   #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
   471    481   #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
................................................................................
   486    496   #define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
   487    497   #define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
   488    498   #define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
   489    499   #define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
   490    500   #define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
   491    501   #define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))
   492    502   #define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))
          503  +#define SQLITE_IOERR_BEGIN_ATOMIC      (SQLITE_IOERR | (29<<8))
          504  +#define SQLITE_IOERR_COMMIT_ATOMIC     (SQLITE_IOERR | (30<<8))
          505  +#define SQLITE_IOERR_ROLLBACK_ATOMIC   (SQLITE_IOERR | (31<<8))
   493    506   #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
          507  +#define SQLITE_LOCKED_VTAB             (SQLITE_LOCKED |  (2<<8))
   494    508   #define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
   495    509   #define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
   496    510   #define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
   497    511   #define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
   498    512   #define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
   499    513   #define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
   500    514   #define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
          515  +#define SQLITE_CORRUPT_SEQUENCE        (SQLITE_CORRUPT | (2<<8))
   501    516   #define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
   502    517   #define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
   503    518   #define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
   504    519   #define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
          520  +#define SQLITE_READONLY_CANTINIT       (SQLITE_READONLY | (5<<8))
          521  +#define SQLITE_READONLY_DIRECTORY      (SQLITE_READONLY | (6<<8))
   505    522   #define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
   506    523   #define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
   507    524   #define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
   508    525   #define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
   509    526   #define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
   510    527   #define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
   511    528   #define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
................................................................................
   568    585   ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
   569    586   ** information is written to disk in the same order as calls
   570    587   ** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
   571    588   ** after reboot following a crash or power loss, the only bytes in a
   572    589   ** file that were written at the application level might have changed
   573    590   ** and that adjacent bytes, even bytes within the same sector are
   574    591   ** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
   575         -** flag indicate that a file cannot be deleted when open.  The
          592  +** flag indicates that a file cannot be deleted when open.  The
   576    593   ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
   577    594   ** read-only media and cannot be changed even by processes with
   578    595   ** elevated privileges.
          596  +**
          597  +** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
          598  +** filesystem supports doing multiple write operations atomically when those
          599  +** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
          600  +** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
   579    601   */
   580    602   #define SQLITE_IOCAP_ATOMIC                 0x00000001
   581    603   #define SQLITE_IOCAP_ATOMIC512              0x00000002
   582    604   #define SQLITE_IOCAP_ATOMIC1K               0x00000004
   583    605   #define SQLITE_IOCAP_ATOMIC2K               0x00000008
   584    606   #define SQLITE_IOCAP_ATOMIC4K               0x00000010
   585    607   #define SQLITE_IOCAP_ATOMIC8K               0x00000020
................................................................................
   587    609   #define SQLITE_IOCAP_ATOMIC32K              0x00000080
   588    610   #define SQLITE_IOCAP_ATOMIC64K              0x00000100
   589    611   #define SQLITE_IOCAP_SAFE_APPEND            0x00000200
   590    612   #define SQLITE_IOCAP_SEQUENTIAL             0x00000400
   591    613   #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
   592    614   #define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
   593    615   #define SQLITE_IOCAP_IMMUTABLE              0x00002000
          616  +#define SQLITE_IOCAP_BATCH_ATOMIC           0x00004000
   594    617   
   595    618   /*
   596    619   ** CAPI3REF: File Locking Levels
   597    620   **
   598    621   ** SQLite uses one of these integer values as the second
   599    622   ** argument to calls it makes to the xLock() and xUnlock() methods
   600    623   ** of an [sqlite3_io_methods] object.
................................................................................
   718    741   ** <li> [SQLITE_IOCAP_ATOMIC4K]
   719    742   ** <li> [SQLITE_IOCAP_ATOMIC8K]
   720    743   ** <li> [SQLITE_IOCAP_ATOMIC16K]
   721    744   ** <li> [SQLITE_IOCAP_ATOMIC32K]
   722    745   ** <li> [SQLITE_IOCAP_ATOMIC64K]
   723    746   ** <li> [SQLITE_IOCAP_SAFE_APPEND]
   724    747   ** <li> [SQLITE_IOCAP_SEQUENTIAL]
          748  +** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
          749  +** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
          750  +** <li> [SQLITE_IOCAP_IMMUTABLE]
          751  +** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
   725    752   ** </ul>
   726    753   **
   727    754   ** The SQLITE_IOCAP_ATOMIC property means that all writes of
   728    755   ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
   729    756   ** mean that writes of blocks that are nnn bytes in size and
   730    757   ** are aligned to an address which is an integer multiple of
   731    758   ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
................................................................................
   846    873   ** anti-virus programs.  By default, the windows VFS will retry file read,
   847    874   ** file write, and file delete operations up to 10 times, with a delay
   848    875   ** of 25 milliseconds before the first retry and with the delay increasing
   849    876   ** by an additional 25 milliseconds with each subsequent retry.  This
   850    877   ** opcode allows these two values (10 retries and 25 milliseconds of delay)
   851    878   ** to be adjusted.  The values are changed for all database connections
   852    879   ** within the same process.  The argument is a pointer to an array of two
   853         -** integers where the first integer i the new retry count and the second
          880  +** integers where the first integer is the new retry count and the second
   854    881   ** integer is the delay.  If either integer is negative, then the setting
   855    882   ** is not changed but instead the prior value of that setting is written
   856    883   ** into the array entry, allowing the current retry settings to be
   857    884   ** interrogated.  The zDbName parameter is ignored.
   858    885   **
   859    886   ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
   860    887   ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
................................................................................
  1001   1028   ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
  1002   1029   ** VFS should return SQLITE_NOTFOUND for this opcode.
  1003   1030   **
  1004   1031   ** <li>[[SQLITE_FCNTL_RBU]]
  1005   1032   ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
  1006   1033   ** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
  1007   1034   ** this opcode.  
         1035  +**
         1036  +** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
         1037  +** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
         1038  +** the file descriptor is placed in "batch write mode", which
         1039  +** means all subsequent write operations will be deferred and done
         1040  +** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].  Systems
         1041  +** that do not support batch atomic writes will return SQLITE_NOTFOUND.
         1042  +** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
         1043  +** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
         1044  +** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
         1045  +** no VFS interface calls on the same [sqlite3_file] file descriptor
         1046  +** except for calls to the xWrite method and the xFileControl method
         1047  +** with [SQLITE_FCNTL_SIZE_HINT].
         1048  +**
         1049  +** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
         1050  +** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
         1051  +** operations since the previous successful call to 
         1052  +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
         1053  +** This file control returns [SQLITE_OK] if and only if the writes were
         1054  +** all performed successfully and have been committed to persistent storage.
         1055  +** ^Regardless of whether or not it is successful, this file control takes
         1056  +** the file descriptor out of batch write mode so that all subsequent
         1057  +** write operations are independent.
         1058  +** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
         1059  +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
         1060  +**
         1061  +** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
         1062  +** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
         1063  +** operations since the previous successful call to 
         1064  +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
         1065  +** ^This file control takes the file descriptor out of batch write mode
         1066  +** so that all subsequent write operations are independent.
         1067  +** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
         1068  +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
         1069  +**
         1070  +** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
         1071  +** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain
         1072  +** a file lock using the xLock or xShmLock methods of the VFS to wait
         1073  +** for up to M milliseconds before failing, where M is the single 
         1074  +** unsigned integer parameter.
  1008   1075   ** </ul>
  1009   1076   */
  1010   1077   #define SQLITE_FCNTL_LOCKSTATE               1
  1011   1078   #define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
  1012   1079   #define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
  1013   1080   #define SQLITE_FCNTL_LAST_ERRNO              4
  1014   1081   #define SQLITE_FCNTL_SIZE_HINT               5
................................................................................
  1031   1098   #define SQLITE_FCNTL_WIN32_SET_HANDLE       23
  1032   1099   #define SQLITE_FCNTL_WAL_BLOCK              24
  1033   1100   #define SQLITE_FCNTL_ZIPVFS                 25
  1034   1101   #define SQLITE_FCNTL_RBU                    26
  1035   1102   #define SQLITE_FCNTL_VFS_POINTER            27
  1036   1103   #define SQLITE_FCNTL_JOURNAL_POINTER        28
  1037   1104   #define SQLITE_FCNTL_WIN32_GET_HANDLE       29
         1105  +#define SQLITE_FCNTL_PDB                    30
         1106  +#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
         1107  +#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
         1108  +#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
         1109  +#define SQLITE_FCNTL_LOCK_TIMEOUT           34
  1038   1110   
  1039   1111   /* deprecated names */
  1040   1112   #define SQLITE_GET_LOCKPROXYFILE      SQLITE_FCNTL_GET_LOCKPROXYFILE
  1041   1113   #define SQLITE_SET_LOCKPROXYFILE      SQLITE_FCNTL_SET_LOCKPROXYFILE
  1042   1114   #define SQLITE_LAST_ERRNO             SQLITE_FCNTL_LAST_ERRNO
  1043   1115   
  1044   1116   
................................................................................
  1068   1140   ** CAPI3REF: OS Interface Object
  1069   1141   **
  1070   1142   ** An instance of the sqlite3_vfs object defines the interface between
  1071   1143   ** the SQLite core and the underlying operating system.  The "vfs"
  1072   1144   ** in the name of the object stands for "virtual file system".  See
  1073   1145   ** the [VFS | VFS documentation] for further information.
  1074   1146   **
  1075         -** The value of the iVersion field is initially 1 but may be larger in
  1076         -** future versions of SQLite.  Additional fields may be appended to this
  1077         -** object when the iVersion value is increased.  Note that the structure
  1078         -** of the sqlite3_vfs object changes in the transaction between
  1079         -** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
  1080         -** modified.
         1147  +** The VFS interface is sometimes extended by adding new methods onto
         1148  +** the end.  Each time such an extension occurs, the iVersion field
         1149  +** is incremented.  The iVersion value started out as 1 in
         1150  +** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
         1151  +** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
         1152  +** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6].  Additional fields
         1153  +** may be appended to the sqlite3_vfs object and the iVersion value
         1154  +** may increase again in future versions of SQLite.
         1155  +** Note that the structure
         1156  +** of the sqlite3_vfs object changes in the transition from
         1157  +** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
         1158  +** and yet the iVersion field was not modified.
  1081   1159   **
  1082   1160   ** The szOsFile field is the size of the subclassed [sqlite3_file]
  1083   1161   ** structure used by this VFS.  mxPathname is the maximum length of
  1084   1162   ** a pathname in this VFS.
  1085   1163   **
  1086   1164   ** Registered sqlite3_vfs objects are kept on a linked list formed by
  1087   1165   ** the pNext pointer.  The [sqlite3_vfs_register()]
................................................................................
  1600   1678   ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
  1601   1679   ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
  1602   1680   ** The [sqlite3_mem_methods]
  1603   1681   ** structure is filled with the currently defined memory allocation routines.)^
  1604   1682   ** This option can be used to overload the default memory allocation
  1605   1683   ** routines with a wrapper that simulations memory allocation failure or
  1606   1684   ** tracks memory usage, for example. </dd>
         1685  +**
         1686  +** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
         1687  +** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
         1688  +** type int, interpreted as a boolean, which if true provides a hint to
         1689  +** SQLite that it should avoid large memory allocations if possible.
         1690  +** SQLite will run faster if it is free to make large memory allocations,
         1691  +** but some application might prefer to run slower in exchange for
         1692  +** guarantees about memory fragmentation that are possible if large
         1693  +** allocations are avoided.  This hint is normally off.
         1694  +** </dd>
  1607   1695   **
  1608   1696   ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1609   1697   ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
  1610   1698   ** interpreted as a boolean, which enables or disables the collection of
  1611   1699   ** memory allocation statistics. ^(When memory allocation statistics are
  1612   1700   ** disabled, the following SQLite interfaces become non-operational:
  1613   1701   **   <ul>
................................................................................
  1618   1706   **   </ul>)^
  1619   1707   ** ^Memory allocation statistics are enabled by default unless SQLite is
  1620   1708   ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
  1621   1709   ** allocation statistics are disabled by default.
  1622   1710   ** </dd>
  1623   1711   **
  1624   1712   ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
  1625         -** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
  1626         -** that SQLite can use for scratch memory.  ^(There are three arguments
  1627         -** to SQLITE_CONFIG_SCRATCH:  A pointer an 8-byte
  1628         -** aligned memory buffer from which the scratch allocations will be
  1629         -** drawn, the size of each scratch allocation (sz),
  1630         -** and the maximum number of scratch allocations (N).)^
  1631         -** The first argument must be a pointer to an 8-byte aligned buffer
  1632         -** of at least sz*N bytes of memory.
  1633         -** ^SQLite will not use more than one scratch buffers per thread.
  1634         -** ^SQLite will never request a scratch buffer that is more than 6
  1635         -** times the database page size.
  1636         -** ^If SQLite needs needs additional
  1637         -** scratch memory beyond what is provided by this configuration option, then 
  1638         -** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
  1639         -** ^When the application provides any amount of scratch memory using
  1640         -** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
  1641         -** [sqlite3_malloc|heap allocations].
  1642         -** This can help [Robson proof|prevent memory allocation failures] due to heap
  1643         -** fragmentation in low-memory embedded systems.
         1713  +** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
  1644   1714   ** </dd>
  1645   1715   **
  1646   1716   ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1647   1717   ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
  1648   1718   ** that SQLite can use for the database page cache with the default page
  1649   1719   ** cache implementation.  
  1650   1720   ** This configuration option is a no-op if an application-define page
................................................................................
  1672   1742   ** page cache memory is needed beyond what is provided by the initial
  1673   1743   ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
  1674   1744   ** additional cache line. </dd>
  1675   1745   **
  1676   1746   ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
  1677   1747   ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer 
  1678   1748   ** that SQLite will use for all of its dynamic memory allocation needs
  1679         -** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and
  1680         -** [SQLITE_CONFIG_PAGECACHE].
         1749  +** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
  1681   1750   ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
  1682   1751   ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
  1683   1752   ** [SQLITE_ERROR] if invoked otherwise.
  1684   1753   ** ^There are three arguments to SQLITE_CONFIG_HEAP:
  1685   1754   ** An 8-byte aligned pointer to the memory,
  1686   1755   ** the number of bytes in the memory buffer, and the minimum allocation size.
  1687   1756   ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
................................................................................
  1859   1928   ** Or if the threshold is -1, statement journals are always held
  1860   1929   ** exclusively in memory.
  1861   1930   ** Since many statement journals never become large, setting the spill
  1862   1931   ** threshold to a value such as 64KiB can greatly reduce the amount of
  1863   1932   ** I/O required to support statement rollback.
  1864   1933   ** The default value for this setting is controlled by the
  1865   1934   ** [SQLITE_STMTJRNL_SPILL] compile-time option.
         1935  +**
         1936  +** [[SQLITE_CONFIG_SORTERREF_SIZE]]
         1937  +** <dt>SQLITE_CONFIG_SORTERREF_SIZE
         1938  +** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
         1939  +** of type (int) - the new value of the sorter-reference size threshold.
         1940  +** Usually, when SQLite uses an external sort to order records according
         1941  +** to an ORDER BY clause, all fields required by the caller are present in the
         1942  +** sorted records. However, if SQLite determines based on the declared type
         1943  +** of a table column that its values are likely to be very large - larger
         1944  +** than the configured sorter-reference size threshold - then a reference
         1945  +** is stored in each sorted record and the required column values loaded
         1946  +** from the database as records are returned in sorted order. The default
         1947  +** value for this option is to never use this optimization. Specifying a 
         1948  +** negative value for this option restores the default behaviour.
         1949  +** This option is only available if SQLite is compiled with the
         1950  +** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
  1866   1951   ** </dl>
  1867   1952   */
  1868   1953   #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
  1869   1954   #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
  1870   1955   #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
  1871   1956   #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
  1872   1957   #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
  1873         -#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
         1958  +#define SQLITE_CONFIG_SCRATCH       6  /* No longer used */
  1874   1959   #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
  1875   1960   #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
  1876   1961   #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
  1877   1962   #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
  1878   1963   #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
  1879   1964   /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
  1880   1965   #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
................................................................................
  1887   1972   #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
  1888   1973   #define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
  1889   1974   #define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
  1890   1975   #define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
  1891   1976   #define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */
  1892   1977   #define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */
  1893   1978   #define SQLITE_CONFIG_STMTJRNL_SPILL      26  /* int nByte */
         1979  +#define SQLITE_CONFIG_SMALL_MALLOC        27  /* boolean */
         1980  +#define SQLITE_CONFIG_SORTERREF_SIZE      28  /* int nByte */
  1894   1981   
  1895   1982   /*
  1896   1983   ** CAPI3REF: Database Connection Configuration Options
  1897   1984   **
  1898   1985   ** These constants are the available integer configuration options that
  1899   1986   ** can be passed as the second argument to the [sqlite3_db_config()] interface.
  1900   1987   **
................................................................................
  1983   2070   ** schema.  ^The sole argument is a pointer to a constant UTF8 string
  1984   2071   ** which will become the new schema name in place of "main".  ^SQLite
  1985   2072   ** does not make a copy of the new main schema name string, so the application
  1986   2073   ** must ensure that the argument passed into this DBCONFIG option is unchanged
  1987   2074   ** until after the database connection closes.
  1988   2075   ** </dd>
  1989   2076   **
         2077  +** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
         2078  +** <dd> Usually, when a database in wal mode is closed or detached from a 
         2079  +** database handle, SQLite checks if this will mean that there are now no 
         2080  +** connections at all to the database. If so, it performs a checkpoint 
         2081  +** operation before closing the connection. This option may be used to
         2082  +** override this behaviour. The first parameter passed to this operation
         2083  +** is an integer - positive to disable checkpoints-on-close, or zero (the
         2084  +** default) to enable them, and negative to leave the setting unchanged.
         2085  +** The second parameter is a pointer to an integer
         2086  +** into which is written 0 or 1 to indicate whether checkpoints-on-close
         2087  +** have been disabled - 0 if they are not disabled, 1 if they are.
         2088  +** </dd>
         2089  +**
         2090  +** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
         2091  +** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
         2092  +** the [query planner stability guarantee] (QPSG).  When the QPSG is active,
         2093  +** a single SQL query statement will always use the same algorithm regardless
         2094  +** of values of [bound parameters].)^ The QPSG disables some query optimizations
         2095  +** that look at the values of bound parameters, which can make some queries
         2096  +** slower.  But the QPSG has the advantage of more predictable behavior.  With
         2097  +** the QPSG active, SQLite will always use the same query plan in the field as
         2098  +** was used during testing in the lab.
         2099  +** The first argument to this setting is an integer which is 0 to disable 
         2100  +** the QPSG, positive to enable QPSG, or negative to leave the setting
         2101  +** unchanged. The second parameter is a pointer to an integer into which
         2102  +** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
         2103  +** following this call.
         2104  +** </dd>
         2105  +**
         2106  +** <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
         2107  +** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not 
         2108  +** include output for any operations performed by trigger programs. This
         2109  +** option is used to set or clear (the default) a flag that governs this
         2110  +** behavior. The first parameter passed to this operation is an integer -
         2111  +** positive to enable output for trigger programs, or zero to disable it,
         2112  +** or negative to leave the setting unchanged.
         2113  +** The second parameter is a pointer to an integer into which is written 
         2114  +** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if 
         2115  +** it is not disabled, 1 if it is.  
         2116  +** </dd>
         2117  +**
         2118  +** <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
         2119  +** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
         2120  +** [VACUUM] in order to reset a database back to an empty database
         2121  +** with no schema and no content. The following process works even for
         2122  +** a badly corrupted database file:
         2123  +** <ol>
         2124  +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
         2125  +** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
         2126  +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
         2127  +** </ol>
         2128  +** Because resetting a database is destructive and irreversible, the
         2129  +** process requires the use of this obscure API and multiple steps to help
         2130  +** ensure that it does not happen by accident.
         2131  +** </dd>
  1990   2132   ** </dl>
  1991   2133   */
  1992   2134   #define SQLITE_DBCONFIG_MAINDBNAME            1000 /* const char* */
  1993   2135   #define SQLITE_DBCONFIG_LOOKASIDE             1001 /* void* int int */
  1994   2136   #define SQLITE_DBCONFIG_ENABLE_FKEY           1002 /* int int* */
  1995   2137   #define SQLITE_DBCONFIG_ENABLE_TRIGGER        1003 /* int int* */
  1996   2138   #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
  1997   2139   #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
  1998         -
         2140  +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE      1006 /* int int* */
         2141  +#define SQLITE_DBCONFIG_ENABLE_QPSG           1007 /* int int* */
         2142  +#define SQLITE_DBCONFIG_TRIGGER_EQP           1008 /* int int* */
         2143  +#define SQLITE_DBCONFIG_RESET_DATABASE        1009 /* int int* */
         2144  +#define SQLITE_DBCONFIG_MAX                   1009 /* Largest DBCONFIG */
  1999   2145   
  2000   2146   /*
  2001   2147   ** CAPI3REF: Enable Or Disable Extended Result Codes
  2002   2148   ** METHOD: sqlite3
  2003   2149   **
  2004   2150   ** ^The sqlite3_extended_result_codes() routine enables or disables the
  2005   2151   ** [extended result codes] feature of SQLite. ^The extended result
................................................................................
  2015   2161   ** has a unique 64-bit signed
  2016   2162   ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
  2017   2163   ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  2018   2164   ** names are not also used by explicitly declared columns. ^If
  2019   2165   ** the table has a column of type [INTEGER PRIMARY KEY] then that column
  2020   2166   ** is another alias for the rowid.
  2021   2167   **
  2022         -** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the 
  2023         -** most recent successful [INSERT] into a rowid table or [virtual table]
  2024         -** on database connection D.
  2025         -** ^Inserts into [WITHOUT ROWID] tables are not recorded.
  2026         -** ^If no successful [INSERT]s into rowid tables
  2027         -** have ever occurred on the database connection D, 
  2028         -** then sqlite3_last_insert_rowid(D) returns zero.
         2168  +** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
         2169  +** the most recent successful [INSERT] into a rowid table or [virtual table]
         2170  +** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
         2171  +** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred 
         2172  +** on the database connection D, then sqlite3_last_insert_rowid(D) returns 
         2173  +** zero.
  2029   2174   **
  2030         -** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
  2031         -** method, then this routine will return the [rowid] of the inserted
  2032         -** row as long as the trigger or virtual table method is running.
  2033         -** But once the trigger or virtual table method ends, the value returned 
  2034         -** by this routine reverts to what it was before the trigger or virtual
  2035         -** table method began.)^
         2175  +** As well as being set automatically as rows are inserted into database
         2176  +** tables, the value returned by this function may be set explicitly by
         2177  +** [sqlite3_set_last_insert_rowid()]
         2178  +**
         2179  +** Some virtual table implementations may INSERT rows into rowid tables as
         2180  +** part of committing a transaction (e.g. to flush data accumulated in memory
         2181  +** to disk). In this case subsequent calls to this function return the rowid
         2182  +** associated with these internal INSERT operations, which leads to 
         2183  +** unintuitive results. Virtual table implementations that do write to rowid
         2184  +** tables in this way can avoid this problem by restoring the original 
         2185  +** rowid value using [sqlite3_set_last_insert_rowid()] before returning 
         2186  +** control to the user.
         2187  +**
         2188  +** ^(If an [INSERT] occurs within a trigger then this routine will 
         2189  +** return the [rowid] of the inserted row as long as the trigger is 
         2190  +** running. Once the trigger program ends, the value returned 
         2191  +** by this routine reverts to what it was before the trigger was fired.)^
  2036   2192   **
  2037   2193   ** ^An [INSERT] that fails due to a constraint violation is not a
  2038   2194   ** successful [INSERT] and does not change the value returned by this
  2039   2195   ** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  2040   2196   ** and INSERT OR ABORT make no changes to the return value of this
  2041   2197   ** routine when their insertion fails.  ^(When INSERT OR REPLACE
  2042   2198   ** encounters a constraint violation, it does not fail.  The
................................................................................
  2055   2211   ** function is running and thus changes the last insert [rowid],
  2056   2212   ** then the value returned by [sqlite3_last_insert_rowid()] is
  2057   2213   ** unpredictable and might not equal either the old or the new
  2058   2214   ** last insert [rowid].
  2059   2215   */
  2060   2216   SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  2061   2217   
         2218  +/*
         2219  +** CAPI3REF: Set the Last Insert Rowid value.
         2220  +** METHOD: sqlite3
         2221  +**
         2222  +** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
         2223  +** set the value returned by calling sqlite3_last_insert_rowid(D) to R 
         2224  +** without inserting a row into the database.
         2225  +*/
         2226  +SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
         2227  +
  2062   2228   /*
  2063   2229   ** CAPI3REF: Count The Number Of Rows Modified
  2064   2230   ** METHOD: sqlite3
  2065   2231   **
  2066   2232   ** ^This function returns the number of rows modified, inserted or
  2067   2233   ** deleted by the most recently completed INSERT, UPDATE or DELETE
  2068   2234   ** statement on the database connection specified by the only parameter.
................................................................................
  2166   2332   ** running statements reaches zero are interrupted as if they had been
  2167   2333   ** running prior to the sqlite3_interrupt() call.  ^New SQL statements
  2168   2334   ** that are started after the running statement count reaches zero are
  2169   2335   ** not effected by the sqlite3_interrupt().
  2170   2336   ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
  2171   2337   ** SQL statements is a no-op and has no effect on SQL statements
  2172   2338   ** that are started after the sqlite3_interrupt() call returns.
  2173         -**
  2174         -** If the database connection closes while [sqlite3_interrupt()]
  2175         -** is running then bad things will likely happen.
  2176   2339   */
  2177   2340   SQLITE_API void sqlite3_interrupt(sqlite3*);
  2178   2341   
  2179   2342   /*
  2180   2343   ** CAPI3REF: Determine If An SQL Statement Is Complete
  2181   2344   **
  2182   2345   ** These routines are useful during command-line input to determine if the
................................................................................
  2380   2543   SQLITE_API void sqlite3_free_table(char **result);
  2381   2544   
  2382   2545   /*
  2383   2546   ** CAPI3REF: Formatted String Printing Functions
  2384   2547   **
  2385   2548   ** These routines are work-alikes of the "printf()" family of functions
  2386   2549   ** from the standard C library.
  2387         -** These routines understand most of the common K&R formatting options,
  2388         -** plus some additional non-standard formats, detailed below.
  2389         -** Note that some of the more obscure formatting options from recent
  2390         -** C-library standards are omitted from this implementation.
         2550  +** These routines understand most of the common formatting options from
         2551  +** the standard library printf() 
         2552  +** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
         2553  +** See the [built-in printf()] documentation for details.
  2391   2554   **
  2392   2555   ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2393         -** results into memory obtained from [sqlite3_malloc()].
         2556  +** results into memory obtained from [sqlite3_malloc64()].
  2394   2557   ** The strings returned by these two routines should be
  2395   2558   ** released by [sqlite3_free()].  ^Both routines return a
  2396         -** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
         2559  +** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
  2397   2560   ** memory to hold the resulting string.
  2398   2561   **
  2399   2562   ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
  2400   2563   ** the standard C library.  The result is written into the
  2401   2564   ** buffer supplied as the second parameter whose size is given by
  2402   2565   ** the first parameter. Note that the order of the
  2403   2566   ** first two parameters is reversed from snprintf().)^  This is an
................................................................................
  2413   2576   ** guarantees that the buffer is always zero-terminated.  ^The first
  2414   2577   ** parameter "n" is the total size of the buffer, including space for
  2415   2578   ** the zero terminator.  So the longest string that can be completely
  2416   2579   ** written will be n-1 characters.
  2417   2580   **
  2418   2581   ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2419   2582   **
  2420         -** These routines all implement some additional formatting
  2421         -** options that are useful for constructing SQL statements.
  2422         -** All of the usual printf() formatting options apply.  In addition, there
  2423         -** is are "%q", "%Q", "%w" and "%z" options.
  2424         -**
  2425         -** ^(The %q option works like %s in that it substitutes a nul-terminated
  2426         -** string from the argument list.  But %q also doubles every '\'' character.
  2427         -** %q is designed for use inside a string literal.)^  By doubling each '\''
  2428         -** character it escapes that character and allows it to be inserted into
  2429         -** the string.
  2430         -**
  2431         -** For example, assume the string variable zText contains text as follows:
  2432         -**
  2433         -** <blockquote><pre>
  2434         -**  char *zText = "It's a happy day!";
  2435         -** </pre></blockquote>
  2436         -**
  2437         -** One can use this text in an SQL statement as follows:
  2438         -**
  2439         -** <blockquote><pre>
  2440         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
  2441         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2442         -**  sqlite3_free(zSQL);
  2443         -** </pre></blockquote>
  2444         -**
  2445         -** Because the %q format string is used, the '\'' character in zText
  2446         -** is escaped and the SQL generated is as follows:
  2447         -**
  2448         -** <blockquote><pre>
  2449         -**  INSERT INTO table1 VALUES('It''s a happy day!')
  2450         -** </pre></blockquote>
  2451         -**
  2452         -** This is correct.  Had we used %s instead of %q, the generated SQL
  2453         -** would have looked like this:
  2454         -**
  2455         -** <blockquote><pre>
  2456         -**  INSERT INTO table1 VALUES('It's a happy day!');
  2457         -** </pre></blockquote>
  2458         -**
  2459         -** This second example is an SQL syntax error.  As a general rule you should
  2460         -** always use %q instead of %s when inserting text into a string literal.
  2461         -**
  2462         -** ^(The %Q option works like %q except it also adds single quotes around
  2463         -** the outside of the total string.  Additionally, if the parameter in the
  2464         -** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
  2465         -** single quotes).)^  So, for example, one could say:
  2466         -**
  2467         -** <blockquote><pre>
  2468         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  2469         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2470         -**  sqlite3_free(zSQL);
  2471         -** </pre></blockquote>
  2472         -**
  2473         -** The code above will render a correct SQL statement in the zSQL
  2474         -** variable even if the zText variable is a NULL pointer.
  2475         -**
  2476         -** ^(The "%w" formatting option is like "%q" except that it expects to
  2477         -** be contained within double-quotes instead of single quotes, and it
  2478         -** escapes the double-quote character instead of the single-quote
  2479         -** character.)^  The "%w" formatting option is intended for safely inserting
  2480         -** table and column names into a constructed SQL statement.
  2481         -**
  2482         -** ^(The "%z" formatting option works like "%s" but with the
  2483         -** addition that after the string has been read and copied into
  2484         -** the result, [sqlite3_free()] is called on the input string.)^
         2583  +** See also:  [built-in printf()], [printf() SQL function]
  2485   2584   */
  2486   2585   SQLITE_API char *sqlite3_mprintf(const char*,...);
  2487   2586   SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
  2488   2587   SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
  2489   2588   SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
  2490   2589   
  2491   2590   /*
................................................................................
  2631   2730   ** method.
  2632   2731   */
  2633   2732   SQLITE_API void sqlite3_randomness(int N, void *P);
  2634   2733   
  2635   2734   /*
  2636   2735   ** CAPI3REF: Compile-Time Authorization Callbacks
  2637   2736   ** METHOD: sqlite3
         2737  +** KEYWORDS: {authorizer callback}
  2638   2738   **
  2639   2739   ** ^This routine registers an authorizer callback with a particular
  2640   2740   ** [database connection], supplied in the first argument.
  2641   2741   ** ^The authorizer callback is invoked as SQL statements are being compiled
  2642   2742   ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  2643         -** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
         2743  +** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
         2744  +** and [sqlite3_prepare16_v3()].  ^At various
  2644   2745   ** points during the compilation process, as logic is being created
  2645   2746   ** to perform various actions, the authorizer callback is invoked to
  2646   2747   ** see if those actions are allowed.  ^The authorizer callback should
  2647   2748   ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  2648   2749   ** specific action but allow the SQL statement to continue to be
  2649   2750   ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  2650   2751   ** rejected with an error.  ^If the authorizer callback returns
................................................................................
  2658   2759   ** authorizer will fail with an error message explaining that
  2659   2760   ** access is denied. 
  2660   2761   **
  2661   2762   ** ^The first parameter to the authorizer callback is a copy of the third
  2662   2763   ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
  2663   2764   ** to the callback is an integer [SQLITE_COPY | action code] that specifies
  2664   2765   ** the particular action to be authorized. ^The third through sixth parameters
  2665         -** to the callback are zero-terminated strings that contain additional
  2666         -** details about the action to be authorized.
         2766  +** to the callback are either NULL pointers or zero-terminated strings
         2767  +** that contain additional details about the action to be authorized.
         2768  +** Applications must always be prepared to encounter a NULL pointer in any
         2769  +** of the third through the sixth parameters of the authorization callback.
  2667   2770   **
  2668   2771   ** ^If the action code is [SQLITE_READ]
  2669   2772   ** and the callback returns [SQLITE_IGNORE] then the
  2670   2773   ** [prepared statement] statement is constructed to substitute
  2671   2774   ** a NULL value in place of the table column that would have
  2672   2775   ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
  2673   2776   ** return can be used to deny an untrusted user access to individual
  2674   2777   ** columns of a table.
         2778  +** ^When a table is referenced by a [SELECT] but no column values are
         2779  +** extracted from that table (for example in a query like
         2780  +** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
         2781  +** is invoked once for that table with a column name that is an empty string.
  2675   2782   ** ^If the action code is [SQLITE_DELETE] and the callback returns
  2676   2783   ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
  2677   2784   ** [truncate optimization] is disabled and all rows are deleted individually.
  2678   2785   **
  2679   2786   ** An authorizer is used when [sqlite3_prepare | preparing]
  2680   2787   ** SQL statements from an untrusted source, to ensure that the SQL statements
  2681   2788   ** do not try to access data they are not allowed to see, or that they do not
................................................................................
  2827   2934      void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  2828   2935   
  2829   2936   /*
  2830   2937   ** CAPI3REF: SQL Trace Event Codes
  2831   2938   ** KEYWORDS: SQLITE_TRACE
  2832   2939   **
  2833   2940   ** These constants identify classes of events that can be monitored
  2834         -** using the [sqlite3_trace_v2()] tracing logic.  The third argument
  2835         -** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
         2941  +** using the [sqlite3_trace_v2()] tracing logic.  The M argument
         2942  +** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
  2836   2943   ** the following constants.  ^The first argument to the trace callback
  2837   2944   ** is one of the following constants.
  2838   2945   **
  2839   2946   ** New tracing constants may be added in future releases.
  2840   2947   **
  2841   2948   ** ^A trace callback has four arguments: xCallback(T,C,P,X).
  2842   2949   ** ^The T argument is one of the integer type codes above.
................................................................................
  3037   3144   ** automatically deleted as soon as the database connection is closed.
  3038   3145   **
  3039   3146   ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
  3040   3147   **
  3041   3148   ** ^If [URI filename] interpretation is enabled, and the filename argument
  3042   3149   ** begins with "file:", then the filename is interpreted as a URI. ^URI
  3043   3150   ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
  3044         -** set in the fourth argument to sqlite3_open_v2(), or if it has
         3151  +** set in the third argument to sqlite3_open_v2(), or if it has
  3045   3152   ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
  3046   3153   ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
  3047         -** As of SQLite version 3.7.7, URI filename interpretation is turned off
         3154  +** URI filename interpretation is turned off
  3048   3155   ** by default, but future releases of SQLite might enable URI filename
  3049   3156   ** interpretation by default.  See "[URI filenames]" for additional
  3050   3157   ** information.
  3051   3158   **
  3052   3159   ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
  3053   3160   ** authority, then it must be either an empty string or the string 
  3054   3161   ** "localhost". ^If the authority is not an empty string or "localhost", an 
................................................................................
  3379   3486   ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
  3380   3487   **
  3381   3488   ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  3382   3489   ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
  3383   3490   **
  3384   3491   ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
  3385   3492   ** <dd>The maximum number of instructions in a virtual machine program
  3386         -** used to implement an SQL statement.  This limit is not currently
  3387         -** enforced, though that might be added in some future release of
  3388         -** SQLite.</dd>)^
         3493  +** used to implement an SQL statement.  If [sqlite3_prepare_v2()] or
         3494  +** the equivalent tries to allocate space for more than this many opcodes
         3495  +** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
  3389   3496   **
  3390   3497   ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  3391   3498   ** <dd>The maximum number of arguments on a function.</dd>)^
  3392   3499   **
  3393   3500   ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
  3394   3501   ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
  3395   3502   **
................................................................................
  3419   3526   #define SQLITE_LIMIT_FUNCTION_ARG              6
  3420   3527   #define SQLITE_LIMIT_ATTACHED                  7
  3421   3528   #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
  3422   3529   #define SQLITE_LIMIT_VARIABLE_NUMBER           9
  3423   3530   #define SQLITE_LIMIT_TRIGGER_DEPTH            10
  3424   3531   #define SQLITE_LIMIT_WORKER_THREADS           11
  3425   3532   
         3533  +/*
         3534  +** CAPI3REF: Prepare Flags
         3535  +**
         3536  +** These constants define various flags that can be passed into
         3537  +** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
         3538  +** [sqlite3_prepare16_v3()] interfaces.
         3539  +**
         3540  +** New flags may be added in future releases of SQLite.
         3541  +**
         3542  +** <dl>
         3543  +** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
         3544  +** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
         3545  +** that the prepared statement will be retained for a long time and
         3546  +** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
         3547  +** and [sqlite3_prepare16_v3()] assume that the prepared statement will 
         3548  +** be used just once or at most a few times and then destroyed using
         3549  +** [sqlite3_finalize()] relatively soon. The current implementation acts
         3550  +** on this hint by avoiding the use of [lookaside memory] so as not to
         3551  +** deplete the limited store of lookaside memory. Future versions of
         3552  +** SQLite may act on this hint differently.
         3553  +** </dl>
         3554  +*/
         3555  +#define SQLITE_PREPARE_PERSISTENT              0x01
         3556  +
  3426   3557   /*
  3427   3558   ** CAPI3REF: Compiling An SQL Statement
  3428   3559   ** KEYWORDS: {SQL statement compiler}
  3429   3560   ** METHOD: sqlite3
  3430   3561   ** CONSTRUCTOR: sqlite3_stmt
  3431   3562   **
  3432         -** To execute an SQL query, it must first be compiled into a byte-code
  3433         -** program using one of these routines.
         3563  +** To execute an SQL statement, it must first be compiled into a byte-code
         3564  +** program using one of these routines.  Or, in other words, these routines
         3565  +** are constructors for the [prepared statement] object.
         3566  +**
         3567  +** The preferred routine to use is [sqlite3_prepare_v2()].  The
         3568  +** [sqlite3_prepare()] interface is legacy and should be avoided.
         3569  +** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
         3570  +** for special purposes.
         3571  +**
         3572  +** The use of the UTF-8 interfaces is preferred, as SQLite currently
         3573  +** does all parsing using UTF-8.  The UTF-16 interfaces are provided
         3574  +** as a convenience.  The UTF-16 interfaces work by converting the
         3575  +** input text into UTF-8, then invoking the corresponding UTF-8 interface.
  3434   3576   **
  3435   3577   ** The first argument, "db", is a [database connection] obtained from a
  3436   3578   ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
  3437   3579   ** [sqlite3_open16()].  The database connection must not have been closed.
  3438   3580   **
  3439   3581   ** The second argument, "zSql", is the statement to be compiled, encoded
  3440         -** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
  3441         -** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
  3442         -** use UTF-16.
         3582  +** as either UTF-8 or UTF-16.  The sqlite3_prepare(), sqlite3_prepare_v2(),
         3583  +** and sqlite3_prepare_v3()
         3584  +** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
         3585  +** and sqlite3_prepare16_v3() use UTF-16.
  3443   3586   **
  3444   3587   ** ^If the nByte argument is negative, then zSql is read up to the
  3445   3588   ** first zero terminator. ^If nByte is positive, then it is the
  3446   3589   ** number of bytes read from zSql.  ^If nByte is zero, then no prepared
  3447   3590   ** statement is generated.
  3448   3591   ** If the caller knows that the supplied string is nul-terminated, then
  3449   3592   ** there is a small performance advantage to passing an nByte parameter that
................................................................................
  3462   3605   ** The calling procedure is responsible for deleting the compiled
  3463   3606   ** SQL statement using [sqlite3_finalize()] after it has finished with it.
  3464   3607   ** ppStmt may not be NULL.
  3465   3608   **
  3466   3609   ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
  3467   3610   ** otherwise an [error code] is returned.
  3468   3611   **
  3469         -** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  3470         -** recommended for all new programs. The two older interfaces are retained
  3471         -** for backwards compatibility, but their use is discouraged.
  3472         -** ^In the "v2" interfaces, the prepared statement
         3612  +** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
         3613  +** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
         3614  +** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
         3615  +** are retained for backwards compatibility, but their use is discouraged.
         3616  +** ^In the "vX" interfaces, the prepared statement
  3473   3617   ** that is returned (the [sqlite3_stmt] object) contains a copy of the
  3474   3618   ** original SQL text. This causes the [sqlite3_step()] interface to
  3475   3619   ** behave differently in three ways:
  3476   3620   **
  3477   3621   ** <ol>
  3478   3622   ** <li>
  3479   3623   ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
................................................................................
  3499   3643   ** to the [sqlite3_bind_text | bindings] of that [parameter]. 
  3500   3644   ** ^The specific value of WHERE-clause [parameter] might influence the 
  3501   3645   ** choice of query plan if the parameter is the left-hand side of a [LIKE]
  3502   3646   ** or [GLOB] operator or if the parameter is compared to an indexed column
  3503   3647   ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
  3504   3648   ** </li>
  3505   3649   ** </ol>
         3650  +**
         3651  +** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
         3652  +** the extra prepFlags parameter, which is a bit array consisting of zero or
         3653  +** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags.  ^The
         3654  +** sqlite3_prepare_v2() interface works exactly the same as
         3655  +** sqlite3_prepare_v3() with a zero prepFlags parameter.
  3506   3656   */
  3507   3657   SQLITE_API int sqlite3_prepare(
  3508   3658     sqlite3 *db,            /* Database handle */
  3509   3659     const char *zSql,       /* SQL statement, UTF-8 encoded */
  3510   3660     int nByte,              /* Maximum length of zSql in bytes. */
  3511   3661     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3512   3662     const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  3513   3663   );
  3514   3664   SQLITE_API int sqlite3_prepare_v2(
  3515   3665     sqlite3 *db,            /* Database handle */
  3516   3666     const char *zSql,       /* SQL statement, UTF-8 encoded */
  3517   3667     int nByte,              /* Maximum length of zSql in bytes. */
         3668  +  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
         3669  +  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
         3670  +);
         3671  +SQLITE_API int sqlite3_prepare_v3(
         3672  +  sqlite3 *db,            /* Database handle */
         3673  +  const char *zSql,       /* SQL statement, UTF-8 encoded */
         3674  +  int nByte,              /* Maximum length of zSql in bytes. */
         3675  +  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  3518   3676     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3519   3677     const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  3520   3678   );
  3521   3679   SQLITE_API int sqlite3_prepare16(
  3522   3680     sqlite3 *db,            /* Database handle */
  3523   3681     const void *zSql,       /* SQL statement, UTF-16 encoded */
  3524   3682     int nByte,              /* Maximum length of zSql in bytes. */
................................................................................
  3528   3686   SQLITE_API int sqlite3_prepare16_v2(
  3529   3687     sqlite3 *db,            /* Database handle */
  3530   3688     const void *zSql,       /* SQL statement, UTF-16 encoded */
  3531   3689     int nByte,              /* Maximum length of zSql in bytes. */
  3532   3690     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3533   3691     const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  3534   3692   );
         3693  +SQLITE_API int sqlite3_prepare16_v3(
         3694  +  sqlite3 *db,            /* Database handle */
         3695  +  const void *zSql,       /* SQL statement, UTF-16 encoded */
         3696  +  int nByte,              /* Maximum length of zSql in bytes. */
         3697  +  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
         3698  +  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
         3699  +  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
         3700  +);
  3535   3701   
  3536   3702   /*
  3537   3703   ** CAPI3REF: Retrieving Statement SQL
  3538   3704   ** METHOD: sqlite3_stmt
  3539   3705   **
  3540   3706   ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
  3541   3707   ** SQL text used to create [prepared statement] P if P was
  3542         -** created by either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
         3708  +** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
         3709  +** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  3543   3710   ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
  3544   3711   ** string containing the SQL text of prepared statement P with
  3545   3712   ** [bound parameters] expanded.
  3546   3713   **
  3547   3714   ** ^(For example, if a prepared statement is created using the SQL
  3548   3715   ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
  3549   3716   ** and parameter :xyz is unbound, then sqlite3_sql() will return
................................................................................
  3592   3759   ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
  3593   3760   ** since the statements themselves do not actually modify the database but
  3594   3761   ** rather they control the timing of when other statements modify the 
  3595   3762   ** database.  ^The [ATTACH] and [DETACH] statements also cause
  3596   3763   ** sqlite3_stmt_readonly() to return true since, while those statements
  3597   3764   ** change the configuration of a database connection, they do not make 
  3598   3765   ** changes to the content of the database files on disk.
         3766  +** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
         3767  +** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
         3768  +** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
         3769  +** sqlite3_stmt_readonly() returns false for those commands.
  3599   3770   */
  3600   3771   SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
  3601   3772   
  3602   3773   /*
  3603   3774   ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
  3604   3775   ** METHOD: sqlite3_stmt
  3605   3776   **
................................................................................
  3650   3821   ** still make the distinction between protected and unprotected
  3651   3822   ** sqlite3_value objects even when not strictly required.
  3652   3823   **
  3653   3824   ** ^The sqlite3_value objects that are passed as parameters into the
  3654   3825   ** implementation of [application-defined SQL functions] are protected.
  3655   3826   ** ^The sqlite3_value object returned by
  3656   3827   ** [sqlite3_column_value()] is unprotected.
  3657         -** Unprotected sqlite3_value objects may only be used with
  3658         -** [sqlite3_result_value()] and [sqlite3_bind_value()].
         3828  +** Unprotected sqlite3_value objects may only be used as arguments
         3829  +** to [sqlite3_result_value()], [sqlite3_bind_value()], and
         3830  +** [sqlite3_value_dup()].
  3659   3831   ** The [sqlite3_value_blob | sqlite3_value_type()] family of
  3660   3832   ** interfaces require protected sqlite3_value objects.
  3661   3833   */
  3662         -typedef struct Mem sqlite3_value;
         3834  +typedef struct sqlite3_value sqlite3_value;
  3663   3835   
  3664   3836   /*
  3665   3837   ** CAPI3REF: SQL Function Context Object
  3666   3838   **
  3667   3839   ** The context in which an SQL function executes is stored in an
  3668   3840   ** sqlite3_context object.  ^A pointer to an sqlite3_context object
  3669   3841   ** is always first parameter to [application-defined SQL functions].
................................................................................
  3756   3928   ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  3757   3929   ** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
  3758   3930   ** (just an integer to hold its size) while it is being processed.
  3759   3931   ** Zeroblobs are intended to serve as placeholders for BLOBs whose
  3760   3932   ** content is later written using
  3761   3933   ** [sqlite3_blob_open | incremental BLOB I/O] routines.
  3762   3934   ** ^A negative value for the zeroblob results in a zero-length BLOB.
         3935  +**
         3936  +** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
         3937  +** [prepared statement] S to have an SQL value of NULL, but to also be
         3938  +** associated with the pointer P of type T.  ^D is either a NULL pointer or
         3939  +** a pointer to a destructor function for P. ^SQLite will invoke the
         3940  +** destructor D with a single argument of P when it is finished using
         3941  +** P.  The T parameter should be a static string, preferably a string
         3942  +** literal. The sqlite3_bind_pointer() routine is part of the
         3943  +** [pointer passing interface] added for SQLite 3.20.0.
  3763   3944   **
  3764   3945   ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
  3765   3946   ** for the [prepared statement] or with a prepared statement for which
  3766   3947   ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
  3767   3948   ** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
  3768   3949   ** routine is passed a [prepared statement] that has been finalized, the
  3769   3950   ** result is undefined and probably harmful.
................................................................................
  3790   3971   SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  3791   3972   SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
  3792   3973   SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
  3793   3974   SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  3794   3975   SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
  3795   3976                            void(*)(void*), unsigned char encoding);
  3796   3977   SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
         3978  +SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
  3797   3979   SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  3798   3980   SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
  3799   3981   
  3800   3982   /*
  3801   3983   ** CAPI3REF: Number Of SQL Parameters
  3802   3984   ** METHOD: sqlite3_stmt
  3803   3985   **
................................................................................
  3833   4015   ** and are referred to as "nameless" or "anonymous parameters".
  3834   4016   **
  3835   4017   ** ^The first host parameter has an index of 1, not 0.
  3836   4018   **
  3837   4019   ** ^If the value N is out of range or if the N-th parameter is
  3838   4020   ** nameless, then NULL is returned.  ^The returned string is
  3839   4021   ** always in UTF-8 encoding even if the named parameter was
  3840         -** originally specified as UTF-16 in [sqlite3_prepare16()] or
  3841         -** [sqlite3_prepare16_v2()].
         4022  +** originally specified as UTF-16 in [sqlite3_prepare16()],
         4023  +** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  3842   4024   **
  3843   4025   ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3844   4026   ** [sqlite3_bind_parameter_count()], and
  3845   4027   ** [sqlite3_bind_parameter_index()].
  3846   4028   */
  3847   4029   SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  3848   4030   
................................................................................
  3851   4033   ** METHOD: sqlite3_stmt
  3852   4034   **
  3853   4035   ** ^Return the index of an SQL parameter given its name.  ^The
  3854   4036   ** index value returned is suitable for use as the second
  3855   4037   ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
  3856   4038   ** is returned if no matching parameter is found.  ^The parameter
  3857   4039   ** name must be given in UTF-8 even if the original statement
  3858         -** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
         4040  +** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
         4041  +** [sqlite3_prepare16_v3()].
  3859   4042   **
  3860   4043   ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3861   4044   ** [sqlite3_bind_parameter_count()], and
  3862   4045   ** [sqlite3_bind_parameter_name()].
  3863   4046   */
  3864   4047   SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  3865   4048   
................................................................................
  3874   4057   SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
  3875   4058   
  3876   4059   /*
  3877   4060   ** CAPI3REF: Number Of Columns In A Result Set
  3878   4061   ** METHOD: sqlite3_stmt
  3879   4062   **
  3880   4063   ** ^Return the number of columns in the result set returned by the
  3881         -** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
  3882         -** statement that does not return data (for example an [UPDATE]).
         4064  +** [prepared statement]. ^If this routine returns 0, that means the 
         4065  +** [prepared statement] returns no data (for example an [UPDATE]).
         4066  +** ^However, just because this routine returns a positive number does not
         4067  +** mean that one or more rows of data will be returned.  ^A SELECT statement
         4068  +** will always have a positive sqlite3_column_count() but depending on the
         4069  +** WHERE clause constraints and the table content, it might return no rows.
  3883   4070   **
  3884   4071   ** See also: [sqlite3_data_count()]
  3885   4072   */
  3886   4073   SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
  3887   4074   
  3888   4075   /*
  3889   4076   ** CAPI3REF: Column Names In A Result Set
................................................................................
  4001   4188   SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  4002   4189   SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  4003   4190   
  4004   4191   /*
  4005   4192   ** CAPI3REF: Evaluate An SQL Statement
  4006   4193   ** METHOD: sqlite3_stmt
  4007   4194   **
  4008         -** After a [prepared statement] has been prepared using either
  4009         -** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
         4195  +** After a [prepared statement] has been prepared using any of
         4196  +** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
         4197  +** or [sqlite3_prepare16_v3()] or one of the legacy
  4010   4198   ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
  4011   4199   ** must be called one or more times to evaluate the statement.
  4012   4200   **
  4013   4201   ** The details of the behavior of the sqlite3_step() interface depend
  4014         -** on whether the statement was prepared using the newer "v2" interface
  4015         -** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
  4016         -** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
  4017         -** new "v2" interface is recommended for new applications but the legacy
         4202  +** on whether the statement was prepared using the newer "vX" interfaces
         4203  +** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
         4204  +** [sqlite3_prepare16_v2()] or the older legacy
         4205  +** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
         4206  +** new "vX" interface is recommended for new applications but the legacy
  4018   4207   ** interface will continue to be supported.
  4019   4208   **
  4020   4209   ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
  4021   4210   ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  4022   4211   ** ^With the "v2" interface, any of the other [result codes] or
  4023   4212   ** [extended result codes] might be returned as well.
  4024   4213   **
................................................................................
  4071   4260   ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
  4072   4261   ** API always returns a generic error code, [SQLITE_ERROR], following any
  4073   4262   ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
  4074   4263   ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
  4075   4264   ** specific [error codes] that better describes the error.
  4076   4265   ** We admit that this is a goofy design.  The problem has been fixed
  4077   4266   ** with the "v2" interface.  If you prepare all of your SQL statements
  4078         -** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
         4267  +** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
         4268  +** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
  4079   4269   ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
  4080   4270   ** then the more specific [error codes] are returned directly
  4081         -** by sqlite3_step().  The use of the "v2" interface is recommended.
         4271  +** by sqlite3_step().  The use of the "vX" interfaces is recommended.
  4082   4272   */
  4083   4273   SQLITE_API int sqlite3_step(sqlite3_stmt*);
  4084   4274   
  4085   4275   /*
  4086   4276   ** CAPI3REF: Number of columns in a result set
  4087   4277   ** METHOD: sqlite3_stmt
  4088   4278   **
................................................................................
  4135   4325   #endif
  4136   4326   #define SQLITE3_TEXT     3
  4137   4327   
  4138   4328   /*
  4139   4329   ** CAPI3REF: Result Values From A Query
  4140   4330   ** KEYWORDS: {column access functions}
  4141   4331   ** METHOD: sqlite3_stmt
         4332  +**
         4333  +** <b>Summary:</b>
         4334  +** <blockquote><table border=0 cellpadding=0 cellspacing=0>
         4335  +** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
         4336  +** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
         4337  +** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
         4338  +** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
         4339  +** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
         4340  +** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
         4341  +** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an 
         4342  +** [sqlite3_value|unprotected sqlite3_value] object.
         4343  +** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
         4344  +** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
         4345  +** or a UTF-8 TEXT result in bytes
         4346  +** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
         4347  +** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
         4348  +** TEXT in bytes
         4349  +** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
         4350  +** datatype of the result
         4351  +** </table></blockquote>
         4352  +**
         4353  +** <b>Details:</b>
  4142   4354   **
  4143   4355   ** ^These routines return information about a single column of the current
  4144   4356   ** result row of a query.  ^In every case the first argument is a pointer
  4145   4357   ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  4146   4358   ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  4147   4359   ** and the second argument is the index of the column for which information
  4148   4360   ** should be returned. ^The leftmost column of the result set has the index 0.
................................................................................
  4157   4369   ** If any of these routines are called after [sqlite3_reset()] or
  4158   4370   ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  4159   4371   ** something other than [SQLITE_ROW], the results are undefined.
  4160   4372   ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  4161   4373   ** are called from a different thread while any of these routines
  4162   4374   ** are pending, then the results are undefined.
  4163   4375   **
         4376  +** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
         4377  +** each return the value of a result column in a specific data format.  If
         4378  +** the result column is not initially in the requested format (for example,
         4379  +** if the query returns an integer but the sqlite3_column_text() interface
         4380  +** is used to extract the value) then an automatic type conversion is performed.
         4381  +**
  4164   4382   ** ^The sqlite3_column_type() routine returns the
  4165   4383   ** [SQLITE_INTEGER | datatype code] for the initial data type
  4166   4384   ** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
  4167         -** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
  4168         -** returned by sqlite3_column_type() is only meaningful if no type
  4169         -** conversions have occurred as described below.  After a type conversion,
  4170         -** the value returned by sqlite3_column_type() is undefined.  Future
         4385  +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
         4386  +** The return value of sqlite3_column_type() can be used to decide which
         4387  +** of the first six interface should be used to extract the column value.
         4388  +** The value returned by sqlite3_column_type() is only meaningful if no
         4389  +** automatic type conversions have occurred for the value in question.  
         4390  +** After a type conversion, the result of calling sqlite3_column_type()
         4391  +** is undefined, though harmless.  Future
  4171   4392   ** versions of SQLite may change the behavior of sqlite3_column_type()
  4172   4393   ** following a type conversion.
         4394  +**
         4395  +** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
         4396  +** or sqlite3_column_bytes16() interfaces can be used to determine the size
         4397  +** of that BLOB or string.
  4173   4398   **
  4174   4399   ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
  4175   4400   ** routine returns the number of bytes in that BLOB or string.
  4176   4401   ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  4177   4402   ** the string to UTF-8 and then returns the number of bytes.
  4178   4403   ** ^If the result is a numeric value then sqlite3_column_bytes() uses
  4179   4404   ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
................................................................................
  4203   4428   ** [unprotected sqlite3_value] object.  In a multithreaded environment,
  4204   4429   ** an unprotected sqlite3_value object may only be used safely with
  4205   4430   ** [sqlite3_bind_value()] and [sqlite3_result_value()].
  4206   4431   ** If the [unprotected sqlite3_value] object returned by
  4207   4432   ** [sqlite3_column_value()] is used in any other way, including calls
  4208   4433   ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  4209   4434   ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
         4435  +** Hence, the sqlite3_column_value() interface
         4436  +** is normally only useful within the implementation of 
         4437  +** [application-defined SQL functions] or [virtual tables], not within
         4438  +** top-level application code.
  4210   4439   **
  4211         -** These routines attempt to convert the value where appropriate.  ^For
  4212         -** example, if the internal representation is FLOAT and a text result
         4440  +** The these routines may attempt to convert the datatype of the result.
         4441  +** ^For example, if the internal representation is FLOAT and a text result
  4213   4442   ** is requested, [sqlite3_snprintf()] is used internally to perform the
  4214   4443   ** conversion automatically.  ^(The following table details the conversions
  4215   4444   ** that are applied:
  4216   4445   **
  4217   4446   ** <blockquote>
  4218   4447   ** <table border="1">
  4219   4448   ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
................................................................................
  4277   4506   ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  4278   4507   ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  4279   4508   ** with calls to sqlite3_column_bytes().
  4280   4509   **
  4281   4510   ** ^The pointers returned are valid until a type conversion occurs as
  4282   4511   ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  4283   4512   ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
  4284         -** and BLOBs is freed automatically.  Do <em>not</em> pass the pointers returned
         4513  +** and BLOBs is freed automatically.  Do not pass the pointers returned
  4285   4514   ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  4286   4515   ** [sqlite3_free()].
  4287   4516   **
  4288   4517   ** ^(If a memory allocation error occurs during the evaluation of any
  4289   4518   ** of these routines, a default value is returned.  The default value
  4290   4519   ** is either the integer 0, the floating point number 0.0, or a NULL
  4291   4520   ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  4292   4521   ** [SQLITE_NOMEM].)^
  4293   4522   */
  4294   4523   SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  4295         -SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  4296         -SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  4297   4524   SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
  4298   4525   SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
  4299   4526   SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  4300   4527   SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  4301   4528   SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  4302         -SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  4303   4529   SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
         4530  +SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
         4531  +SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
         4532  +SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  4304   4533   
  4305   4534   /*
  4306   4535   ** CAPI3REF: Destroy A Prepared Statement Object
  4307   4536   ** DESTRUCTOR: sqlite3_stmt
  4308   4537   **
  4309   4538   ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
  4310   4539   ** ^If the most recent evaluation of the statement encountered no errors
................................................................................
  4530   4759                         void*,sqlite3_int64);
  4531   4760   #endif
  4532   4761   
  4533   4762   /*
  4534   4763   ** CAPI3REF: Obtaining SQL Values
  4535   4764   ** METHOD: sqlite3_value
  4536   4765   **
  4537         -** The C-language implementation of SQL functions and aggregates uses
  4538         -** this set of interface routines to access the parameter values on
  4539         -** the function or aggregate.  
         4766  +** <b>Summary:</b>
         4767  +** <blockquote><table border=0 cellpadding=0 cellspacing=0>
         4768  +** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
         4769  +** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
         4770  +** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
         4771  +** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
         4772  +** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
         4773  +** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
         4774  +** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
         4775  +** the native byteorder
         4776  +** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
         4777  +** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
         4778  +** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
         4779  +** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
         4780  +** or a UTF-8 TEXT in bytes
         4781  +** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
         4782  +** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
         4783  +** TEXT in bytes
         4784  +** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
         4785  +** datatype of the value
         4786  +** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
         4787  +** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
         4788  +** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
         4789  +** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
         4790  +** against a virtual table.
         4791  +** </table></blockquote>
  4540   4792   **
  4541         -** The xFunc (for scalar functions) or xStep (for aggregates) parameters
  4542         -** to [sqlite3_create_function()] and [sqlite3_create_function16()]
  4543         -** define callbacks that implement the SQL functions and aggregates.
  4544         -** The 3rd parameter to these callbacks is an array of pointers to
  4545         -** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
  4546         -** each parameter to the SQL function.  These routines are used to
  4547         -** extract values from the [sqlite3_value] objects.
         4793  +** <b>Details:</b>
         4794  +**
         4795  +** These routines extract type, size, and content information from
         4796  +** [protected sqlite3_value] objects.  Protected sqlite3_value objects
         4797  +** are used to pass parameter information into implementation of
         4798  +** [application-defined SQL functions] and [virtual tables].
  4548   4799   **
  4549   4800   ** These routines work only with [protected sqlite3_value] objects.
  4550   4801   ** Any attempt to use these routines on an [unprotected sqlite3_value]
  4551         -** object results in undefined behavior.
         4802  +** is not threadsafe.
  4552   4803   **
  4553   4804   ** ^These routines work just like the corresponding [column access functions]
  4554   4805   ** except that these routines take a single [protected sqlite3_value] object
  4555   4806   ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
  4556   4807   **
  4557   4808   ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
  4558   4809   ** in the native byte-order of the host machine.  ^The
  4559   4810   ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  4560   4811   ** extract UTF-16 strings as big-endian and little-endian respectively.
  4561   4812   **
         4813  +** ^If [sqlite3_value] object V was initialized 
         4814  +** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
         4815  +** and if X and Y are strings that compare equal according to strcmp(X,Y),
         4816  +** then sqlite3_value_pointer(V,Y) will return the pointer P.  ^Otherwise,
         4817  +** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer() 
         4818  +** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
         4819  +**
         4820  +** ^(The sqlite3_value_type(V) interface returns the
         4821  +** [SQLITE_INTEGER | datatype code] for the initial datatype of the
         4822  +** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
         4823  +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
         4824  +** Other interfaces might change the datatype for an sqlite3_value object.
         4825  +** For example, if the datatype is initially SQLITE_INTEGER and
         4826  +** sqlite3_value_text(V) is called to extract a text value for that
         4827  +** integer, then subsequent calls to sqlite3_value_type(V) might return
         4828  +** SQLITE_TEXT.  Whether or not a persistent internal datatype conversion
         4829  +** occurs is undefined and may change from one release of SQLite to the next.
         4830  +**
  4562   4831   ** ^(The sqlite3_value_numeric_type() interface attempts to apply
  4563   4832   ** numeric affinity to the value.  This means that an attempt is
  4564   4833   ** made to convert the value to an integer or floating point.  If
  4565   4834   ** such a conversion is possible without loss of information (in other
  4566   4835   ** words, if the value is a string that looks like a number)
  4567   4836   ** then the conversion is performed.  Otherwise no conversion occurs.
  4568   4837   ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
         4838  +**
         4839  +** ^Within the [xUpdate] method of a [virtual table], the
         4840  +** sqlite3_value_nochange(X) interface returns true if and only if
         4841  +** the column corresponding to X is unchanged by the UPDATE operation
         4842  +** that the xUpdate method call was invoked to implement and if
         4843  +** and the prior [xColumn] method call that was invoked to extracted
         4844  +** the value for that column returned without setting a result (probably
         4845  +** because it queried [sqlite3_vtab_nochange()] and found that the column
         4846  +** was unchanging).  ^Within an [xUpdate] method, any value for which
         4847  +** sqlite3_value_nochange(X) is true will in all other respects appear
         4848  +** to be a NULL value.  If sqlite3_value_nochange(X) is invoked anywhere other
         4849  +** than within an [xUpdate] method call for an UPDATE statement, then
         4850  +** the return value is arbitrary and meaningless.
  4569   4851   **
  4570   4852   ** Please pay particular attention to the fact that the pointer returned
  4571   4853   ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  4572   4854   ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  4573   4855   ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  4574   4856   ** or [sqlite3_value_text16()].
  4575   4857   **
  4576   4858   ** These routines must be called from the same thread as
  4577   4859   ** the SQL function that supplied the [sqlite3_value*] parameters.
  4578   4860   */
  4579   4861   SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
  4580         -SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
  4581         -SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  4582   4862   SQLITE_API double sqlite3_value_double(sqlite3_value*);
  4583   4863   SQLITE_API int sqlite3_value_int(sqlite3_value*);
  4584   4864   SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
         4865  +SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
  4585   4866   SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
  4586   4867   SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
  4587   4868   SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
  4588   4869   SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
         4870  +SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
         4871  +SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  4589   4872   SQLITE_API int sqlite3_value_type(sqlite3_value*);
  4590   4873   SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
         4874  +SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
  4591   4875   
  4592   4876   /*
  4593   4877   ** CAPI3REF: Finding The Subtype Of SQL Values
  4594   4878   ** METHOD: sqlite3_value
  4595   4879   **
  4596   4880   ** The sqlite3_value_subtype(V) function returns the subtype for
  4597   4881   ** an [application-defined SQL function] argument V.  The subtype
  4598   4882   ** information can be used to pass a limited amount of context from
  4599   4883   ** one SQL function to another.  Use the [sqlite3_result_subtype()]
  4600   4884   ** routine to set the subtype for the return value of an SQL function.
  4601         -**
  4602         -** SQLite makes no use of subtype itself.  It merely passes the subtype
  4603         -** from the result of one [application-defined SQL function] into the
  4604         -** input of another.
  4605   4885   */
  4606   4886   SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
  4607   4887   
  4608   4888   /*
  4609   4889   ** CAPI3REF: Copy And Free SQL Values
  4610   4890   ** METHOD: sqlite3_value
  4611   4891   **
................................................................................
  4705   4985   ** of where this might be useful is in a regular-expression matching
  4706   4986   ** function. The compiled version of the regular expression can be stored as
  4707   4987   ** metadata associated with the pattern string.  
  4708   4988   ** Then as long as the pattern string remains the same,
  4709   4989   ** the compiled regular expression can be reused on multiple
  4710   4990   ** invocations of the same function.
  4711   4991   **
  4712         -** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
  4713         -** associated by the sqlite3_set_auxdata() function with the Nth argument
  4714         -** value to the application-defined function. ^If there is no metadata
  4715         -** associated with the function argument, this sqlite3_get_auxdata() interface
         4992  +** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
         4993  +** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
         4994  +** value to the application-defined function.  ^N is zero for the left-most
         4995  +** function argument.  ^If there is no metadata
         4996  +** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
  4716   4997   ** returns a NULL pointer.
  4717   4998   **
  4718   4999   ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
  4719   5000   ** argument of the application-defined function.  ^Subsequent
  4720   5001   ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
  4721   5002   ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
  4722   5003   ** NULL if the metadata has been discarded.
................................................................................
  4738   5019   ** should be called near the end of the function implementation and the
  4739   5020   ** function implementation should not make any use of P after
  4740   5021   ** sqlite3_set_auxdata() has been called.
  4741   5022   **
  4742   5023   ** ^(In practice, metadata is preserved between function calls for
  4743   5024   ** function parameters that are compile-time constants, including literal
  4744   5025   ** values and [parameters] and expressions composed from the same.)^
         5026  +**
         5027  +** The value of the N parameter to these interfaces should be non-negative.
         5028  +** Future enhancements may make use of negative N values to define new
         5029  +** kinds of function caching behavior.
  4745   5030   **
  4746   5031   ** These routines must be called from the same thread in which
  4747   5032   ** the SQL function is running.
  4748   5033   */
  4749   5034   SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
  4750   5035   SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  4751   5036   
................................................................................
  4862   5147   ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
  4863   5148   ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
  4864   5149   ** assumes that the text or BLOB result is in constant space and does not
  4865   5150   ** copy the content of the parameter nor call a destructor on the content
  4866   5151   ** when it has finished using that result.
  4867   5152   ** ^If the 4th parameter to the sqlite3_result_text* interfaces
  4868   5153   ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  4869         -** then SQLite makes a copy of the result into space obtained from
         5154  +** then SQLite makes a copy of the result into space obtained
  4870   5155   ** from [sqlite3_malloc()] before it returns.
  4871   5156   **
  4872   5157   ** ^The sqlite3_result_value() interface sets the result of
  4873   5158   ** the application-defined function to be a copy of the
  4874   5159   ** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
  4875   5160   ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  4876   5161   ** so that the [sqlite3_value] specified in the parameter may change or
  4877   5162   ** be deallocated after sqlite3_result_value() returns without harm.
  4878   5163   ** ^A [protected sqlite3_value] object may always be used where an
  4879   5164   ** [unprotected sqlite3_value] object is required, so either
  4880   5165   ** kind of [sqlite3_value] object can be used with this interface.
  4881   5166   **
         5167  +** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
         5168  +** SQL NULL value, just like [sqlite3_result_null(C)], except that it
         5169  +** also associates the host-language pointer P or type T with that 
         5170  +** NULL value such that the pointer can be retrieved within an
         5171  +** [application-defined SQL function] using [sqlite3_value_pointer()].
         5172  +** ^If the D parameter is not NULL, then it is a pointer to a destructor
         5173  +** for the P parameter.  ^SQLite invokes D with P as its only argument
         5174  +** when SQLite is finished with P.  The T parameter should be a static
         5175  +** string and preferably a string literal. The sqlite3_result_pointer()
         5176  +** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
         5177  +**
  4882   5178   ** If these routines are called from within the different thread
  4883   5179   ** than the one containing the application-defined function that received
  4884   5180   ** the [sqlite3_context] pointer, the results are undefined.
  4885   5181   */
  4886   5182   SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  4887   5183   SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
  4888   5184                              sqlite3_uint64,void(*)(void*));
................................................................................
  4898   5194   SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
  4899   5195   SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
  4900   5196                              void(*)(void*), unsigned char encoding);
  4901   5197   SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  4902   5198   SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  4903   5199   SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  4904   5200   SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
         5201  +SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
  4905   5202   SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
  4906   5203   SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
  4907   5204   
  4908   5205   
  4909   5206   /*
  4910   5207   ** CAPI3REF: Setting The Subtype Of An SQL Function
  4911   5208   ** METHOD: sqlite3_context
................................................................................
  5226   5523   ** using [sqlite3_free].
  5227   5524   ** Hence, if this variable is modified directly, either it should be
  5228   5525   ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  5229   5526   ** or else the use of the [data_store_directory pragma] should be avoided.
  5230   5527   */
  5231   5528   SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
  5232   5529   
         5530  +/*
         5531  +** CAPI3REF: Win32 Specific Interface
         5532  +**
         5533  +** These interfaces are available only on Windows.  The
         5534  +** [sqlite3_win32_set_directory] interface is used to set the value associated
         5535  +** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
         5536  +** zValue, depending on the value of the type parameter.  The zValue parameter
         5537  +** should be NULL to cause the previous value to be freed via [sqlite3_free];
         5538  +** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
         5539  +** prior to being used.  The [sqlite3_win32_set_directory] interface returns
         5540  +** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
         5541  +** or [SQLITE_NOMEM] if memory could not be allocated.  The value of the
         5542  +** [sqlite3_data_directory] variable is intended to act as a replacement for
         5543  +** the current directory on the sub-platforms of Win32 where that concept is
         5544  +** not present, e.g. WinRT and UWP.  The [sqlite3_win32_set_directory8] and
         5545  +** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
         5546  +** sqlite3_win32_set_directory interface except the string parameter must be
         5547  +** UTF-8 or UTF-16, respectively.
         5548  +*/
         5549  +SQLITE_API int sqlite3_win32_set_directory(
         5550  +  unsigned long type, /* Identifier for directory being set or reset */
         5551  +  void *zValue        /* New value for directory being set or reset */
         5552  +);
         5553  +SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
         5554  +SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
         5555  +
         5556  +/*
         5557  +** CAPI3REF: Win32 Directory Types
         5558  +**
         5559  +** These macros are only available on Windows.  They define the allowed values
         5560  +** for the type argument to the [sqlite3_win32_set_directory] interface.
         5561  +*/
         5562  +#define SQLITE_WIN32_DATA_DIRECTORY_TYPE  1
         5563  +#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  2
         5564  +
  5233   5565   /*
  5234   5566   ** CAPI3REF: Test For Auto-Commit Mode
  5235   5567   ** KEYWORDS: {autocommit mode}
  5236   5568   ** METHOD: sqlite3
  5237   5569   **
  5238   5570   ** ^The sqlite3_get_autocommit() interface returns non-zero or
  5239   5571   ** zero if the given database connection is or is not in autocommit mode,
................................................................................
  5384   5716   ** ^In the case of an update, this is the [rowid] after the update takes place.
  5385   5717   **
  5386   5718   ** ^(The update hook is not invoked when internal system tables are
  5387   5719   ** modified (i.e. sqlite_master and sqlite_sequence).)^
  5388   5720   ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
  5389   5721   **
  5390   5722   ** ^In the current implementation, the update hook
  5391         -** is not invoked when duplication rows are deleted because of an
         5723  +** is not invoked when conflicting rows are deleted because of an
  5392   5724   ** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
  5393   5725   ** invoked when rows are deleted using the [truncate optimization].
  5394   5726   ** The exceptions defined in this paragraph might change in a future
  5395   5727   ** release of SQLite.
  5396   5728   **
  5397   5729   ** The update hook implementation must not do anything that will modify
  5398   5730   ** the database connection that invoked the update hook.  Any actions
................................................................................
  5557   5889   ** interface returns SQLITE_OK and fills in the non-NULL pointers in
  5558   5890   ** the final five arguments with appropriate values if the specified
  5559   5891   ** column exists.  ^The sqlite3_table_column_metadata() interface returns
  5560   5892   ** SQLITE_ERROR and if the specified column does not exist.
  5561   5893   ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
  5562   5894   ** NULL pointer, then this routine simply checks for the existence of the
  5563   5895   ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
  5564         -** does not.
         5896  +** does not.  If the table name parameter T in a call to
         5897  +** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
         5898  +** undefined behavior.
  5565   5899   **
  5566   5900   ** ^The column is identified by the second, third and fourth parameters to
  5567   5901   ** this function. ^(The second parameter is either the name of the database
  5568   5902   ** (i.e. "main", "temp", or an attached database) containing the specified
  5569   5903   ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
  5570   5904   ** for the table using the same algorithm used by the database engine to
  5571   5905   ** resolve unqualified table references.
................................................................................
  5956   6290     int idxFlags;              /* Mask of SQLITE_INDEX_SCAN_* flags */
  5957   6291     /* Fields below are only available in SQLite 3.10.0 and later */
  5958   6292     sqlite3_uint64 colUsed;    /* Input: Mask of columns used by statement */
  5959   6293   };
  5960   6294   
  5961   6295   /*
  5962   6296   ** CAPI3REF: Virtual Table Scan Flags
         6297  +**
         6298  +** Virtual table implementations are allowed to set the 
         6299  +** [sqlite3_index_info].idxFlags field to some combination of
         6300  +** these bits.
  5963   6301   */
  5964   6302   #define SQLITE_INDEX_SCAN_UNIQUE      1     /* Scan visits at most 1 row */
  5965   6303   
  5966   6304   /*
  5967   6305   ** CAPI3REF: Virtual Table Constraint Operator Codes
  5968   6306   **
  5969   6307   ** These macros defined the allowed values for the
  5970   6308   ** [sqlite3_index_info].aConstraint[].op field.  Each value represents
  5971   6309   ** an operator that is part of a constraint term in the wHERE clause of
  5972   6310   ** a query that uses a [virtual table].
  5973   6311   */
  5974         -#define SQLITE_INDEX_CONSTRAINT_EQ      2
  5975         -#define SQLITE_INDEX_CONSTRAINT_GT      4
  5976         -#define SQLITE_INDEX_CONSTRAINT_LE      8
  5977         -#define SQLITE_INDEX_CONSTRAINT_LT     16
  5978         -#define SQLITE_INDEX_CONSTRAINT_GE     32
  5979         -#define SQLITE_INDEX_CONSTRAINT_MATCH  64
  5980         -#define SQLITE_INDEX_CONSTRAINT_LIKE   65
  5981         -#define SQLITE_INDEX_CONSTRAINT_GLOB   66
  5982         -#define SQLITE_INDEX_CONSTRAINT_REGEXP 67
         6312  +#define SQLITE_INDEX_CONSTRAINT_EQ         2
         6313  +#define SQLITE_INDEX_CONSTRAINT_GT         4
         6314  +#define SQLITE_INDEX_CONSTRAINT_LE         8
         6315  +#define SQLITE_INDEX_CONSTRAINT_LT        16
         6316  +#define SQLITE_INDEX_CONSTRAINT_GE        32
         6317  +#define SQLITE_INDEX_CONSTRAINT_MATCH     64
         6318  +#define SQLITE_INDEX_CONSTRAINT_LIKE      65
         6319  +#define SQLITE_INDEX_CONSTRAINT_GLOB      66
         6320  +#define SQLITE_INDEX_CONSTRAINT_REGEXP    67
         6321  +#define SQLITE_INDEX_CONSTRAINT_NE        68
         6322  +#define SQLITE_INDEX_CONSTRAINT_ISNOT     69
         6323  +#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
         6324  +#define SQLITE_INDEX_CONSTRAINT_ISNULL    71
         6325  +#define SQLITE_INDEX_CONSTRAINT_IS        72
  5983   6326   
  5984   6327   /*
  5985   6328   ** CAPI3REF: Register A Virtual Table Implementation
  5986   6329   ** METHOD: sqlite3
  5987   6330   **
  5988   6331   ** ^These routines are used to register a new [virtual table module] name.
  5989   6332   ** ^Module names must be registered before
................................................................................
  6166   6509   **         being opened for read/write access)^.
  6167   6510   ** </ul>
  6168   6511   **
  6169   6512   ** ^Unless it returns SQLITE_MISUSE, this function sets the 
  6170   6513   ** [database connection] error code and message accessible via 
  6171   6514   ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. 
  6172   6515   **
         6516  +** A BLOB referenced by sqlite3_blob_open() may be read using the
         6517  +** [sqlite3_blob_read()] interface and modified by using
         6518  +** [sqlite3_blob_write()].  The [BLOB handle] can be moved to a
         6519  +** different row of the same table using the [sqlite3_blob_reopen()]
         6520  +** interface.  However, the column, table, or database of a [BLOB handle]
         6521  +** cannot be changed after the [BLOB handle] is opened.
  6173   6522   **
  6174   6523   ** ^(If the row that a BLOB handle points to is modified by an
  6175   6524   ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
  6176   6525   ** then the BLOB handle is marked as "expired".
  6177   6526   ** This is true if any column of the row is changed, even a column
  6178   6527   ** other than the one the BLOB handle is open on.)^
  6179   6528   ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
................................................................................
  6189   6538   **
  6190   6539   ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
  6191   6540   ** and the built-in [zeroblob] SQL function may be used to create a 
  6192   6541   ** zero-filled blob to read or write using the incremental-blob interface.
  6193   6542   **
  6194   6543   ** To avoid a resource leak, every open [BLOB handle] should eventually
  6195   6544   ** be released by a call to [sqlite3_blob_close()].
         6545  +**
         6546  +** See also: [sqlite3_blob_close()],
         6547  +** [sqlite3_blob_reopen()], [sqlite3_blob_read()],
         6548  +** [sqlite3_blob_bytes()], [sqlite3_blob_write()].
  6196   6549   */
  6197   6550   SQLITE_API int sqlite3_blob_open(
  6198   6551     sqlite3*,
  6199   6552     const char *zDb,
  6200   6553     const char *zTable,
  6201   6554     const char *zColumn,
  6202   6555     sqlite3_int64 iRow,
................................................................................
  6204   6557     sqlite3_blob **ppBlob
  6205   6558   );
  6206   6559   
  6207   6560   /*
  6208   6561   ** CAPI3REF: Move a BLOB Handle to a New Row
  6209   6562   ** METHOD: sqlite3_blob
  6210   6563   **
  6211         -** ^This function is used to move an existing blob handle so that it points
         6564  +** ^This function is used to move an existing [BLOB handle] so that it points
  6212   6565   ** to a different row of the same database table. ^The new row is identified
  6213   6566   ** by the rowid value passed as the second argument. Only the row can be
  6214   6567   ** changed. ^The database, table and column on which the blob handle is open
  6215         -** remain the same. Moving an existing blob handle to a new row can be
         6568  +** remain the same. Moving an existing [BLOB handle] to a new row is
  6216   6569   ** faster than closing the existing handle and opening a new one.
  6217   6570   **
  6218   6571   ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
  6219   6572   ** it must exist and there must be either a blob or text value stored in
  6220   6573   ** the nominated column.)^ ^If the new row is not present in the table, or if
  6221   6574   ** it does not contain a blob or text value, or if another error occurs, an
  6222   6575   ** SQLite error code is returned and the blob handle is considered aborted.
................................................................................
  6656   7009   ** ^A NULL pointer can be used in place of "main" to refer to the
  6657   7010   ** main database file.
  6658   7011   ** ^The third and fourth parameters to this routine
  6659   7012   ** are passed directly through to the second and third parameters of
  6660   7013   ** the xFileControl method.  ^The return value of the xFileControl
  6661   7014   ** method becomes the return value of this routine.
  6662   7015   **
  6663         -** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
         7016  +** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes
  6664   7017   ** a pointer to the underlying [sqlite3_file] object to be written into
  6665         -** the space pointed to by the 4th parameter.  ^The SQLITE_FCNTL_FILE_POINTER
         7018  +** the space pointed to by the 4th parameter.  ^The [SQLITE_FCNTL_FILE_POINTER]
  6666   7019   ** case is a short-circuit path which does not actually invoke the
  6667   7020   ** underlying sqlite3_io_methods.xFileControl method.
  6668   7021   **
  6669   7022   ** ^If the second parameter (zDbName) does not match the name of any
  6670   7023   ** open database file, then SQLITE_ERROR is returned.  ^This error
  6671   7024   ** code is not remembered and will not be recalled by [sqlite3_errcode()]
  6672   7025   ** or [sqlite3_errmsg()].  The underlying xFileControl method might
  6673   7026   ** also return SQLITE_ERROR.  There is no way to distinguish between
  6674   7027   ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
  6675   7028   ** xFileControl method.
  6676   7029   **
  6677         -** See also: [SQLITE_FCNTL_LOCKSTATE]
         7030  +** See also: [file control opcodes]
  6678   7031   */
  6679   7032   SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
  6680   7033   
  6681   7034   /*
  6682   7035   ** CAPI3REF: Testing Interface
  6683   7036   **
  6684   7037   ** ^The sqlite3_test_control() interface is used to read out internal
................................................................................
  6716   7069   #define SQLITE_TESTCTRL_FAULT_INSTALL            9
  6717   7070   #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
  6718   7071   #define SQLITE_TESTCTRL_PENDING_BYTE            11
  6719   7072   #define SQLITE_TESTCTRL_ASSERT                  12
  6720   7073   #define SQLITE_TESTCTRL_ALWAYS                  13
  6721   7074   #define SQLITE_TESTCTRL_RESERVE                 14
  6722   7075   #define SQLITE_TESTCTRL_OPTIMIZATIONS           15
  6723         -#define SQLITE_TESTCTRL_ISKEYWORD               16
  6724         -#define SQLITE_TESTCTRL_SCRATCHMALLOC           17
         7076  +#define SQLITE_TESTCTRL_ISKEYWORD               16  /* NOT USED */
         7077  +#define SQLITE_TESTCTRL_SCRATCHMALLOC           17  /* NOT USED */
  6725   7078   #define SQLITE_TESTCTRL_LOCALTIME_FAULT         18
  6726   7079   #define SQLITE_TESTCTRL_EXPLAIN_STMT            19  /* NOT USED */
  6727   7080   #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD    19
  6728   7081   #define SQLITE_TESTCTRL_NEVER_CORRUPT           20
  6729   7082   #define SQLITE_TESTCTRL_VDBE_COVERAGE           21
  6730   7083   #define SQLITE_TESTCTRL_BYTEORDER               22
  6731   7084   #define SQLITE_TESTCTRL_ISINIT                  23
  6732   7085   #define SQLITE_TESTCTRL_SORTER_MMAP             24
  6733   7086   #define SQLITE_TESTCTRL_IMPOSTER                25
  6734         -#define SQLITE_TESTCTRL_LAST                    25
         7087  +#define SQLITE_TESTCTRL_PARSER_COVERAGE         26
         7088  +#define SQLITE_TESTCTRL_LAST                    26  /* Largest TESTCTRL */
         7089  +
         7090  +/*
         7091  +** CAPI3REF: SQL Keyword Checking
         7092  +**
         7093  +** These routines provide access to the set of SQL language keywords 
         7094  +** recognized by SQLite.  Applications can uses these routines to determine
         7095  +** whether or not a specific identifier needs to be escaped (for example,
         7096  +** by enclosing in double-quotes) so as not to confuse the parser.
         7097  +**
         7098  +** The sqlite3_keyword_count() interface returns the number of distinct
         7099  +** keywords understood by SQLite.
         7100  +**
         7101  +** The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and
         7102  +** makes *Z point to that keyword expressed as UTF8 and writes the number
         7103  +** of bytes in the keyword into *L.  The string that *Z points to is not
         7104  +** zero-terminated.  The sqlite3_keyword_name(N,Z,L) routine returns
         7105  +** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
         7106  +** or L are NULL or invalid pointers then calls to
         7107  +** sqlite3_keyword_name(N,Z,L) result in undefined behavior.
         7108  +**
         7109  +** The sqlite3_keyword_check(Z,L) interface checks to see whether or not
         7110  +** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
         7111  +** if it is and zero if not.
         7112  +**
         7113  +** The parser used by SQLite is forgiving.  It is often possible to use
         7114  +** a keyword as an identifier as long as such use does not result in a
         7115  +** parsing ambiguity.  For example, the statement
         7116  +** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
         7117  +** creates a new table named "BEGIN" with three columns named
         7118  +** "REPLACE", "PRAGMA", and "END".  Nevertheless, best practice is to avoid
         7119  +** using keywords as identifiers.  Common techniques used to avoid keyword
         7120  +** name collisions include:
         7121  +** <ul>
         7122  +** <li> Put all identifier names inside double-quotes.  This is the official
         7123  +**      SQL way to escape identifier names.
         7124  +** <li> Put identifier names inside &#91;...&#93;.  This is not standard SQL,
         7125  +**      but it is what SQL Server does and so lots of programmers use this
         7126  +**      technique.
         7127  +** <li> Begin every identifier with the letter "Z" as no SQL keywords start
         7128  +**      with "Z".
         7129  +** <li> Include a digit somewhere in every identifier name.
         7130  +** </ul>
         7131  +**
         7132  +** Note that the number of keywords understood by SQLite can depend on
         7133  +** compile-time options.  For example, "VACUUM" is not a keyword if
         7134  +** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option.  Also,
         7135  +** new keywords may be added to future releases of SQLite.
         7136  +*/
         7137  +SQLITE_API int sqlite3_keyword_count(void);
         7138  +SQLITE_API int sqlite3_keyword_name(int,const char**,int*);
         7139  +SQLITE_API int sqlite3_keyword_check(const char*,int);
         7140  +
         7141  +/*
         7142  +** CAPI3REF: Dynamic String Object
         7143  +** KEYWORDS: {dynamic string}
         7144  +**
         7145  +** An instance of the sqlite3_str object contains a dynamically-sized
         7146  +** string under construction.
         7147  +**
         7148  +** The lifecycle of an sqlite3_str object is as follows:
         7149  +** <ol>
         7150  +** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
         7151  +** <li> ^Text is appended to the sqlite3_str object using various
         7152  +** methods, such as [sqlite3_str_appendf()].
         7153  +** <li> ^The sqlite3_str object is destroyed and the string it created
         7154  +** is returned using the [sqlite3_str_finish()] interface.
         7155  +** </ol>
         7156  +*/
         7157  +typedef struct sqlite3_str sqlite3_str;
         7158  +
         7159  +/*
         7160  +** CAPI3REF: Create A New Dynamic String Object
         7161  +** CONSTRUCTOR: sqlite3_str
         7162  +**
         7163  +** ^The [sqlite3_str_new(D)] interface allocates and initializes
         7164  +** a new [sqlite3_str] object.  To avoid memory leaks, the object returned by
         7165  +** [sqlite3_str_new()] must be freed by a subsequent call to 
         7166  +** [sqlite3_str_finish(X)].
         7167  +**
         7168  +** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
         7169  +** valid [sqlite3_str] object, though in the event of an out-of-memory
         7170  +** error the returned object might be a special singleton that will
         7171  +** silently reject new text, always return SQLITE_NOMEM from 
         7172  +** [sqlite3_str_errcode()], always return 0 for 
         7173  +** [sqlite3_str_length()], and always return NULL from
         7174  +** [sqlite3_str_finish(X)].  It is always safe to use the value
         7175  +** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter
         7176  +** to any of the other [sqlite3_str] methods.
         7177  +**
         7178  +** The D parameter to [sqlite3_str_new(D)] may be NULL.  If the
         7179  +** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
         7180  +** length of the string contained in the [sqlite3_str] object will be
         7181  +** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead
         7182  +** of [SQLITE_MAX_LENGTH].
         7183  +*/
         7184  +SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);
         7185  +
         7186  +/*
         7187  +** CAPI3REF: Finalize A Dynamic String
         7188  +** DESTRUCTOR: sqlite3_str
         7189  +**
         7190  +** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X
         7191  +** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
         7192  +** that contains the constructed string.  The calling application should
         7193  +** pass the returned value to [sqlite3_free()] to avoid a memory leak.
         7194  +** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any
         7195  +** errors were encountered during construction of the string.  ^The
         7196  +** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the
         7197  +** string in [sqlite3_str] object X is zero bytes long.
         7198  +*/
         7199  +SQLITE_API char *sqlite3_str_finish(sqlite3_str*);
         7200  +
         7201  +/*
         7202  +** CAPI3REF: Add Content To A Dynamic String
         7203  +** METHOD: sqlite3_str
         7204  +**
         7205  +** These interfaces add content to an sqlite3_str object previously obtained
         7206  +** from [sqlite3_str_new()].
         7207  +**
         7208  +** ^The [sqlite3_str_appendf(X,F,...)] and 
         7209  +** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
         7210  +** functionality of SQLite to append formatted text onto the end of 
         7211  +** [sqlite3_str] object X.
         7212  +**
         7213  +** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S
         7214  +** onto the end of the [sqlite3_str] object X.  N must be non-negative.
         7215  +** S must contain at least N non-zero bytes of content.  To append a
         7216  +** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
         7217  +** method instead.
         7218  +**
         7219  +** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of
         7220  +** zero-terminated string S onto the end of [sqlite3_str] object X.
         7221  +**
         7222  +** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the
         7223  +** single-byte character C onto the end of [sqlite3_str] object X.
         7224  +** ^This method can be used, for example, to add whitespace indentation.
         7225  +**
         7226  +** ^The [sqlite3_str_reset(X)] method resets the string under construction
         7227  +** inside [sqlite3_str] object X back to zero bytes in length.  
         7228  +**
         7229  +** These methods do not return a result code.  ^If an error occurs, that fact
         7230  +** is recorded in the [sqlite3_str] object and can be recovered by a
         7231  +** subsequent call to [sqlite3_str_errcode(X)].
         7232  +*/
         7233  +SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
         7234  +SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
         7235  +SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
         7236  +SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
         7237  +SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
         7238  +SQLITE_API void sqlite3_str_reset(sqlite3_str*);
         7239  +
         7240  +/*
         7241  +** CAPI3REF: Status Of A Dynamic String
         7242  +** METHOD: sqlite3_str
         7243  +**
         7244  +** These interfaces return the current status of an [sqlite3_str] object.
         7245  +**
         7246  +** ^If any prior errors have occurred while constructing the dynamic string
         7247  +** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return
         7248  +** an appropriate error code.  ^The [sqlite3_str_errcode(X)] method returns
         7249  +** [SQLITE_NOMEM] following any out-of-memory error, or
         7250  +** [SQLITE_TOOBIG] if the size of the dynamic string exceeds
         7251  +** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors.
         7252  +**
         7253  +** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,
         7254  +** of the dynamic string under construction in [sqlite3_str] object X.
         7255  +** ^The length returned by [sqlite3_str_length(X)] does not include the
         7256  +** zero-termination byte.
         7257  +**
         7258  +** ^The [sqlite3_str_value(X)] method returns a pointer to the current
         7259  +** content of the dynamic string under construction in X.  The value
         7260  +** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
         7261  +** and might be freed or altered by any subsequent method on the same
         7262  +** [sqlite3_str] object.  Applications must not used the pointer returned
         7263  +** [sqlite3_str_value(X)] after any subsequent method call on the same
         7264  +** object.  ^Applications may change the content of the string returned
         7265  +** by [sqlite3_str_value(X)] as long as they do not write into any bytes
         7266  +** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
         7267  +** write any byte after any subsequent sqlite3_str method call.
         7268  +*/
         7269  +SQLITE_API int sqlite3_str_errcode(sqlite3_str*);
         7270  +SQLITE_API int sqlite3_str_length(sqlite3_str*);
         7271  +SQLITE_API char *sqlite3_str_value(sqlite3_str*);
  6735   7272   
  6736   7273   /*
  6737   7274   ** CAPI3REF: SQLite Runtime Status
  6738   7275   **
  6739   7276   ** ^These interfaces are used to retrieve runtime status information
  6740   7277   ** about the performance of SQLite, and optionally to reset various
  6741   7278   ** highwater marks.  ^The first argument is an integer code for
................................................................................
  6776   7313   ** that can be returned by [sqlite3_status()].
  6777   7314   **
  6778   7315   ** <dl>
  6779   7316   ** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
  6780   7317   ** <dd>This parameter is the current amount of memory checked out
  6781   7318   ** using [sqlite3_malloc()], either directly or indirectly.  The
  6782   7319   ** figure includes calls made to [sqlite3_malloc()] by the application
  6783         -** and internal memory usage by the SQLite library.  Scratch memory
  6784         -** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
         7320  +** and internal memory usage by the SQLite library.  Auxiliary page-cache
  6785   7321   ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
  6786   7322   ** this parameter.  The amount returned is the sum of the allocation
  6787   7323   ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
  6788   7324   **
  6789   7325   ** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
  6790   7326   ** <dd>This parameter records the largest memory allocation request
  6791   7327   ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
................................................................................
  6815   7351   **
  6816   7352   ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
  6817   7353   ** <dd>This parameter records the largest memory allocation request
  6818   7354   ** handed to [pagecache memory allocator].  Only the value returned in the
  6819   7355   ** *pHighwater parameter to [sqlite3_status()] is of interest.  
  6820   7356   ** The value written into the *pCurrent parameter is undefined.</dd>)^
  6821   7357   **
  6822         -** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
  6823         -** <dd>This parameter returns the number of allocations used out of the
  6824         -** [scratch memory allocator] configured using
  6825         -** [SQLITE_CONFIG_SCRATCH].  The value returned is in allocations, not
  6826         -** in bytes.  Since a single thread may only have one scratch allocation
  6827         -** outstanding at time, this parameter also reports the number of threads
  6828         -** using scratch memory at the same time.</dd>)^
         7358  +** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
         7359  +** <dd>No longer used.</dd>
  6829   7360   **
  6830   7361   ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
  6831         -** <dd>This parameter returns the number of bytes of scratch memory
  6832         -** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
  6833         -** buffer and where forced to overflow to [sqlite3_malloc()].  The values
  6834         -** returned include overflows because the requested allocation was too
  6835         -** larger (that is, because the requested allocation was larger than the
  6836         -** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
  6837         -** slots were available.
  6838         -** </dd>)^
         7362  +** <dd>No longer used.</dd>
  6839   7363   **
  6840         -** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
  6841         -** <dd>This parameter records the largest memory allocation request
  6842         -** handed to [scratch memory allocator].  Only the value returned in the
  6843         -** *pHighwater parameter to [sqlite3_status()] is of interest.  
  6844         -** The value written into the *pCurrent parameter is undefined.</dd>)^
         7364  +** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
         7365  +** <dd>No longer used.</dd>
  6845   7366   **
  6846   7367   ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
  6847   7368   ** <dd>The *pHighwater parameter records the deepest parser stack. 
  6848   7369   ** The *pCurrent value is undefined.  The *pHighwater value is only
  6849   7370   ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
  6850   7371   ** </dl>
  6851   7372   **
  6852   7373   ** New status parameters may be added from time to time.
  6853   7374   */
  6854   7375   #define SQLITE_STATUS_MEMORY_USED          0
  6855   7376   #define SQLITE_STATUS_PAGECACHE_USED       1
  6856   7377   #define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
  6857         -#define SQLITE_STATUS_SCRATCH_USED         3
  6858         -#define SQLITE_STATUS_SCRATCH_OVERFLOW     4
         7378  +#define SQLITE_STATUS_SCRATCH_USED         3  /* NOT USED */
         7379  +#define SQLITE_STATUS_SCRATCH_OVERFLOW     4  /* NOT USED */
  6859   7380   #define SQLITE_STATUS_MALLOC_SIZE          5
  6860   7381   #define SQLITE_STATUS_PARSER_STACK         6
  6861   7382   #define SQLITE_STATUS_PAGECACHE_SIZE       7
  6862         -#define SQLITE_STATUS_SCRATCH_SIZE         8
         7383  +#define SQLITE_STATUS_SCRATCH_SIZE         8  /* NOT USED */
  6863   7384   #define SQLITE_STATUS_MALLOC_COUNT         9
  6864   7385   
  6865   7386   /*
  6866   7387   ** CAPI3REF: Database Connection Status
  6867   7388   ** METHOD: sqlite3
  6868   7389   **
  6869   7390   ** ^This interface is used to retrieve runtime status information 
................................................................................
  6977   7498   ** wal file in wal mode databases, or the number of pages written to the
  6978   7499   ** database file in rollback mode databases. Any pages written as part of
  6979   7500   ** transaction rollback or database recovery operations are not included.
  6980   7501   ** If an IO or other error occurs while writing a page to disk, the effect
  6981   7502   ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
  6982   7503   ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
  6983   7504   ** </dd>
         7505  +**
         7506  +** [[SQLITE_DBSTATUS_CACHE_SPILL]] ^(<dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>
         7507  +** <dd>This parameter returns the number of dirty cache entries that have
         7508  +** been written to disk in the middle of a transaction due to the page
         7509  +** cache overflowing. Transactions are more efficient if they are written
         7510  +** to disk all at once. When pages spill mid-transaction, that introduces
         7511  +** additional overhead. This parameter can be used help identify
         7512  +** inefficiencies that can be resolve by increasing the cache size.
         7513  +** </dd>
  6984   7514   **
  6985   7515   ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
  6986   7516   ** <dd>This parameter returns zero for the current value if and only if
  6987   7517   ** all foreign key constraints (deferred or immediate) have been
  6988   7518   ** resolved.)^  ^The highwater mark is always 0.
  6989   7519   ** </dd>
  6990   7520   ** </dl>
................................................................................
  6997   7527   #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
  6998   7528   #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
  6999   7529   #define SQLITE_DBSTATUS_CACHE_HIT            7
  7000   7530   #define SQLITE_DBSTATUS_CACHE_MISS           8
  7001   7531   #define SQLITE_DBSTATUS_CACHE_WRITE          9
  7002   7532   #define SQLITE_DBSTATUS_DEFERRED_FKS        10
  7003   7533   #define SQLITE_DBSTATUS_CACHE_USED_SHARED   11
  7004         -#define SQLITE_DBSTATUS_MAX                 11   /* Largest defined DBSTATUS */
         7534  +#define SQLITE_DBSTATUS_CACHE_SPILL         12
         7535  +#define SQLITE_DBSTATUS_MAX                 12   /* Largest defined DBSTATUS */
  7005   7536   
  7006   7537   
  7007   7538   /*
  7008   7539   ** CAPI3REF: Prepared Statement Status
  7009   7540   ** METHOD: sqlite3_stmt
  7010   7541   **
  7011   7542   ** ^(Each prepared statement maintains various
................................................................................
  7060   7591   ** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
  7061   7592   ** <dd>^This is the number of virtual machine operations executed
  7062   7593   ** by the prepared statement if that number is less than or equal
  7063   7594   ** to 2147483647.  The number of virtual machine operations can be 
  7064   7595   ** used as a proxy for the total work done by the prepared statement.
  7065   7596   ** If the number of virtual machine operations exceeds 2147483647
  7066   7597   ** then the value returned by this statement status code is undefined.
         7598  +**
         7599  +** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
         7600  +** <dd>^This is the number of times that the prepare statement has been
         7601  +** automatically regenerated due to schema changes or change to 
         7602  +** [bound parameters] that might affect the query plan.
         7603  +**
         7604  +** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
         7605  +** <dd>^This is the number of times that the prepared statement has
         7606  +** been run.  A single "run" for the purposes of this counter is one
         7607  +** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
         7608  +** The counter is incremented on the first [sqlite3_step()] call of each
         7609  +** cycle.
         7610  +**
         7611  +** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
         7612  +** <dd>^This is the approximate number of bytes of heap memory
         7613  +** used to store the prepared statement.  ^This value is not actually
         7614  +** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
         7615  +** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
  7067   7616   ** </dd>
  7068   7617   ** </dl>
  7069   7618   */
  7070   7619   #define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
  7071   7620   #define SQLITE_STMTSTATUS_SORT              2
  7072   7621   #define SQLITE_STMTSTATUS_AUTOINDEX         3
  7073   7622   #define SQLITE_STMTSTATUS_VM_STEP           4
         7623  +#define SQLITE_STMTSTATUS_REPREPARE         5
         7624  +#define SQLITE_STMTSTATUS_RUN               6
         7625  +#define SQLITE_STMTSTATUS_MEMUSED           99
  7074   7626   
  7075   7627   /*
  7076   7628   ** CAPI3REF: Custom Page Cache Object
  7077   7629   **
  7078   7630   ** The sqlite3_pcache type is opaque.  It is implemented by
  7079   7631   ** the pluggable module.  The SQLite core has no knowledge of
  7080   7632   ** its size or internal structure and never deals with the
................................................................................
  7976   8528   ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
  7977   8529   ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
  7978   8530   ** of the SQL statement that triggered the call to the [xUpdate] method of the
  7979   8531   ** [virtual table].
  7980   8532   */
  7981   8533   SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
  7982   8534   
         8535  +/*
         8536  +** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE
         8537  +**
         8538  +** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
         8539  +** method of a [virtual table], then it returns true if and only if the
         8540  +** column is being fetched as part of an UPDATE operation during which the
         8541  +** column value will not change.  Applications might use this to substitute
         8542  +** a return value that is less expensive to compute and that the corresponding
         8543  +** [xUpdate] method understands as a "no-change" value.
         8544  +**
         8545  +** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that
         8546  +** the column is not changed by the UPDATE statement, then the xColumn
         8547  +** method can optionally return without setting a result, without calling
         8548  +** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].
         8549  +** In that case, [sqlite3_value_nochange(X)] will return true for the
         8550  +** same column in the [xUpdate] method.
         8551  +*/
         8552  +SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
         8553  +
         8554  +/*
         8555  +** CAPI3REF: Determine The Collation For a Virtual Table Constraint
         8556  +**
         8557  +** This function may only be called from within a call to the [xBestIndex]
         8558  +** method of a [virtual table]. 
         8559  +**
         8560  +** The first argument must be the sqlite3_index_info object that is the
         8561  +** first parameter to the xBestIndex() method. The second argument must be
         8562  +** an index into the aConstraint[] array belonging to the sqlite3_index_info
         8563  +** structure passed to xBestIndex. This function returns a pointer to a buffer 
         8564  +** containing the name of the collation sequence for the corresponding
         8565  +** constraint.
         8566  +*/
         8567  +SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
         8568  +
  7983   8569   /*
  7984   8570   ** CAPI3REF: Conflict resolution modes
  7985   8571   ** KEYWORDS: {conflict resolution mode}
  7986   8572   **
  7987   8573   ** These constants are returned by [sqlite3_vtab_on_conflict()] to
  7988   8574   ** inform a [virtual table] implementation what the [ON CONFLICT] mode
  7989   8575   ** is for the SQL statement being evaluated.
................................................................................
  8137   8723   ** CAPI3REF: The pre-update hook.
  8138   8724   **
  8139   8725   ** ^These interfaces are only available if SQLite is compiled using the
  8140   8726   ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
  8141   8727   **
  8142   8728   ** ^The [sqlite3_preupdate_hook()] interface registers a callback function
  8143   8729   ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
  8144         -** on a [rowid table].
         8730  +** on a database table.
  8145   8731   ** ^At most one preupdate hook may be registered at a time on a single
  8146   8732   ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
  8147   8733   ** the previous setting.
  8148   8734   ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
  8149   8735   ** with a NULL pointer as the second parameter.
  8150   8736   ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
  8151   8737   ** the first parameter to callbacks.
  8152   8738   **
  8153         -** ^The preupdate hook only fires for changes to [rowid tables]; the preupdate
  8154         -** hook is not invoked for changes to [virtual tables] or [WITHOUT ROWID]
  8155         -** tables.
         8739  +** ^The preupdate hook only fires for changes to real database tables; the
         8740  +** preupdate hook is not invoked for changes to [virtual tables] or to
         8741  +** system tables like sqlite_master or sqlite_stat1.
  8156   8742   **
  8157   8743   ** ^The second parameter to the preupdate callback is a pointer to
  8158   8744   ** the [database connection] that registered the preupdate hook.
  8159   8745   ** ^The third parameter to the preupdate callback is one of the constants
  8160   8746   ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
  8161   8747   ** kind of update operation that is about to occur.
  8162   8748   ** ^(The fourth parameter to the preupdate callback is the name of the
  8163   8749   ** database within the database connection that is being modified.  This
  8164   8750   ** will be "main" for the main database or "temp" for TEMP tables or 
  8165   8751   ** the name given after the AS keyword in the [ATTACH] statement for attached
  8166   8752   ** databases.)^
  8167   8753   ** ^The fifth parameter to the preupdate callback is the name of the
  8168   8754   ** table that is being modified.
  8169         -** ^The sixth parameter to the preupdate callback is the initial [rowid] of the
  8170         -** row being changes for SQLITE_UPDATE and SQLITE_DELETE changes and is
  8171         -** undefined for SQLITE_INSERT changes.
  8172         -** ^The seventh parameter to the preupdate callback is the final [rowid] of
  8173         -** the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes and is
  8174         -** undefined for SQLITE_DELETE changes.
         8755  +**
         8756  +** For an UPDATE or DELETE operation on a [rowid table], the sixth
         8757  +** parameter passed to the preupdate callback is the initial [rowid] of the 
         8758  +** row being modified or deleted. For an INSERT operation on a rowid table,
         8759  +** or any operation on a WITHOUT ROWID table, the value of the sixth 
         8760  +** parameter is undefined. For an INSERT or UPDATE on a rowid table the
         8761  +** seventh parameter is the final rowid value of the row being inserted
         8762  +** or updated. The value of the seventh parameter passed to the callback
         8763  +** function is not defined for operations on WITHOUT ROWID tables, or for
         8764  +** INSERT operations on rowid tables.
  8175   8765   **
  8176   8766   ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
  8177   8767   ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
  8178   8768   ** provide additional information about a preupdate event. These routines
  8179   8769   ** may only be called from within a preupdate callback.  Invoking any of
  8180   8770   ** these routines from outside of a preupdate callback or with a
  8181   8771   ** [database connection] pointer that is different from the one supplied
................................................................................
  8207   8797   ** callback was invoked as a result of a direct insert, update, or delete
  8208   8798   ** operation; or 1 for inserts, updates, or deletes invoked by top-level 
  8209   8799   ** triggers; or 2 for changes resulting from triggers called by top-level
  8210   8800   ** triggers; and so forth.
  8211   8801   **
  8212   8802   ** See also:  [sqlite3_update_hook()]
  8213   8803   */
  8214         -SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_preupdate_hook(
         8804  +#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
         8805  +SQLITE_API void *sqlite3_preupdate_hook(
  8215   8806     sqlite3 *db,
  8216   8807     void(*xPreUpdate)(
  8217   8808       void *pCtx,                   /* Copy of third arg to preupdate_hook() */
  8218   8809       sqlite3 *db,                  /* Database handle */
  8219   8810       int op,                       /* SQLITE_UPDATE, DELETE or INSERT */
  8220   8811       char const *zDb,              /* Database name */
  8221   8812       char const *zName,            /* Table name */
  8222   8813       sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */
  8223   8814       sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */
  8224   8815     ),
  8225   8816     void*
  8226   8817   );
  8227         -SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
  8228         -SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_preupdate_count(sqlite3 *);
  8229         -SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_preupdate_depth(sqlite3 *);
  8230         -SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
         8818  +SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
         8819  +SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
         8820  +SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
         8821  +SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
         8822  +#endif
  8231   8823   
  8232   8824   /*
  8233   8825   ** CAPI3REF: Low-level system error code
  8234   8826   **
  8235   8827   ** ^Attempt to return the underlying operating system error code or error
  8236   8828   ** number that caused the most recent I/O error or failure to open a file.
  8237   8829   ** The return value is OS-dependent.  For example, on unix systems, after
................................................................................
  8239   8831   ** called to get back the underlying "errno" that caused the problem, such
  8240   8832   ** as ENOSPC, EAUTH, EISDIR, and so forth.  
  8241   8833   */
  8242   8834   SQLITE_API int sqlite3_system_errno(sqlite3*);
  8243   8835   
  8244   8836   /*
  8245   8837   ** CAPI3REF: Database Snapshot
  8246         -** KEYWORDS: {snapshot}
         8838  +** KEYWORDS: {snapshot} {sqlite3_snapshot}
  8247   8839   ** EXPERIMENTAL
  8248   8840   **
  8249   8841   ** An instance of the snapshot object records the state of a [WAL mode]
  8250   8842   ** database for some specific point in history.
  8251   8843   **
  8252   8844   ** In [WAL mode], multiple [database connections] that are open on the
  8253   8845   ** same database file can each be reading a different historical version
................................................................................
  8263   8855   ** the most recent version.
  8264   8856   **
  8265   8857   ** The constructor for this object is [sqlite3_snapshot_get()].  The
  8266   8858   ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
  8267   8859   ** to an historical snapshot (if possible).  The destructor for 
  8268   8860   ** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
  8269   8861   */
  8270         -typedef struct sqlite3_snapshot sqlite3_snapshot;
         8862  +typedef struct sqlite3_snapshot {
         8863  +  unsigned char hidden[48];
         8864  +} sqlite3_snapshot;
  8271   8865   
  8272   8866   /*
  8273   8867   ** CAPI3REF: Record A Database Snapshot
  8274   8868   ** EXPERIMENTAL
  8275   8869   **
  8276   8870   ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
  8277   8871   ** new [sqlite3_snapshot] object that records the current state of
  8278   8872   ** schema S in database connection D.  ^On success, the
  8279   8873   ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
  8280   8874   ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
  8281         -** ^If schema S of [database connection] D is not a [WAL mode] database
  8282         -** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)]
  8283         -** leaves the *P value unchanged and returns an appropriate [error code].
         8875  +** If there is not already a read-transaction open on schema S when
         8876  +** this function is called, one is opened automatically. 
         8877  +**
         8878  +** The following must be true for this function to succeed. If any of
         8879  +** the following statements are false when sqlite3_snapshot_get() is
         8880  +** called, SQLITE_ERROR is returned. The final value of *P is undefined
         8881  +** in this case. 
         8882  +**
         8883  +** <ul>
         8884  +**   <li> The database handle must be in [autocommit mode].
         8885  +**
         8886  +**   <li> Schema S of [database connection] D must be a [WAL mode] database.
         8887  +**
         8888  +**   <li> There must not be a write transaction open on schema S of database
         8889  +**        connection D.
         8890  +**
         8891  +**   <li> One or more transactions must have been written to the current wal
         8892  +**        file since it was created on disk (by any connection). This means
         8893  +**        that a snapshot cannot be taken on a wal mode database with no wal 
         8894  +**        file immediately after it is first opened. At least one transaction
         8895  +**        must be written to it first.
         8896  +** </ul>
         8897  +**
         8898  +** This function may also return SQLITE_NOMEM.  If it is called with the
         8899  +** database handle in autocommit mode but fails for some other reason, 
         8900  +** whether or not a read transaction is opened on schema S is undefined.
  8284   8901   **
  8285   8902   ** The [sqlite3_snapshot] object returned from a successful call to
  8286   8903   ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
  8287   8904   ** to avoid a memory leak.
  8288   8905   **
  8289   8906   ** The [sqlite3_snapshot_get()] interface is only available when the
  8290   8907   ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
................................................................................
  8369   8986   ** snapshot, and a positive value if P1 is a newer snapshot than P2.
  8370   8987   */
  8371   8988   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
  8372   8989     sqlite3_snapshot *p1,
  8373   8990     sqlite3_snapshot *p2
  8374   8991   );
  8375   8992   
         8993  +/*
         8994  +** CAPI3REF: Recover snapshots from a wal file
         8995  +** EXPERIMENTAL
         8996  +**
         8997  +** If all connections disconnect from a database file but do not perform
         8998  +** a checkpoint, the existing wal file is opened along with the database
         8999  +** file the next time the database is opened. At this point it is only
         9000  +** possible to successfully call sqlite3_snapshot_open() to open the most
         9001  +** recent snapshot of the database (the one at the head of the wal file),
         9002  +** even though the wal file may contain other valid snapshots for which
         9003  +** clients have sqlite3_snapshot handles.
         9004  +**
         9005  +** This function attempts to scan the wal file associated with database zDb
         9006  +** of database handle db and make all valid snapshots available to
         9007  +** sqlite3_snapshot_open(). It is an error if there is already a read
         9008  +** transaction open on the database, or if the database is not a wal mode
         9009  +** database.
         9010  +**
         9011  +** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
         9012  +*/
         9013  +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
         9014  +
         9015  +/*
         9016  +** CAPI3REF: Serialize a database
         9017  +**
         9018  +** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
         9019  +** that is a serialization of the S database on [database connection] D.
         9020  +** If P is not a NULL pointer, then the size of the database in bytes
         9021  +** is written into *P.
         9022  +**
         9023  +** For an ordinary on-disk database file, the serialization is just a
         9024  +** copy of the disk file.  For an in-memory database or a "TEMP" database,
         9025  +** the serialization is the same sequence of bytes which would be written
         9026  +** to disk if that database where backed up to disk.
         9027  +**
         9028  +** The usual case is that sqlite3_serialize() copies the serialization of
         9029  +** the database into memory obtained from [sqlite3_malloc64()] and returns
         9030  +** a pointer to that memory.  The caller is responsible for freeing the
         9031  +** returned value to avoid a memory leak.  However, if the F argument
         9032  +** contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
         9033  +** are made, and the sqlite3_serialize() function will return a pointer
         9034  +** to the contiguous memory representation of the database that SQLite
         9035  +** is currently using for that database, or NULL if the no such contiguous
         9036  +** memory representation of the database exists.  A contiguous memory
         9037  +** representation of the database will usually only exist if there has
         9038  +** been a prior call to [sqlite3_deserialize(D,S,...)] with the same
         9039  +** values of D and S.
         9040  +** The size of the database is written into *P even if the 
         9041  +** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
         9042  +** of the database exists.
         9043  +**
         9044  +** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
         9045  +** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
         9046  +** allocation error occurs.
         9047  +**
         9048  +** This interface is only available if SQLite is compiled with the
         9049  +** [SQLITE_ENABLE_DESERIALIZE] option.
         9050  +*/
         9051  +SQLITE_API unsigned char *sqlite3_serialize(
         9052  +  sqlite3 *db,           /* The database connection */
         9053  +  const char *zSchema,   /* Which DB to serialize. ex: "main", "temp", ... */
         9054  +  sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
         9055  +  unsigned int mFlags    /* Zero or more SQLITE_SERIALIZE_* flags */
         9056  +);
         9057  +
         9058  +/*
         9059  +** CAPI3REF: Flags for sqlite3_serialize
         9060  +**
         9061  +** Zero or more of the following constants can be OR-ed together for
         9062  +** the F argument to [sqlite3_serialize(D,S,P,F)].
         9063  +**
         9064  +** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return
         9065  +** a pointer to contiguous in-memory database that it is currently using,
         9066  +** without making a copy of the database.  If SQLite is not currently using
         9067  +** a contiguous in-memory database, then this option causes
         9068  +** [sqlite3_serialize()] to return a NULL pointer.  SQLite will only be
         9069  +** using a contiguous in-memory database if it has been initialized by a
         9070  +** prior call to [sqlite3_deserialize()].
         9071  +*/
         9072  +#define SQLITE_SERIALIZE_NOCOPY 0x001   /* Do no memory allocations */
         9073  +
         9074  +/*
         9075  +** CAPI3REF: Deserialize a database
         9076  +**
         9077  +** The sqlite3_deserialize(D,S,P,N,M,F) interface causes the 
         9078  +** [database connection] D to disconnect from database S and then
         9079  +** reopen S as an in-memory database based on the serialization contained
         9080  +** in P.  The serialized database P is N bytes in size.  M is the size of
         9081  +** the buffer P, which might be larger than N.  If M is larger than N, and
         9082  +** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
         9083  +** permitted to add content to the in-memory database as long as the total
         9084  +** size does not exceed M bytes.
         9085  +**
         9086  +** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
         9087  +** invoke sqlite3_free() on the serialization buffer when the database
         9088  +** connection closes.  If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
         9089  +** SQLite will try to increase the buffer size using sqlite3_realloc64()
         9090  +** if writes on the database cause it to grow larger than M bytes.
         9091  +**
         9092  +** The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
         9093  +** database is currently in a read transaction or is involved in a backup
         9094  +** operation.
         9095  +**
         9096  +** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the 
         9097  +** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
         9098  +** [sqlite3_free()] is invoked on argument P prior to returning.
         9099  +**
         9100  +** This interface is only available if SQLite is compiled with the
         9101  +** [SQLITE_ENABLE_DESERIALIZE] option.
         9102  +*/
         9103  +SQLITE_API int sqlite3_deserialize(
         9104  +  sqlite3 *db,            /* The database connection */
         9105  +  const char *zSchema,    /* Which DB to reopen with the deserialization */
         9106  +  unsigned char *pData,   /* The serialized database content */
         9107  +  sqlite3_int64 szDb,     /* Number bytes in the deserialization */
         9108  +  sqlite3_int64 szBuf,    /* Total size of buffer pData[] */
         9109  +  unsigned mFlags         /* Zero or more SQLITE_DESERIALIZE_* flags */
         9110  +);
         9111  +
         9112  +/*
         9113  +** CAPI3REF: Flags for sqlite3_deserialize()
         9114  +**
         9115  +** The following are allowed values for 6th argument (the F argument) to
         9116  +** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.
         9117  +**
         9118  +** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
         9119  +** in the P argument is held in memory obtained from [sqlite3_malloc64()]
         9120  +** and that SQLite should take ownership of this memory and automatically
         9121  +** free it when it has finished using it.  Without this flag, the caller
         9122  +** is resposible for freeing any dynamically allocated memory.
         9123  +**
         9124  +** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
         9125  +** grow the size of the database using calls to [sqlite3_realloc64()].  This
         9126  +** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
         9127  +** Without this flag, the deserialized database cannot increase in size beyond
         9128  +** the number of bytes specified by the M parameter.
         9129  +**
         9130  +** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
         9131  +** should be treated as read-only.
         9132  +*/
         9133  +#define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
         9134  +#define SQLITE_DESERIALIZE_RESIZEABLE  2 /* Resize using sqlite3_realloc64() */
         9135  +#define SQLITE_DESERIALIZE_READONLY    4 /* Database is read-only */
         9136  +
  8376   9137   /*
  8377   9138   ** Undo the hack that converts floating point types to integer for
  8378   9139   ** builds on processors without floating point support.
  8379   9140   */
  8380   9141   #ifdef SQLITE_OMIT_FLOATING_POINT
  8381   9142   # undef double
  8382   9143   #endif
................................................................................
  8516   9277   #ifdef __cplusplus
  8517   9278   extern "C" {
  8518   9279   #endif
  8519   9280   
  8520   9281   
  8521   9282   /*
  8522   9283   ** CAPI3REF: Session Object Handle
         9284  +**
         9285  +** An instance of this object is a [session] that can be used to
         9286  +** record changes to a database.
  8523   9287   */
  8524   9288   typedef struct sqlite3_session sqlite3_session;
  8525   9289   
  8526   9290   /*
  8527   9291   ** CAPI3REF: Changeset Iterator Handle
         9292  +**
         9293  +** An instance of this object acts as a cursor for iterating
         9294  +** over the elements of a [changeset] or [patchset].
  8528   9295   */
  8529   9296   typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
  8530   9297   
  8531   9298   /*
  8532   9299   ** CAPI3REF: Create A New Session Object
         9300  +** CONSTRUCTOR: sqlite3_session
  8533   9301   **
  8534   9302   ** Create a new session object attached to database handle db. If successful,
  8535   9303   ** a pointer to the new object is written to *ppSession and SQLITE_OK is
  8536   9304   ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
  8537   9305   ** error code (e.g. SQLITE_NOMEM) is returned.
  8538   9306   **
  8539   9307   ** It is possible to create multiple session objects attached to a single
................................................................................
  8554   9322   ** either of these things are undefined.
  8555   9323   **
  8556   9324   ** The session object will be used to create changesets for tables in
  8557   9325   ** database zDb, where zDb is either "main", or "temp", or the name of an
  8558   9326   ** attached database. It is not an error if database zDb is not attached
  8559   9327   ** to the database when the session object is created.
  8560   9328   */
  8561         -int sqlite3session_create(
         9329  +SQLITE_API int sqlite3session_create(
  8562   9330     sqlite3 *db,                    /* Database handle */
  8563   9331     const char *zDb,                /* Name of db (e.g. "main") */
  8564   9332     sqlite3_session **ppSession     /* OUT: New session object */
  8565   9333   );
  8566   9334   
  8567   9335   /*
  8568   9336   ** CAPI3REF: Delete A Session Object
         9337  +** DESTRUCTOR: sqlite3_session
  8569   9338   **
  8570   9339   ** Delete a session object previously allocated using 
  8571   9340   ** [sqlite3session_create()]. Once a session object has been deleted, the
  8572   9341   ** results of attempting to use pSession with any other session module
  8573   9342   ** function are undefined.
  8574   9343   **
  8575   9344   ** Session objects must be deleted before the database handle to which they
  8576   9345   ** are attached is closed. Refer to the documentation for 
  8577   9346   ** [sqlite3session_create()] for details.
  8578   9347   */
  8579         -void sqlite3session_delete(sqlite3_session *pSession);
         9348  +SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
  8580   9349   
  8581   9350   
  8582   9351   /*
  8583   9352   ** CAPI3REF: Enable Or Disable A Session Object
         9353  +** METHOD: sqlite3_session
  8584   9354   **
  8585   9355   ** Enable or disable the recording of changes by a session object. When
  8586   9356   ** enabled, a session object records changes made to the database. When
  8587   9357   ** disabled - it does not. A newly created session object is enabled.
  8588   9358   ** Refer to the documentation for [sqlite3session_changeset()] for further
  8589   9359   ** details regarding how enabling and disabling a session object affects
  8590   9360   ** the eventual changesets.
................................................................................
  8592   9362   ** Passing zero to this function disables the session. Passing a value
  8593   9363   ** greater than zero enables it. Passing a value less than zero is a 
  8594   9364   ** no-op, and may be used to query the current state of the session.
  8595   9365   **
  8596   9366   ** The return value indicates the final state of the session object: 0 if 
  8597   9367   ** the session is disabled, or 1 if it is enabled.
  8598   9368   */
  8599         -int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
         9369  +SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
  8600   9370   
  8601   9371   /*
  8602   9372   ** CAPI3REF: Set Or Clear the Indirect Change Flag
         9373  +** METHOD: sqlite3_session
  8603   9374   **
  8604   9375   ** Each change recorded by a session object is marked as either direct or
  8605   9376   ** indirect. A change is marked as indirect if either:
  8606   9377   **
  8607   9378   ** <ul>
  8608   9379   **   <li> The session object "indirect" flag is set when the change is
  8609   9380   **        made, or
................................................................................
  8621   9392   ** is set. Passing a value less than zero does not modify the current value
  8622   9393   ** of the indirect flag, and may be used to query the current state of the 
  8623   9394   ** indirect flag for the specified session object.
  8624   9395   **
  8625   9396   ** The return value indicates the final state of the indirect flag: 0 if 
  8626   9397   ** it is clear, or 1 if it is set.
  8627   9398   */
  8628         -int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
         9399  +SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
  8629   9400   
  8630   9401   /*
  8631   9402   ** CAPI3REF: Attach A Table To A Session Object
         9403  +** METHOD: sqlite3_session
  8632   9404   **
  8633   9405   ** If argument zTab is not NULL, then it is the name of a table to attach
  8634   9406   ** to the session object passed as the first argument. All subsequent changes 
  8635   9407   ** made to the table while the session object is enabled will be recorded. See 
  8636   9408   ** documentation for [sqlite3session_changeset()] for further details.
  8637   9409   **
  8638   9410   ** Or, if argument zTab is NULL, then changes are recorded for all tables
................................................................................
  8650   9422   ** no changes will be recorded in either of these scenarios.
  8651   9423   **
  8652   9424   ** Changes are not recorded for individual rows that have NULL values stored
  8653   9425   ** in one or more of their PRIMARY KEY columns.
  8654   9426   **
  8655   9427   ** SQLITE_OK is returned if the call completes without error. Or, if an error 
  8656   9428   ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
         9429  +**
         9430  +** <h3>Special sqlite_stat1 Handling</h3>
         9431  +**
         9432  +** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to 
         9433  +** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
         9434  +**  <pre>
         9435  +**  &nbsp;     CREATE TABLE sqlite_stat1(tbl,idx,stat)  
         9436  +**  </pre>
         9437  +**
         9438  +** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are 
         9439  +** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes 
         9440  +** are recorded for rows for which (idx IS NULL) is true. However, for such
         9441  +** rows a zero-length blob (SQL value X'') is stored in the changeset or
         9442  +** patchset instead of a NULL value. This allows such changesets to be
         9443  +** manipulated by legacy implementations of sqlite3changeset_invert(),
         9444  +** concat() and similar.
         9445  +**
         9446  +** The sqlite3changeset_apply() function automatically converts the 
         9447  +** zero-length blob back to a NULL value when updating the sqlite_stat1
         9448  +** table. However, if the application calls sqlite3changeset_new(),
         9449  +** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset 
         9450  +** iterator directly (including on a changeset iterator passed to a
         9451  +** conflict-handler callback) then the X'' value is returned. The application
         9452  +** must translate X'' to NULL itself if required.
         9453  +**
         9454  +** Legacy (older than 3.22.0) versions of the sessions module cannot capture
         9455  +** changes made to the sqlite_stat1 table. Legacy versions of the
         9456  +** sqlite3changeset_apply() function silently ignore any modifications to the
         9457  +** sqlite_stat1 table that are part of a changeset or patchset.
  8657   9458   */
  8658         -int sqlite3session_attach(
         9459  +SQLITE_API int sqlite3session_attach(
  8659   9460     sqlite3_session *pSession,      /* Session object */
  8660   9461     const char *zTab                /* Table name */
  8661   9462   );
  8662   9463   
  8663   9464   /*
  8664   9465   ** CAPI3REF: Set a table filter on a Session Object.
         9466  +** METHOD: sqlite3_session
  8665   9467   **
  8666   9468   ** The second argument (xFilter) is the "filter callback". For changes to rows 
  8667   9469   ** in tables that are not attached to the Session object, the filter is called
  8668   9470   ** to determine whether changes to the table's rows should be tracked or not. 
  8669   9471   ** If xFilter returns 0, changes is not tracked. Note that once a table is 
  8670   9472   ** attached, xFilter will not be called again.
  8671   9473   */
  8672         -void sqlite3session_table_filter(
         9474  +SQLITE_API void sqlite3session_table_filter(
  8673   9475     sqlite3_session *pSession,      /* Session object */
  8674   9476     int(*xFilter)(
  8675   9477       void *pCtx,                   /* Copy of third arg to _filter_table() */
  8676   9478       const char *zTab              /* Table name */
  8677   9479     ),
  8678   9480     void *pCtx                      /* First argument passed to xFilter */
  8679   9481   );
  8680   9482   
  8681   9483   /*
  8682   9484   ** CAPI3REF: Generate A Changeset From A Session Object
         9485  +** METHOD: sqlite3_session
  8683   9486   **
  8684   9487   ** Obtain a changeset containing changes to the tables attached to the 
  8685   9488   ** session object passed as the first argument. If successful, 
  8686   9489   ** set *ppChangeset to point to a buffer containing the changeset 
  8687   9490   ** and *pnChangeset to the size of the changeset in bytes before returning
  8688   9491   ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
  8689   9492   ** zero and return an SQLite error code.
................................................................................
  8778   9581   ** is inserted while a session object is enabled, then later deleted while 
  8779   9582   ** the same session object is disabled, no INSERT record will appear in the
  8780   9583   ** changeset, even though the delete took place while the session was disabled.
  8781   9584   ** Or, if one field of a row is updated while a session is disabled, and 
  8782   9585   ** another field of the same row is updated while the session is enabled, the
  8783   9586   ** resulting changeset will contain an UPDATE change that updates both fields.
  8784   9587   */
  8785         -int sqlite3session_changeset(
         9588  +SQLITE_API int sqlite3session_changeset(
  8786   9589     sqlite3_session *pSession,      /* Session object */
  8787   9590     int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
  8788   9591     void **ppChangeset              /* OUT: Buffer containing changeset */
  8789   9592   );
  8790   9593   
  8791   9594   /*
  8792         -** CAPI3REF: Load The Difference Between Tables Into A Session 
         9595  +** CAPI3REF: Load The Difference Between Tables Into A Session
         9596  +** METHOD: sqlite3_session
  8793   9597   **
  8794   9598   ** If it is not already attached to the session object passed as the first
  8795   9599   ** argument, this function attaches table zTbl in the same manner as the
  8796   9600   ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
  8797   9601   ** does not have a primary key, this function is a no-op (but does not return
  8798   9602   ** an error).
  8799   9603   **
................................................................................
  8822   9626   **   <li> For each row (primary key) that exists in the to-table but not in 
  8823   9627   **     the from-table, an INSERT record is added to the session object.
  8824   9628   **
  8825   9629   **   <li> For each row (primary key) that exists in the to-table but not in 
  8826   9630   **     the from-table, a DELETE record is added to the session object.
  8827   9631   **
  8828   9632   **   <li> For each row (primary key) that exists in both tables, but features 
  8829         -**     different in each, an UPDATE record is added to the session.
         9633  +**     different non-PK values in each, an UPDATE record is added to the
         9634  +**     session.  
  8830   9635   ** </ul>
  8831   9636   **
  8832   9637   ** To clarify, if this function is called and then a changeset constructed
  8833   9638   ** using [sqlite3session_changeset()], then after applying that changeset to 
  8834   9639   ** database zFrom the contents of the two compatible tables would be 
  8835   9640   ** identical.
  8836   9641   **
................................................................................
  8839   9644   **
  8840   9645   ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
  8841   9646   ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
  8842   9647   ** may be set to point to a buffer containing an English language error 
  8843   9648   ** message. It is the responsibility of the caller to free this buffer using
  8844   9649   ** sqlite3_free().
  8845   9650   */
  8846         -int sqlite3session_diff(
         9651  +SQLITE_API int sqlite3session_diff(
  8847   9652     sqlite3_session *pSession,
  8848   9653     const char *zFromDb,
  8849   9654     const char *zTbl,
  8850   9655     char **pzErrMsg
  8851   9656   );
  8852   9657   
  8853   9658   
  8854   9659   /*
  8855   9660   ** CAPI3REF: Generate A Patchset From A Session Object
         9661  +** METHOD: sqlite3_session
  8856   9662   **
  8857   9663   ** The differences between a patchset and a changeset are that:
  8858   9664   **
  8859   9665   ** <ul>
  8860   9666   **   <li> DELETE records consist of the primary key fields only. The 
  8861   9667   **        original values of other fields are omitted.
  8862   9668   **   <li> The original values of any modified fields are omitted from 
................................................................................
  8875   9681   ** in the same way as for changesets.
  8876   9682   **
  8877   9683   ** Changes within a patchset are ordered in the same way as for changesets
  8878   9684   ** generated by the sqlite3session_changeset() function (i.e. all changes for
  8879   9685   ** a single table are grouped together, tables appear in the order in which
  8880   9686   ** they were attached to the session object).
  8881   9687   */
  8882         -int sqlite3session_patchset(
         9688  +SQLITE_API int sqlite3session_patchset(
  8883   9689     sqlite3_session *pSession,      /* Session object */
  8884         -  int *pnPatchset,                /* OUT: Size of buffer at *ppChangeset */
  8885         -  void **ppPatchset               /* OUT: Buffer containing changeset */
         9690  +  int *pnPatchset,                /* OUT: Size of buffer at *ppPatchset */
         9691  +  void **ppPatchset               /* OUT: Buffer containing patchset */
  8886   9692   );
  8887   9693   
  8888   9694   /*
  8889   9695   ** CAPI3REF: Test if a changeset has recorded any changes.
  8890   9696   **
  8891   9697   ** Return non-zero if no changes to attached tables have been recorded by 
  8892   9698   ** the session object passed as the first argument. Otherwise, if one or 
................................................................................
  8896   9702   ** [sqlite3session_changeset()] on the session handle may still return a
  8897   9703   ** changeset that contains no changes. This can happen when a row in 
  8898   9704   ** an attached table is modified and then later on the original values 
  8899   9705   ** are restored. However, if this function returns non-zero, then it is
  8900   9706   ** guaranteed that a call to sqlite3session_changeset() will return a 
  8901   9707   ** changeset containing zero changes.
  8902   9708   */
  8903         -int sqlite3session_isempty(sqlite3_session *pSession);
         9709  +SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
  8904   9710   
  8905   9711   /*
  8906   9712   ** CAPI3REF: Create An Iterator To Traverse A Changeset 
         9713  +** CONSTRUCTOR: sqlite3_changeset_iter
  8907   9714   **
  8908   9715   ** Create an iterator used to iterate through the contents of a changeset.
  8909   9716   ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
  8910   9717   ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
  8911   9718   ** SQLite error code is returned.
  8912   9719   **
  8913   9720   ** The following functions can be used to advance and query a changeset 
................................................................................
  8931   9738   ** that apply to a single table are grouped together. This means that when 
  8932   9739   ** an application iterates through a changeset using an iterator created by 
  8933   9740   ** this function, all changes that relate to a single table are visited 
  8934   9741   ** consecutively. There is no chance that the iterator will visit a change 
  8935   9742   ** the applies to table X, then one for table Y, and then later on visit 
  8936   9743   ** another change for table X.
  8937   9744   */
  8938         -int sqlite3changeset_start(
         9745  +SQLITE_API int sqlite3changeset_start(
  8939   9746     sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
  8940   9747     int nChangeset,                 /* Size of changeset blob in bytes */
  8941   9748     void *pChangeset                /* Pointer to blob containing changeset */
  8942   9749   );
  8943   9750   
  8944   9751   
  8945   9752   /*
  8946   9753   ** CAPI3REF: Advance A Changeset Iterator
         9754  +** METHOD: sqlite3_changeset_iter
  8947   9755   **
  8948   9756   ** This function may only be used with iterators created by function
  8949   9757   ** [sqlite3changeset_start()]. If it is called on an iterator passed to
  8950   9758   ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
  8951   9759   ** is returned and the call has no effect.
  8952   9760   **
  8953   9761   ** Immediately after an iterator is created by sqlite3changeset_start(), it
................................................................................
  8960   9768   ** Otherwise, if all changes in the changeset have already been visited,
  8961   9769   ** SQLITE_DONE is returned.
  8962   9770   **
  8963   9771   ** If an error occurs, an SQLite error code is returned. Possible error 
  8964   9772   ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or 
  8965   9773   ** SQLITE_NOMEM.
  8966   9774   */
  8967         -int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
         9775  +SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
  8968   9776   
  8969   9777   /*
  8970   9778   ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
         9779  +** METHOD: sqlite3_changeset_iter
  8971   9780   **
  8972   9781   ** The pIter argument passed to this function may either be an iterator
  8973   9782   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  8974   9783   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  8975   9784   ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
  8976   9785   ** is not the case, this function returns [SQLITE_MISUSE].
  8977   9786   **
................................................................................
  8988   9797   ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the 
  8989   9798   ** type of change that the iterator currently points to.
  8990   9799   **
  8991   9800   ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
  8992   9801   ** SQLite error code is returned. The values of the output variables may not
  8993   9802   ** be trusted in this case.
  8994   9803   */
  8995         -int sqlite3changeset_op(
         9804  +SQLITE_API int sqlite3changeset_op(
  8996   9805     sqlite3_changeset_iter *pIter,  /* Iterator object */
  8997   9806     const char **pzTab,             /* OUT: Pointer to table name */
  8998   9807     int *pnCol,                     /* OUT: Number of columns in table */
  8999   9808     int *pOp,                       /* OUT: SQLITE_INSERT, DELETE or UPDATE */
  9000   9809     int *pbIndirect                 /* OUT: True for an 'indirect' change */
  9001   9810   );
  9002   9811   
  9003   9812   /*
  9004   9813   ** CAPI3REF: Obtain The Primary Key Definition Of A Table
         9814  +** METHOD: sqlite3_changeset_iter
  9005   9815   **
  9006   9816   ** For each modified table, a changeset includes the following:
  9007   9817   **
  9008   9818   ** <ul>
  9009   9819   **   <li> The number of columns in the table, and
  9010   9820   **   <li> Which of those columns make up the tables PRIMARY KEY.
  9011   9821   ** </ul>
................................................................................
  9021   9831   ** in the table.
  9022   9832   **
  9023   9833   ** If this function is called when the iterator does not point to a valid
  9024   9834   ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
  9025   9835   ** SQLITE_OK is returned and the output variables populated as described
  9026   9836   ** above.
  9027   9837   */
  9028         -int sqlite3changeset_pk(
         9838  +SQLITE_API int sqlite3changeset_pk(
  9029   9839     sqlite3_changeset_iter *pIter,  /* Iterator object */
  9030   9840     unsigned char **pabPK,          /* OUT: Array of boolean - true for PK cols */
  9031   9841     int *pnCol                      /* OUT: Number of entries in output array */
  9032   9842   );
  9033   9843   
  9034   9844   /*
  9035   9845   ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
         9846  +** METHOD: sqlite3_changeset_iter
  9036   9847   **
  9037   9848   ** The pIter argument passed to this function may either be an iterator
  9038   9849   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  9039   9850   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  9040   9851   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
  9041   9852   ** Furthermore, it may only be called if the type of change that the iterator
  9042   9853   ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
................................................................................
  9051   9862   ** original row values stored as part of the UPDATE or DELETE change and
  9052   9863   ** returns SQLITE_OK. The name of the function comes from the fact that this 
  9053   9864   ** is similar to the "old.*" columns available to update or delete triggers.
  9054   9865   **
  9055   9866   ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9056   9867   ** is returned and *ppValue is set to NULL.
  9057   9868   */
  9058         -int sqlite3changeset_old(
         9869  +SQLITE_API int sqlite3changeset_old(
  9059   9870     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
  9060   9871     int iVal,                       /* Column number */
  9061   9872     sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */
  9062   9873   );
  9063   9874   
  9064   9875   /*
  9065   9876   ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
         9877  +** METHOD: sqlite3_changeset_iter
  9066   9878   **
  9067   9879   ** The pIter argument passed to this function may either be an iterator
  9068   9880   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  9069   9881   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  9070   9882   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
  9071   9883   ** Furthermore, it may only be called if the type of change that the iterator
  9072   9884   ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
................................................................................
  9084   9896   ** SQLITE_OK returned. The name of the function comes from the fact that 
  9085   9897   ** this is similar to the "new.*" columns available to update or delete 
  9086   9898   ** triggers.
  9087   9899   **
  9088   9900   ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9089   9901   ** is returned and *ppValue is set to NULL.
  9090   9902   */
  9091         -int sqlite3changeset_new(
         9903  +SQLITE_API int sqlite3changeset_new(
  9092   9904     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
  9093   9905     int iVal,                       /* Column number */
  9094   9906     sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
  9095   9907   );
  9096   9908   
  9097   9909   /*
  9098   9910   ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
         9911  +** METHOD: sqlite3_changeset_iter
  9099   9912   **
  9100   9913   ** This function should only be used with iterator objects passed to a
  9101   9914   ** conflict-handler callback by [sqlite3changeset_apply()] with either
  9102   9915   ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
  9103   9916   ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
  9104   9917   ** is set to NULL.
  9105   9918   **
................................................................................
  9111   9924   ** sqlite3_value object containing the iVal'th value from the 
  9112   9925   ** "conflicting row" associated with the current conflict-handler callback
  9113   9926   ** and returns SQLITE_OK.
  9114   9927   **
  9115   9928   ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9116   9929   ** is returned and *ppValue is set to NULL.
  9117   9930   */
  9118         -int sqlite3changeset_conflict(
         9931  +SQLITE_API int sqlite3changeset_conflict(
  9119   9932     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
  9120   9933     int iVal,                       /* Column number */
  9121   9934     sqlite3_value **ppValue         /* OUT: Value from conflicting row */
  9122   9935   );
  9123   9936   
  9124   9937   /*
  9125   9938   ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
         9939  +** METHOD: sqlite3_changeset_iter
  9126   9940   **
  9127   9941   ** This function may only be called with an iterator passed to an
  9128   9942   ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
  9129   9943   ** it sets the output variable to the total number of known foreign key
  9130   9944   ** violations in the destination database and returns SQLITE_OK.
  9131   9945   **
  9132   9946   ** In all other cases this function returns SQLITE_MISUSE.
  9133   9947   */
  9134         -int sqlite3changeset_fk_conflicts(
         9948  +SQLITE_API int sqlite3changeset_fk_conflicts(
  9135   9949     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
  9136   9950     int *pnOut                      /* OUT: Number of FK violations */
  9137   9951   );
  9138   9952   
  9139   9953   
  9140   9954   /*
  9141   9955   ** CAPI3REF: Finalize A Changeset Iterator
         9956  +** METHOD: sqlite3_changeset_iter
  9142   9957   **
  9143   9958   ** This function is used to finalize an iterator allocated with
  9144   9959   ** [sqlite3changeset_start()].
  9145   9960   **
  9146   9961   ** This function should only be called on iterators created using the
  9147   9962   ** [sqlite3changeset_start()] function. If an application calls this
  9148   9963   ** function with an iterator passed to a conflict-handler by
................................................................................
  9151   9966   **
  9152   9967   ** If an error was encountered within a call to an sqlite3changeset_xxx()
  9153   9968   ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an 
  9154   9969   ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
  9155   9970   ** to that error is returned by this function. Otherwise, SQLITE_OK is
  9156   9971   ** returned. This is to allow the following pattern (pseudo-code):
  9157   9972   **
         9973  +** <pre>
  9158   9974   **   sqlite3changeset_start();
  9159   9975   **   while( SQLITE_ROW==sqlite3changeset_next() ){
  9160   9976   **     // Do something with change.
  9161   9977   **   }
  9162   9978   **   rc = sqlite3changeset_finalize();
  9163   9979   **   if( rc!=SQLITE_OK ){
  9164   9980   **     // An error has occurred 
  9165   9981   **   }
         9982  +** </pre>
  9166   9983   */
  9167         -int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
         9984  +SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
  9168   9985   
  9169   9986   /*
  9170   9987   ** CAPI3REF: Invert A Changeset
  9171   9988   **
  9172   9989   ** This function is used to "invert" a changeset object. Applying an inverted
  9173   9990   ** changeset to a database reverses the effects of applying the uninverted
  9174   9991   ** changeset. Specifically:
................................................................................
  9190  10007   ** It is the responsibility of the caller to eventually call sqlite3_free()
  9191  10008   ** on the *ppOut pointer to free the buffer allocation following a successful 
  9192  10009   ** call to this function.
  9193  10010   **
  9194  10011   ** WARNING/TODO: This function currently assumes that the input is a valid
  9195  10012   ** changeset. If it is not, the results are undefined.
  9196  10013   */
  9197         -int sqlite3changeset_invert(
        10014  +SQLITE_API int sqlite3changeset_invert(
  9198  10015     int nIn, const void *pIn,       /* Input changeset */
  9199  10016     int *pnOut, void **ppOut        /* OUT: Inverse of input */
  9200  10017   );
  9201  10018   
  9202  10019   /*
  9203  10020   ** CAPI3REF: Concatenate Two Changeset Objects
  9204  10021   **
................................................................................
  9206  10023   ** single changeset. The result is a changeset equivalent to applying
  9207  10024   ** changeset A followed by changeset B. 
  9208  10025   **
  9209  10026   ** This function combines the two input changesets using an 
  9210  10027   ** sqlite3_changegroup object. Calling it produces similar results as the
  9211  10028   ** following code fragment:
  9212  10029   **
        10030  +** <pre>
  9213  10031   **   sqlite3_changegroup *pGrp;
  9214  10032   **   rc = sqlite3_changegroup_new(&pGrp);
  9215  10033   **   if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
  9216  10034   **   if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
  9217  10035   **   if( rc==SQLITE_OK ){
  9218  10036   **     rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
  9219  10037   **   }else{
  9220  10038   **     *ppOut = 0;
  9221  10039   **     *pnOut = 0;
  9222  10040   **   }
        10041  +** </pre>
  9223  10042   **
  9224  10043   ** Refer to the sqlite3_changegroup documentation below for details.
  9225  10044   */
  9226         -int sqlite3changeset_concat(
        10045  +SQLITE_API int sqlite3changeset_concat(
  9227  10046     int nA,                         /* Number of bytes in buffer pA */
  9228  10047     void *pA,                       /* Pointer to buffer containing changeset A */
  9229  10048     int nB,                         /* Number of bytes in buffer pB */
  9230  10049     void *pB,                       /* Pointer to buffer containing changeset B */
  9231  10050     int *pnOut,                     /* OUT: Number of bytes in output changeset */
  9232  10051     void **ppOut                    /* OUT: Buffer containing output changeset */
  9233  10052   );
  9234  10053   
  9235  10054   
  9236  10055   /*
  9237  10056   ** CAPI3REF: Changegroup Handle
        10057  +**
        10058  +** A changegroup is an object used to combine two or more 
        10059  +** [changesets] or [patchsets]
  9238  10060   */
  9239  10061   typedef struct sqlite3_changegroup sqlite3_changegroup;
  9240  10062   
  9241  10063   /*
  9242  10064   ** CAPI3REF: Create A New Changegroup Object
        10065  +** CONSTRUCTOR: sqlite3_changegroup
  9243  10066   **
  9244  10067   ** An sqlite3_changegroup object is used to combine two or more changesets
  9245  10068   ** (or patchsets) into a single changeset (or patchset). A single changegroup
  9246  10069   ** object may combine changesets or patchsets, but not both. The output is
  9247  10070   ** always in the same format as the input.
  9248  10071   **
  9249  10072   ** If successful, this function returns SQLITE_OK and populates (*pp) with
................................................................................
  9269  10092   ** Any number of calls to add() and output() may be made between the calls to
  9270  10093   ** new() and delete(), and in any order.
  9271  10094   **
  9272  10095   ** As well as the regular sqlite3changegroup_add() and 
  9273  10096   ** sqlite3changegroup_output() functions, also available are the streaming
  9274  10097   ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
  9275  10098   */
  9276         -int sqlite3changegroup_new(sqlite3_changegroup **pp);
        10099  +SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
  9277  10100   
  9278  10101   /*
  9279  10102   ** CAPI3REF: Add A Changeset To A Changegroup
        10103  +** METHOD: sqlite3_changegroup
  9280  10104   **
  9281  10105   ** Add all changes within the changeset (or patchset) in buffer pData (size
  9282  10106   ** nData bytes) to the changegroup. 
  9283  10107   **
  9284  10108   ** If the buffer contains a patchset, then all prior calls to this function
  9285  10109   ** on the same changegroup object must also have specified patchsets. Or, if
  9286  10110   ** the buffer contains a changeset, so must have the earlier calls to this
................................................................................
  9346  10170   ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
  9347  10171   ** returned. Or, if an out-of-memory condition occurs during processing, this
  9348  10172   ** function returns SQLITE_NOMEM. In all cases, if an error occurs the
  9349  10173   ** final contents of the changegroup is undefined.
  9350  10174   **
  9351  10175   ** If no error occurs, SQLITE_OK is returned.
  9352  10176   */
  9353         -int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
        10177  +SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
  9354  10178   
  9355  10179   /*
  9356  10180   ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
        10181  +** METHOD: sqlite3_changegroup
  9357  10182   **
  9358  10183   ** Obtain a buffer containing a changeset (or patchset) representing the
  9359  10184   ** current contents of the changegroup. If the inputs to the changegroup
  9360  10185   ** were themselves changesets, the output is a changeset. Or, if the
  9361  10186   ** inputs were patchsets, the output is also a patchset.
  9362  10187   **
  9363  10188   ** As with the output of the sqlite3session_changeset() and
................................................................................
  9372  10197   ** If an error occurs, an SQLite error code is returned and the output
  9373  10198   ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
  9374  10199   ** is returned and the output variables are set to the size of and a 
  9375  10200   ** pointer to the output buffer, respectively. In this case it is the
  9376  10201   ** responsibility of the caller to eventually free the buffer using a
  9377  10202   ** call to sqlite3_free().
  9378  10203   */
  9379         -int sqlite3changegroup_output(
        10204  +SQLITE_API int sqlite3changegroup_output(
  9380  10205     sqlite3_changegroup*,
  9381  10206     int *pnData,                    /* OUT: Size of output buffer in bytes */
  9382  10207     void **ppData                   /* OUT: Pointer to output buffer */
  9383  10208   );
  9384  10209   
  9385  10210   /*
  9386  10211   ** CAPI3REF: Delete A Changegroup Object
        10212  +** DESTRUCTOR: sqlite3_changegroup
  9387  10213   */
  9388         -void sqlite3changegroup_delete(sqlite3_changegroup*);
        10214  +SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
  9389  10215   
  9390  10216   /*
  9391  10217   ** CAPI3REF: Apply A Changeset To A Database
  9392  10218   **
  9393         -** Apply a changeset to a database. This function attempts to update the
  9394         -** "main" database attached to handle db with the changes found in the
  9395         -** changeset passed via the second and third arguments.
        10219  +** Apply a changeset or patchset to a database. These functions attempt to
        10220  +** update the "main" database attached to handle db with the changes found in
        10221  +** the changeset passed via the second and third arguments. 
  9396  10222   **
  9397         -** The fourth argument (xFilter) passed to this function is the "filter
        10223  +** The fourth argument (xFilter) passed to these functions is the "filter
  9398  10224   ** callback". If it is not NULL, then for each table affected by at least one
  9399  10225   ** change in the changeset, the filter callback is invoked with
  9400  10226   ** the table name as the second argument, and a copy of the context pointer
  9401         -** passed as the sixth argument to this function as the first. If the "filter
  9402         -** callback" returns zero, then no attempt is made to apply any changes to 
  9403         -** the table. Otherwise, if the return value is non-zero or the xFilter
  9404         -** argument to this function is NULL, all changes related to the table are
  9405         -** attempted.
        10227  +** passed as the sixth argument as the first. If the "filter callback"
        10228  +** returns zero, then no attempt is made to apply any changes to the table.
        10229  +** Otherwise, if the return value is non-zero or the xFilter argument to
        10230  +** is NULL, all changes related to the table are attempted.
  9406  10231   **
  9407  10232   ** For each table that is not excluded by the filter callback, this function 
  9408  10233   ** tests that the target database contains a compatible table. A table is 
  9409  10234   ** considered compatible if all of the following are true:
  9410  10235   **
  9411  10236   ** <ul>
  9412  10237   **   <li> The table has the same name as the name recorded in the 
  9413  10238   **        changeset, and
  9414         -**   <li> The table has the same number of columns as recorded in the 
        10239  +**   <li> The table has at least as many columns as recorded in the 
  9415  10240   **        changeset, and
  9416  10241   **   <li> The table has primary key columns in the same position as 
  9417  10242   **        recorded in the changeset.
  9418  10243   ** </ul>
  9419  10244   **
  9420  10245   ** If there is no compatible table, it is not an error, but none of the
  9421  10246   ** changes associated with the table are applied. A warning message is issued
................................................................................
  9443  10268   ** actions are taken by sqlite3changeset_apply() depending on the value
  9444  10269   ** returned by each invocation of the conflict-handler function. Refer to
  9445  10270   ** the documentation for the three 
  9446  10271   ** [SQLITE_CHANGESET_OMIT|available return values] for details.
  9447  10272   **
  9448  10273   ** <dl>
  9449  10274   ** <dt>DELETE Changes<dd>
  9450         -**   For each DELETE change, this function checks if the target database 
        10275  +**   For each DELETE change, the function checks if the target database 
  9451  10276   **   contains a row with the same primary key value (or values) as the 
  9452  10277   **   original row values stored in the changeset. If it does, and the values 
  9453  10278   **   stored in all non-primary key columns also match the values stored in 
  9454  10279   **   the changeset the row is deleted from the target database.
  9455  10280   **
  9456  10281   **   If a row with matching primary key values is found, but one or more of
  9457  10282   **   the non-primary key fields contains a value different from the original
  9458  10283   **   row value stored in the changeset, the conflict-handler function is
  9459         -**   invoked with [SQLITE_CHANGESET_DATA] as the second argument.
        10284  +**   invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
        10285  +**   database table has more columns than are recorded in the changeset,
        10286  +**   only the values of those non-primary key fields are compared against
        10287  +**   the current database contents - any trailing database table columns
        10288  +**   are ignored.
  9460  10289   **
  9461  10290   **   If no row with matching primary key values is found in the database,
  9462  10291   **   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  9463  10292   **   passed as the second argument.
  9464  10293   **
  9465  10294   **   If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
  9466  10295   **   (which can only happen if a foreign key constraint is violated), the
................................................................................
  9467  10296   **   conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
  9468  10297   **   passed as the second argument. This includes the case where the DELETE
  9469  10298   **   operation is attempted because an earlier call to the conflict handler
  9470  10299   **   function returned [SQLITE_CHANGESET_REPLACE].
  9471  10300   **
  9472  10301   ** <dt>INSERT Changes<dd>
  9473  10302   **   For each INSERT change, an attempt is made to insert the new row into
  9474         -**   the database.
        10303  +**   the database. If the changeset row contains fewer fields than the
        10304  +**   database table, the trailing fields are populated with their default
        10305  +**   values.
  9475  10306   **
  9476  10307   **   If the attempt to insert the row fails because the database already 
  9477  10308   **   contains a row with the same primary key values, the conflict handler
  9478  10309   **   function is invoked with the second argument set to 
  9479  10310   **   [SQLITE_CHANGESET_CONFLICT].
  9480  10311   **
  9481  10312   **   If the attempt to insert the row fails because of some other constraint
................................................................................
  9482  10313   **   violation (e.g. NOT NULL or UNIQUE), the conflict handler function is 
  9483  10314   **   invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
  9484  10315   **   This includes the case where the INSERT operation is re-attempted because 
  9485  10316   **   an earlier call to the conflict handler function returned 
  9486  10317   **   [SQLITE_CHANGESET_REPLACE].
  9487  10318   **
  9488  10319   ** <dt>UPDATE Changes<dd>
  9489         -**   For each UPDATE change, this function checks if the target database 
        10320  +**   For each UPDATE change, the function checks if the target database 
  9490  10321   **   contains a row with the same primary key value (or values) as the 
  9491  10322   **   original row values stored in the changeset. If it does, and the values 
  9492         -**   stored in all non-primary key columns also match the values stored in 
  9493         -**   the changeset the row is updated within the target database.
        10323  +**   stored in all modified non-primary key columns also match the values
        10324  +**   stored in the changeset the row is updated within the target database.
  9494  10325   **
  9495  10326   **   If a row with matching primary key values is found, but one or more of
  9496         -**   the non-primary key fields contains a value different from an original
  9497         -**   row value stored in the changeset, the conflict-handler function is
  9498         -**   invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
        10327  +**   the modified non-primary key fields contains a value different from an
        10328  +**   original row value stored in the changeset, the conflict-handler function
        10329  +**   is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
  9499  10330   **   UPDATE changes only contain values for non-primary key fields that are
  9500  10331   **   to be modified, only those fields need to match the original values to
  9501  10332   **   avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
  9502  10333   **
  9503  10334   **   If no row with matching primary key values is found in the database,
  9504  10335   **   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  9505  10336   **   passed as the second argument.
................................................................................
  9513  10344   ** </dl>
  9514  10345   **
  9515  10346   ** It is safe to execute SQL statements, including those that write to the
  9516  10347   ** table that the callback related to, from within the xConflict callback.
  9517  10348   ** This can be used to further customize the applications conflict
  9518  10349   ** resolution strategy.
  9519  10350   **
  9520         -** All changes made by this function are enclosed in a savepoint transaction.
        10351  +** All changes made by these functions are enclosed in a savepoint transaction.
  9521  10352   ** If any other error (aside from a constraint failure when attempting to
  9522  10353   ** write to the target database) occurs, then the savepoint transaction is
  9523  10354   ** rolled back, restoring the target database to its original state, and an 
  9524  10355   ** SQLite error code returned.
        10356  +**
        10357  +** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
        10358  +** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
        10359  +** may set (*ppRebase) to point to a "rebase" that may be used with the 
        10360  +** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
        10361  +** is set to the size of the buffer in bytes. It is the responsibility of the
        10362  +** caller to eventually free any such buffer using sqlite3_free(). The buffer
        10363  +** is only allocated and populated if one or more conflicts were encountered
        10364  +** while applying the patchset. See comments surrounding the sqlite3_rebaser
        10365  +** APIs for further details.
        10366  +**
        10367  +** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
        10368  +** may be modified by passing a combination of
        10369  +** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.
        10370  +**
        10371  +** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
        10372  +** and therefore subject to change.
  9525  10373   */
  9526         -int sqlite3changeset_apply(
        10374  +SQLITE_API int sqlite3changeset_apply(
  9527  10375     sqlite3 *db,                    /* Apply change to "main" db of this handle */
  9528  10376     int nChangeset,                 /* Size of changeset in bytes */
  9529  10377     void *pChangeset,               /* Changeset blob */
  9530  10378     int(*xFilter)(
  9531  10379       void *pCtx,                   /* Copy of sixth arg to _apply() */
  9532  10380       const char *zTab              /* Table name */
  9533  10381     ),
................................................................................
  9534  10382     int(*xConflict)(
  9535  10383       void *pCtx,                   /* Copy of sixth arg to _apply() */
  9536  10384       int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
  9537  10385       sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  9538  10386     ),
  9539  10387     void *pCtx                      /* First argument passed to xConflict */
  9540  10388   );
        10389  +SQLITE_API int sqlite3changeset_apply_v2(
        10390  +  sqlite3 *db,                    /* Apply change to "main" db of this handle */
        10391  +  int nChangeset,                 /* Size of changeset in bytes */
        10392  +  void *pChangeset,               /* Changeset blob */
        10393  +  int(*xFilter)(
        10394  +    void *pCtx,                   /* Copy of sixth arg to _apply() */
        10395  +    const char *zTab              /* Table name */
        10396  +  ),
        10397  +  int(*xConflict)(
        10398  +    void *pCtx,                   /* Copy of sixth arg to _apply() */
        10399  +    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
        10400  +    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
        10401  +  ),
        10402  +  void *pCtx,                     /* First argument passed to xConflict */
        10403  +  void **ppRebase, int *pnRebase, /* OUT: Rebase data */
        10404  +  int flags                       /* Combination of SESSION_APPLY_* flags */
        10405  +);
        10406  +
        10407  +/*
        10408  +** CAPI3REF: Flags for sqlite3changeset_apply_v2
        10409  +**
        10410  +** The following flags may passed via the 9th parameter to
        10411  +** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
        10412  +**
        10413  +** <dl>
        10414  +** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
        10415  +**   Usually, the sessions module encloses all operations performed by
        10416  +**   a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The
        10417  +**   SAVEPOINT is committed if the changeset or patchset is successfully
        10418  +**   applied, or rolled back if an error occurs. Specifying this flag
        10419  +**   causes the sessions module to omit this savepoint. In this case, if the
        10420  +**   caller has an open transaction or savepoint when apply_v2() is called, 
        10421  +**   it may revert the partially applied changeset by rolling it back.
        10422  +*/
        10423  +#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT   0x0001
  9541  10424   
  9542  10425   /* 
  9543  10426   ** CAPI3REF: Constants Passed To The Conflict Handler
  9544  10427   **
  9545  10428   ** Values that may be passed as the second argument to a conflict-handler.
  9546  10429   **
  9547  10430   ** <dl>
................................................................................
  9631  10514   **   and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
  9632  10515   ** </dl>
  9633  10516   */
  9634  10517   #define SQLITE_CHANGESET_OMIT       0
  9635  10518   #define SQLITE_CHANGESET_REPLACE    1
  9636  10519   #define SQLITE_CHANGESET_ABORT      2
  9637  10520   
        10521  +/* 
        10522  +** CAPI3REF: Rebasing changesets
        10523  +** EXPERIMENTAL
        10524  +**
        10525  +** Suppose there is a site hosting a database in state S0. And that
        10526  +** modifications are made that move that database to state S1 and a
        10527  +** changeset recorded (the "local" changeset). Then, a changeset based
        10528  +** on S0 is received from another site (the "remote" changeset) and 
        10529  +** applied to the database. The database is then in state 
        10530  +** (S1+"remote"), where the exact state depends on any conflict
        10531  +** resolution decisions (OMIT or REPLACE) made while applying "remote".
        10532  +** Rebasing a changeset is to update it to take those conflict 
        10533  +** resolution decisions into account, so that the same conflicts
        10534  +** do not have to be resolved elsewhere in the network. 
        10535  +**
        10536  +** For example, if both the local and remote changesets contain an
        10537  +** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
        10538  +**
        10539  +**   local:  INSERT INTO t1 VALUES(1, 'v1');
        10540  +**   remote: INSERT INTO t1 VALUES(1, 'v2');
        10541  +**
        10542  +** and the conflict resolution is REPLACE, then the INSERT change is
        10543  +** removed from the local changeset (it was overridden). Or, if the
        10544  +** conflict resolution was "OMIT", then the local changeset is modified
        10545  +** to instead contain:
        10546  +**
        10547  +**           UPDATE t1 SET b = 'v2' WHERE a=1;
        10548  +**
        10549  +** Changes within the local changeset are rebased as follows:
        10550  +**
        10551  +** <dl>
        10552  +** <dt>Local INSERT<dd>
        10553  +**   This may only conflict with a remote INSERT. If the conflict 
        10554  +**   resolution was OMIT, then add an UPDATE change to the rebased
        10555  +**   changeset. Or, if the conflict resolution was REPLACE, add
        10556  +**   nothing to the rebased changeset.
        10557  +**
        10558  +** <dt>Local DELETE<dd>
        10559  +**   This may conflict with a remote UPDATE or DELETE. In both cases the
        10560  +**   only possible resolution is OMIT. If the remote operation was a
        10561  +**   DELETE, then add no change to the rebased changeset. If the remote
        10562  +**   operation was an UPDATE, then the old.* fields of change are updated
        10563  +**   to reflect the new.* values in the UPDATE.
        10564  +**
        10565  +** <dt>Local UPDATE<dd>
        10566  +**   This may conflict with a remote UPDATE or DELETE. If it conflicts
        10567  +**   with a DELETE, and the conflict resolution was OMIT, then the update
        10568  +**   is changed into an INSERT. Any undefined values in the new.* record
        10569  +**   from the update change are filled in using the old.* values from
        10570  +**   the conflicting DELETE. Or, if the conflict resolution was REPLACE,
        10571  +**   the UPDATE change is simply omitted from the rebased changeset.
        10572  +**
        10573  +**   If conflict is with a remote UPDATE and the resolution is OMIT, then
        10574  +**   the old.* values are rebased using the new.* values in the remote
        10575  +**   change. Or, if the resolution is REPLACE, then the change is copied
        10576  +**   into the rebased changeset with updates to columns also updated by
        10577  +**   the conflicting remote UPDATE removed. If this means no columns would 
        10578  +**   be updated, the change is omitted.
        10579  +** </dl>
        10580  +**
        10581  +** A local change may be rebased against multiple remote changes 
        10582  +** simultaneously. If a single key is modified by multiple remote 
        10583  +** changesets, they are combined as follows before the local changeset
        10584  +** is rebased:
        10585  +**
        10586  +** <ul>
        10587  +**    <li> If there has been one or more REPLACE resolutions on a
        10588  +**         key, it is rebased according to a REPLACE.
        10589  +**
        10590  +**    <li> If there have been no REPLACE resolutions on a key, then
        10591  +**         the local changeset is rebased according to the most recent
        10592  +**         of the OMIT resolutions.
        10593  +** </ul>
        10594  +**
        10595  +** Note that conflict resolutions from multiple remote changesets are 
        10596  +** combined on a per-field basis, not per-row. This means that in the 
        10597  +** case of multiple remote UPDATE operations, some fields of a single 
        10598  +** local change may be rebased for REPLACE while others are rebased for 
        10599  +** OMIT.
        10600  +**
        10601  +** In order to rebase a local changeset, the remote changeset must first
        10602  +** be applied to the local database using sqlite3changeset_apply_v2() and
        10603  +** the buffer of rebase information captured. Then:
        10604  +**
        10605  +** <ol>
        10606  +**   <li> An sqlite3_rebaser object is created by calling 
        10607  +**        sqlite3rebaser_create().
        10608  +**   <li> The new object is configured with the rebase buffer obtained from
        10609  +**        sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
        10610  +**        If the local changeset is to be rebased against multiple remote
        10611  +**        changesets, then sqlite3rebaser_configure() should be called
        10612  +**        multiple times, in the same order that the multiple
        10613  +**        sqlite3changeset_apply_v2() calls were made.
        10614  +**   <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
        10615  +**   <li> The sqlite3_rebaser object is deleted by calling
        10616  +**        sqlite3rebaser_delete().
        10617  +** </ol>
        10618  +*/
        10619  +typedef struct sqlite3_rebaser sqlite3_rebaser;
        10620  +
        10621  +/*
        10622  +** CAPI3REF: Create a changeset rebaser object.
        10623  +** EXPERIMENTAL
        10624  +**
        10625  +** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
        10626  +** point to the new object and return SQLITE_OK. Otherwise, if an error
        10627  +** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew) 
        10628  +** to NULL. 
        10629  +*/
        10630  +SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
        10631  +
        10632  +/*
        10633  +** CAPI3REF: Configure a changeset rebaser object.
        10634  +** EXPERIMENTAL
        10635  +**
        10636  +** Configure the changeset rebaser object to rebase changesets according
        10637  +** to the conflict resolutions described by buffer pRebase (size nRebase
        10638  +** bytes), which must have been obtained from a previous call to
        10639  +** sqlite3changeset_apply_v2().
        10640  +*/
        10641  +SQLITE_API int sqlite3rebaser_configure(
        10642  +  sqlite3_rebaser*, 
        10643  +  int nRebase, const void *pRebase
        10644  +); 
        10645  +
        10646  +/*
        10647  +** CAPI3REF: Rebase a changeset
        10648  +** EXPERIMENTAL
        10649  +**
        10650  +** Argument pIn must point to a buffer containing a changeset nIn bytes
        10651  +** in size. This function allocates and populates a buffer with a copy
        10652  +** of the changeset rebased rebased according to the configuration of the
        10653  +** rebaser object passed as the first argument. If successful, (*ppOut)
        10654  +** is set to point to the new buffer containing the rebased changset and 
        10655  +** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
        10656  +** responsibility of the caller to eventually free the new buffer using
        10657  +** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
        10658  +** are set to zero and an SQLite error code returned.
        10659  +*/
        10660  +SQLITE_API int sqlite3rebaser_rebase(
        10661  +  sqlite3_rebaser*,
        10662  +  int nIn, const void *pIn, 
        10663  +  int *pnOut, void **ppOut 
        10664  +);
        10665  +
        10666  +/*
        10667  +** CAPI3REF: Delete a changeset rebaser object.
        10668  +** EXPERIMENTAL
        10669  +**
        10670  +** Delete the changeset rebaser object and all associated resources. There
        10671  +** should be one call to this function for each successful invocation
        10672  +** of sqlite3rebaser_create().
        10673  +*/
        10674  +SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p); 
        10675  +
  9638  10676   /*
  9639  10677   ** CAPI3REF: Streaming Versions of API functions.
  9640  10678   **
  9641  10679   ** The six streaming API xxx_strm() functions serve similar purposes to the 
  9642  10680   ** corresponding non-streaming API functions:
  9643  10681   **
  9644  10682   ** <table border=1 style="margin-left:8ex;margin-right:8ex">
  9645  10683   **   <tr><th>Streaming function<th>Non-streaming equivalent</th>
  9646         -**   <tr><td>sqlite3changeset_apply_str<td>[sqlite3changeset_apply] 
  9647         -**   <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat] 
  9648         -**   <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert] 
  9649         -**   <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start] 
  9650         -**   <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset] 
  9651         -**   <tr><td>sqlite3session_patchset_str<td>[sqlite3session_patchset] 
        10684  +**   <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply] 
        10685  +**   <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2] 
        10686  +**   <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat] 
        10687  +**   <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert] 
        10688  +**   <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start] 
        10689  +**   <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset] 
        10690  +**   <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset] 
  9652  10691   ** </table>
  9653  10692   **
  9654  10693   ** Non-streaming functions that accept changesets (or patchsets) as input
  9655  10694   ** require that the entire changeset be stored in a single buffer in memory. 
  9656  10695   ** Similarly, those that return a changeset or patchset do so by returning 
  9657  10696   ** a pointer to a single large buffer allocated using sqlite3_malloc(). 
  9658  10697   ** Normally this is convenient. However, if an application running in a 
................................................................................
  9720  10759   ** is immediately abandoned and the streaming API function returns a copy
  9721  10760   ** of the xOutput error code to the application.
  9722  10761   **
  9723  10762   ** The sessions module never invokes an xOutput callback with the third 
  9724  10763   ** parameter set to a value less than or equal to zero. Other than this,
  9725  10764   ** no guarantees are made as to the size of the chunks of data returned.
  9726  10765   */
  9727         -int sqlite3changeset_apply_strm(
        10766  +SQLITE_API int sqlite3changeset_apply_strm(
  9728  10767     sqlite3 *db,                    /* Apply change to "main" db of this handle */
  9729  10768     int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  9730  10769     void *pIn,                                          /* First arg for xInput */
  9731  10770     int(*xFilter)(
  9732  10771       void *pCtx,                   /* Copy of sixth arg to _apply() */
  9733  10772       const char *zTab              /* Table name */
  9734  10773     ),
................................................................................
  9735  10774     int(*xConflict)(
  9736  10775       void *pCtx,                   /* Copy of sixth arg to _apply() */
  9737  10776       int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
  9738  10777       sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  9739  10778     ),
  9740  10779     void *pCtx                      /* First argument passed to xConflict */
  9741  10780   );
  9742         -int sqlite3changeset_concat_strm(
        10781  +SQLITE_API int sqlite3changeset_apply_v2_strm(
        10782  +  sqlite3 *db,                    /* Apply change to "main" db of this handle */
        10783  +  int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
        10784  +  void *pIn,                                          /* First arg for xInput */
        10785  +  int(*xFilter)(
        10786  +    void *pCtx,                   /* Copy of sixth arg to _apply() */
        10787  +    const char *zTab              /* Table name */
        10788  +  ),
        10789  +  int(*xConflict)(
        10790  +    void *pCtx,                   /* Copy of sixth arg to _apply() */
        10791  +    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
        10792  +    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
        10793  +  ),
        10794  +  void *pCtx,                     /* First argument passed to xConflict */
        10795  +  void **ppRebase, int *pnRebase,
        10796  +  int flags
        10797  +);
        10798  +SQLITE_API int sqlite3changeset_concat_strm(
  9743  10799     int (*xInputA)(void *pIn, void *pData, int *pnData),
  9744  10800     void *pInA,
  9745  10801     int (*xInputB)(void *pIn, void *pData, int *pnData),
  9746  10802     void *pInB,
  9747  10803     int (*xOutput)(void *pOut, const void *pData, int nData),
  9748  10804     void *pOut
  9749  10805   );
  9750         -int sqlite3changeset_invert_strm(
        10806  +SQLITE_API int sqlite3changeset_invert_strm(
  9751  10807     int (*xInput)(void *pIn, void *pData, int *pnData),
  9752  10808     void *pIn,
  9753  10809     int (*xOutput)(void *pOut, const void *pData, int nData),
  9754  10810     void *pOut
  9755  10811   );
  9756         -int sqlite3changeset_start_strm(
        10812  +SQLITE_API int sqlite3changeset_start_strm(
  9757  10813     sqlite3_changeset_iter **pp,
  9758  10814     int (*xInput)(void *pIn, void *pData, int *pnData),
  9759  10815     void *pIn
  9760  10816   );
  9761         -int sqlite3session_changeset_strm(
        10817  +SQLITE_API int sqlite3session_changeset_strm(
  9762  10818     sqlite3_session *pSession,
  9763  10819     int (*xOutput)(void *pOut, const void *pData, int nData),
  9764  10820     void *pOut
  9765  10821   );
  9766         -int sqlite3session_patchset_strm(
        10822  +SQLITE_API int sqlite3session_patchset_strm(
  9767  10823     sqlite3_session *pSession,
  9768  10824     int (*xOutput)(void *pOut, const void *pData, int nData),
  9769  10825     void *pOut
  9770  10826   );
  9771         -int sqlite3changegroup_add_strm(sqlite3_changegroup*, 
        10827  +SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*, 
  9772  10828       int (*xInput)(void *pIn, void *pData, int *pnData),
  9773  10829       void *pIn
  9774  10830   );
  9775         -int sqlite3changegroup_output_strm(sqlite3_changegroup*,
        10831  +SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
  9776  10832       int (*xOutput)(void *pOut, const void *pData, int nData), 
  9777  10833       void *pOut
        10834  +);
        10835  +SQLITE_API int sqlite3rebaser_rebase_strm(
        10836  +  sqlite3_rebaser *pRebaser,
        10837  +  int (*xInput)(void *pIn, void *pData, int *pnData),
        10838  +  void *pIn,
        10839  +  int (*xOutput)(void *pOut, const void *pData, int nData),
        10840  +  void *pOut
  9778  10841   );
  9779  10842   
  9780  10843   
  9781  10844   /*
  9782  10845   ** Make sure we can call this stuff from C++.
  9783  10846   */
  9784  10847   #ifdef __cplusplus