amalgalite 1.6.1-x64-mingw32 → 1.6.3-x64-mingw32

Sign up to get free protection for your applications and to get access to all the features.
@@ -108,7 +108,7 @@ extern "C" {
108
108
  ** be held constant and Z will be incremented or else Y will be incremented
109
109
  ** and Z will be reset to zero.
110
110
  **
111
- ** Since [version 3.6.18] ([dateof:3.6.18]),
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
@@ -123,9 +123,9 @@ extern "C" {
123
123
  ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
124
124
  ** [sqlite_version()] and [sqlite_source_id()].
125
125
  */
126
- #define SQLITE_VERSION "3.21.0"
127
- #define SQLITE_VERSION_NUMBER 3021000
128
- #define SQLITE_SOURCE_ID "2017-10-24 18:55:49 1a584e499906b5c87ec7d43d4abce641fdf017c42125b083109bc77c4de48827"
126
+ #define SQLITE_VERSION "3.26.0"
127
+ #define SQLITE_VERSION_NUMBER 3026000
128
+ #define SQLITE_SOURCE_ID "2018-12-01 12:34:55 bf8c1b2b7a5960c282e543b9c293686dccff272512d08865f4600fb58238b4f9"
129
129
 
130
130
  /*
131
131
  ** CAPI3REF: Run-Time Library Version Numbers
@@ -151,7 +151,7 @@ extern "C" {
151
151
  ** function is provided for use in DLLs since DLL users usually do not have
152
152
  ** direct access to string constants within the DLL. ^The
153
153
  ** sqlite3_libversion_number() function returns an integer equal to
154
- ** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
154
+ ** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
155
155
  ** a pointer to a string constant whose value is the same as the
156
156
  ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
157
157
  ** using an edited copy of [the amalgamation], then the last four characters
@@ -265,7 +265,7 @@ typedef struct sqlite3 sqlite3;
265
265
  typedef SQLITE_INT64_TYPE sqlite_int64;
266
266
  # ifdef SQLITE_UINT64_TYPE
267
267
  typedef SQLITE_UINT64_TYPE sqlite_uint64;
268
- # else
268
+ # else
269
269
  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
270
270
  # endif
271
271
  #elif defined(_MSC_VER) || defined(__BORLANDC__)
@@ -470,6 +470,9 @@ SQLITE_API int sqlite3_exec(
470
470
  ** the most recent error can be obtained using
471
471
  ** [sqlite3_extended_errcode()].
472
472
  */
473
+ #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))
474
+ #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8))
475
+ #define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8))
473
476
  #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
474
477
  #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
475
478
  #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
@@ -502,17 +505,22 @@ SQLITE_API int sqlite3_exec(
502
505
  #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
503
506
  #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
504
507
  #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
508
+ #define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8))
505
509
  #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
506
510
  #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
507
511
  #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
508
512
  #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
509
513
  #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
510
514
  #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
515
+ #define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
511
516
  #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
517
+ #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8))
512
518
  #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
513
519
  #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
514
520
  #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
515
521
  #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
522
+ #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))
523
+ #define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8))
516
524
  #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
517
525
  #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
518
526
  #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
@@ -880,7 +888,8 @@ struct sqlite3_io_methods {
880
888
  ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
881
889
  ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
882
890
  ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
883
- ** write ahead log and shared memory files used for transaction control
891
+ ** write ahead log ([WAL file]) and shared memory
892
+ ** files used for transaction control
884
893
  ** are automatically deleted when the latest connection to the database
885
894
  ** closes. Setting persistent WAL mode causes those files to persist after
886
895
  ** close. Persisting the files is useful when other processes that do not
@@ -1042,7 +1051,7 @@ struct sqlite3_io_methods {
1042
1051
  **
1043
1052
  ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
1044
1053
  ** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
1045
- ** operations since the previous successful call to
1054
+ ** operations since the previous successful call to
1046
1055
  ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
1047
1056
  ** This file control returns [SQLITE_OK] if and only if the writes were
1048
1057
  ** all performed successfully and have been committed to persistent storage.
@@ -1054,12 +1063,38 @@ struct sqlite3_io_methods {
1054
1063
  **
1055
1064
  ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
1056
1065
  ** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
1057
- ** operations since the previous successful call to
1066
+ ** operations since the previous successful call to
1058
1067
  ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
1059
1068
  ** ^This file control takes the file descriptor out of batch write mode
1060
1069
  ** so that all subsequent write operations are independent.
1061
1070
  ** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
1062
1071
  ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1072
+ **
1073
+ ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
1074
+ ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain
1075
+ ** a file lock using the xLock or xShmLock methods of the VFS to wait
1076
+ ** for up to M milliseconds before failing, where M is the single
1077
+ ** unsigned integer parameter.
1078
+ **
1079
+ ** <li>[[SQLITE_FCNTL_DATA_VERSION]]
1080
+ ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
1081
+ ** a database file. The argument is a pointer to a 32-bit unsigned integer.
1082
+ ** The "data version" for the pager is written into the pointer. The
1083
+ ** "data version" changes whenever any change occurs to the corresponding
1084
+ ** database file, either through SQL statements on the same database
1085
+ ** connection or through transactions committed by separate database
1086
+ ** connections possibly in other processes. The [sqlite3_total_changes()]
1087
+ ** interface can be used to find if any database on the connection has changed,
1088
+ ** but that interface responds to changes on TEMP as well as MAIN and does
1089
+ ** not provide a mechanism to detect changes to MAIN only. Also, the
1090
+ ** [sqlite3_total_changes()] interface responds to internal changes only and
1091
+ ** omits changes made by other database connections. The
1092
+ ** [PRAGMA data_version] command provide a mechanism to detect changes to
1093
+ ** a single attached database that occur due to other database connections,
1094
+ ** but omits changes implemented by the database connection on which it is
1095
+ ** called. This file control is the only mechanism to detect changes that
1096
+ ** happen either internally or externally and that are associated with
1097
+ ** a particular attached database.
1063
1098
  ** </ul>
1064
1099
  */
1065
1100
  #define SQLITE_FCNTL_LOCKSTATE 1
@@ -1094,6 +1129,8 @@ struct sqlite3_io_methods {
1094
1129
  #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
1095
1130
  #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
1096
1131
  #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
1132
+ #define SQLITE_FCNTL_LOCK_TIMEOUT 34
1133
+ #define SQLITE_FCNTL_DATA_VERSION 35
1097
1134
 
1098
1135
  /* deprecated names */
1099
1136
  #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
@@ -1131,12 +1168,18 @@ typedef struct sqlite3_api_routines sqlite3_api_routines;
1131
1168
  ** in the name of the object stands for "virtual file system". See
1132
1169
  ** the [VFS | VFS documentation] for further information.
1133
1170
  **
1134
- ** The value of the iVersion field is initially 1 but may be larger in
1135
- ** future versions of SQLite. Additional fields may be appended to this
1136
- ** object when the iVersion value is increased. Note that the structure
1137
- ** of the sqlite3_vfs object changes in the transaction between
1138
- ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
1139
- ** modified.
1171
+ ** The VFS interface is sometimes extended by adding new methods onto
1172
+ ** the end. Each time such an extension occurs, the iVersion field
1173
+ ** is incremented. The iVersion value started out as 1 in
1174
+ ** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
1175
+ ** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
1176
+ ** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
1177
+ ** may be appended to the sqlite3_vfs object and the iVersion value
1178
+ ** may increase again in future versions of SQLite.
1179
+ ** Note that the structure
1180
+ ** of the sqlite3_vfs object changes in the transition from
1181
+ ** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
1182
+ ** and yet the iVersion field was not modified.
1140
1183
  **
1141
1184
  ** The szOsFile field is the size of the subclassed [sqlite3_file]
1142
1185
  ** structure used by this VFS. mxPathname is the maximum length of
@@ -1903,7 +1946,7 @@ struct sqlite3_mem_methods {
1903
1946
  ** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
1904
1947
  ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
1905
1948
  ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
1906
- ** becomes the [statement journal] spill-to-disk threshold.
1949
+ ** becomes the [statement journal] spill-to-disk threshold.
1907
1950
  ** [Statement journals] are held in memory until their size (in bytes)
1908
1951
  ** exceeds this threshold, at which point they are written to disk.
1909
1952
  ** Or if the threshold is -1, statement journals are always held
@@ -1913,6 +1956,22 @@ struct sqlite3_mem_methods {
1913
1956
  ** I/O required to support statement rollback.
1914
1957
  ** The default value for this setting is controlled by the
1915
1958
  ** [SQLITE_STMTJRNL_SPILL] compile-time option.
1959
+ **
1960
+ ** [[SQLITE_CONFIG_SORTERREF_SIZE]]
1961
+ ** <dt>SQLITE_CONFIG_SORTERREF_SIZE
1962
+ ** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
1963
+ ** of type (int) - the new value of the sorter-reference size threshold.
1964
+ ** Usually, when SQLite uses an external sort to order records according
1965
+ ** to an ORDER BY clause, all fields required by the caller are present in the
1966
+ ** sorted records. However, if SQLite determines based on the declared type
1967
+ ** of a table column that its values are likely to be very large - larger
1968
+ ** than the configured sorter-reference size threshold - then a reference
1969
+ ** is stored in each sorted record and the required column values loaded
1970
+ ** from the database as records are returned in sorted order. The default
1971
+ ** value for this option is to never use this optimization. Specifying a
1972
+ ** negative value for this option restores the default behaviour.
1973
+ ** This option is only available if SQLite is compiled with the
1974
+ ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
1916
1975
  ** </dl>
1917
1976
  */
1918
1977
  #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
@@ -1942,6 +2001,7 @@ struct sqlite3_mem_methods {
1942
2001
  #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
1943
2002
  #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
1944
2003
  #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
2004
+ #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
1945
2005
 
1946
2006
  /*
1947
2007
  ** CAPI3REF: Database Connection Configuration Options
@@ -1957,6 +2017,7 @@ struct sqlite3_mem_methods {
1957
2017
  ** is invoked.
1958
2018
  **
1959
2019
  ** <dl>
2020
+ ** [[SQLITE_DBCONFIG_LOOKASIDE]]
1960
2021
  ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1961
2022
  ** <dd> ^This option takes three additional arguments that determine the
1962
2023
  ** [lookaside memory allocator] configuration for the [database connection].
@@ -1979,6 +2040,7 @@ struct sqlite3_mem_methods {
1979
2040
  ** memory is in use leaves the configuration unchanged and returns
1980
2041
  ** [SQLITE_BUSY].)^</dd>
1981
2042
  **
2043
+ ** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
1982
2044
  ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
1983
2045
  ** <dd> ^This option is used to enable or disable the enforcement of
1984
2046
  ** [foreign key constraints]. There should be two additional arguments.
@@ -1989,6 +2051,7 @@ struct sqlite3_mem_methods {
1989
2051
  ** following this call. The second parameter may be a NULL pointer, in
1990
2052
  ** which case the FK enforcement setting is not reported back. </dd>
1991
2053
  **
2054
+ ** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
1992
2055
  ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
1993
2056
  ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
1994
2057
  ** There should be two additional arguments.
@@ -1999,6 +2062,7 @@ struct sqlite3_mem_methods {
1999
2062
  ** following this call. The second parameter may be a NULL pointer, in
2000
2063
  ** which case the trigger setting is not reported back. </dd>
2001
2064
  **
2065
+ ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
2002
2066
  ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
2003
2067
  ** <dd> ^This option is used to enable or disable the two-argument
2004
2068
  ** version of the [fts3_tokenizer()] function which is part of the
@@ -2012,6 +2076,7 @@ struct sqlite3_mem_methods {
2012
2076
  ** following this call. The second parameter may be a NULL pointer, in
2013
2077
  ** which case the new setting is not reported back. </dd>
2014
2078
  **
2079
+ ** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
2015
2080
  ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
2016
2081
  ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2017
2082
  ** interface independently of the [load_extension()] SQL function.
@@ -2029,7 +2094,7 @@ struct sqlite3_mem_methods {
2029
2094
  ** be a NULL pointer, in which case the new setting is not reported back.
2030
2095
  ** </dd>
2031
2096
  **
2032
- ** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
2097
+ ** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
2033
2098
  ** <dd> ^This option is used to change the name of the "main" database
2034
2099
  ** schema. ^The sole argument is a pointer to a constant UTF8 string
2035
2100
  ** which will become the new schema name in place of "main". ^SQLite
@@ -2038,19 +2103,21 @@ struct sqlite3_mem_methods {
2038
2103
  ** until after the database connection closes.
2039
2104
  ** </dd>
2040
2105
  **
2106
+ ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
2041
2107
  ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
2042
- ** <dd> Usually, when a database in wal mode is closed or detached from a
2043
- ** database handle, SQLite checks if this will mean that there are now no
2044
- ** connections at all to the database. If so, it performs a checkpoint
2108
+ ** <dd> Usually, when a database in wal mode is closed or detached from a
2109
+ ** database handle, SQLite checks if this will mean that there are now no
2110
+ ** connections at all to the database. If so, it performs a checkpoint
2045
2111
  ** operation before closing the connection. This option may be used to
2046
2112
  ** override this behaviour. The first parameter passed to this operation
2047
- ** is an integer - non-zero to disable checkpoints-on-close, or zero (the
2048
- ** default) to enable them. The second parameter is a pointer to an integer
2113
+ ** is an integer - positive to disable checkpoints-on-close, or zero (the
2114
+ ** default) to enable them, and negative to leave the setting unchanged.
2115
+ ** The second parameter is a pointer to an integer
2049
2116
  ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2050
2117
  ** have been disabled - 0 if they are not disabled, 1 if they are.
2051
2118
  ** </dd>
2052
2119
  **
2053
- ** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
2120
+ ** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
2054
2121
  ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
2055
2122
  ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
2056
2123
  ** a single SQL query statement will always use the same algorithm regardless
@@ -2059,8 +2126,57 @@ struct sqlite3_mem_methods {
2059
2126
  ** slower. But the QPSG has the advantage of more predictable behavior. With
2060
2127
  ** the QPSG active, SQLite will always use the same query plan in the field as
2061
2128
  ** was used during testing in the lab.
2129
+ ** The first argument to this setting is an integer which is 0 to disable
2130
+ ** the QPSG, positive to enable QPSG, or negative to leave the setting
2131
+ ** unchanged. The second parameter is a pointer to an integer into which
2132
+ ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
2133
+ ** following this call.
2062
2134
  ** </dd>
2063
2135
  **
2136
+ ** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
2137
+ ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
2138
+ ** include output for any operations performed by trigger programs. This
2139
+ ** option is used to set or clear (the default) a flag that governs this
2140
+ ** behavior. The first parameter passed to this operation is an integer -
2141
+ ** positive to enable output for trigger programs, or zero to disable it,
2142
+ ** or negative to leave the setting unchanged.
2143
+ ** The second parameter is a pointer to an integer into which is written
2144
+ ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2145
+ ** it is not disabled, 1 if it is.
2146
+ ** </dd>
2147
+ **
2148
+ ** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
2149
+ ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
2150
+ ** [VACUUM] in order to reset a database back to an empty database
2151
+ ** with no schema and no content. The following process works even for
2152
+ ** a badly corrupted database file:
2153
+ ** <ol>
2154
+ ** <li> If the database connection is newly opened, make sure it has read the
2155
+ ** database schema by preparing then discarding some query against the
2156
+ ** database, or calling sqlite3_table_column_metadata(), ignoring any
2157
+ ** errors. This step is only necessary if the application desires to keep
2158
+ ** the database in WAL mode after the reset if it was in WAL mode before
2159
+ ** the reset.
2160
+ ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
2161
+ ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
2162
+ ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
2163
+ ** </ol>
2164
+ ** Because resetting a database is destructive and irreversible, the
2165
+ ** process requires the use of this obscure API and multiple steps to help
2166
+ ** ensure that it does not happen by accident.
2167
+ **
2168
+ ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
2169
+ ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
2170
+ ** "defensive" flag for a database connection. When the defensive
2171
+ ** flag is enabled, language features that allow ordinary SQL to
2172
+ ** deliberately corrupt the database file are disabled. The disabled
2173
+ ** features include but are not limited to the following:
2174
+ ** <ul>
2175
+ ** <li> The [PRAGMA writable_schema=ON] statement.
2176
+ ** <li> Writes to the [sqlite_dbpage] virtual table.
2177
+ ** <li> Direct writes to [shadow tables].
2178
+ ** </ul>
2179
+ ** </dd>
2064
2180
  ** </dl>
2065
2181
  */
2066
2182
  #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
@@ -2071,7 +2187,10 @@ struct sqlite3_mem_methods {
2071
2187
  #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
2072
2188
  #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
2073
2189
  #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
2074
-
2190
+ #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
2191
+ #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
2192
+ #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
2193
+ #define SQLITE_DBCONFIG_MAX 1010 /* Largest DBCONFIG */
2075
2194
 
2076
2195
  /*
2077
2196
  ** CAPI3REF: Enable Or Disable Extended Result Codes
@@ -2098,8 +2217,8 @@ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2098
2217
  ** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
2099
2218
  ** the most recent successful [INSERT] into a rowid table or [virtual table]
2100
2219
  ** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
2101
- ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
2102
- ** on the database connection D, then sqlite3_last_insert_rowid(D) returns
2220
+ ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
2221
+ ** on the database connection D, then sqlite3_last_insert_rowid(D) returns
2103
2222
  ** zero.
2104
2223
  **
2105
2224
  ** As well as being set automatically as rows are inserted into database
@@ -2109,15 +2228,15 @@ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2109
2228
  ** Some virtual table implementations may INSERT rows into rowid tables as
2110
2229
  ** part of committing a transaction (e.g. to flush data accumulated in memory
2111
2230
  ** to disk). In this case subsequent calls to this function return the rowid
2112
- ** associated with these internal INSERT operations, which leads to
2231
+ ** associated with these internal INSERT operations, which leads to
2113
2232
  ** unintuitive results. Virtual table implementations that do write to rowid
2114
- ** tables in this way can avoid this problem by restoring the original
2115
- ** rowid value using [sqlite3_set_last_insert_rowid()] before returning
2233
+ ** tables in this way can avoid this problem by restoring the original
2234
+ ** rowid value using [sqlite3_set_last_insert_rowid()] before returning
2116
2235
  ** control to the user.
2117
2236
  **
2118
- ** ^(If an [INSERT] occurs within a trigger then this routine will
2119
- ** return the [rowid] of the inserted row as long as the trigger is
2120
- ** running. Once the trigger program ends, the value returned
2237
+ ** ^(If an [INSERT] occurs within a trigger then this routine will
2238
+ ** return the [rowid] of the inserted row as long as the trigger is
2239
+ ** running. Once the trigger program ends, the value returned
2121
2240
  ** by this routine reverts to what it was before the trigger was fired.)^
2122
2241
  **
2123
2242
  ** ^An [INSERT] that fails due to a constraint violation is not a
@@ -2150,7 +2269,7 @@ SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2150
2269
  ** METHOD: sqlite3
2151
2270
  **
2152
2271
  ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
2153
- ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2272
+ ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2154
2273
  ** without inserting a row into the database.
2155
2274
  */
2156
2275
  SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
@@ -2199,12 +2318,17 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2199
2318
  ** program, the value returned reflects the number of rows modified by the
2200
2319
  ** previous INSERT, UPDATE or DELETE statement within the same trigger.
2201
2320
  **
2202
- ** See also the [sqlite3_total_changes()] interface, the
2203
- ** [count_changes pragma], and the [changes() SQL function].
2204
- **
2205
2321
  ** If a separate thread makes changes on the same database connection
2206
2322
  ** while [sqlite3_changes()] is running then the value returned
2207
2323
  ** is unpredictable and not meaningful.
2324
+ **
2325
+ ** See also:
2326
+ ** <ul>
2327
+ ** <li> the [sqlite3_total_changes()] interface
2328
+ ** <li> the [count_changes pragma]
2329
+ ** <li> the [changes() SQL function]
2330
+ ** <li> the [data_version pragma]
2331
+ ** </ul>
2208
2332
  */
2209
2333
  SQLITE_API int sqlite3_changes(sqlite3*);
2210
2334
 
@@ -2222,13 +2346,26 @@ SQLITE_API int sqlite3_changes(sqlite3*);
2222
2346
  ** count, but those made as part of REPLACE constraint resolution are
2223
2347
  ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2224
2348
  ** are not counted.
2225
- **
2226
- ** See also the [sqlite3_changes()] interface, the
2227
- ** [count_changes pragma], and the [total_changes() SQL function].
2228
2349
  **
2350
+ ** This the [sqlite3_total_changes(D)] interface only reports the number
2351
+ ** of rows that changed due to SQL statement run against database
2352
+ ** connection D. Any changes by other database connections are ignored.
2353
+ ** To detect changes against a database file from other database
2354
+ ** connections use the [PRAGMA data_version] command or the
2355
+ ** [SQLITE_FCNTL_DATA_VERSION] [file control].
2356
+ **
2229
2357
  ** If a separate thread makes changes on the same database connection
2230
2358
  ** while [sqlite3_total_changes()] is running then the value
2231
2359
  ** returned is unpredictable and not meaningful.
2360
+ **
2361
+ ** See also:
2362
+ ** <ul>
2363
+ ** <li> the [sqlite3_changes()] interface
2364
+ ** <li> the [count_changes pragma]
2365
+ ** <li> the [changes() SQL function]
2366
+ ** <li> the [data_version pragma]
2367
+ ** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
2368
+ ** </ul>
2232
2369
  */
2233
2370
  SQLITE_API int sqlite3_total_changes(sqlite3*);
2234
2371
 
@@ -2477,16 +2614,16 @@ SQLITE_API void sqlite3_free_table(char **result);
2477
2614
  **
2478
2615
  ** These routines are work-alikes of the "printf()" family of functions
2479
2616
  ** from the standard C library.
2480
- ** These routines understand most of the common K&R formatting options,
2481
- ** plus some additional non-standard formats, detailed below.
2482
- ** Note that some of the more obscure formatting options from recent
2483
- ** C-library standards are omitted from this implementation.
2617
+ ** These routines understand most of the common formatting options from
2618
+ ** the standard library printf()
2619
+ ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
2620
+ ** See the [built-in printf()] documentation for details.
2484
2621
  **
2485
2622
  ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2486
- ** results into memory obtained from [sqlite3_malloc()].
2623
+ ** results into memory obtained from [sqlite3_malloc64()].
2487
2624
  ** The strings returned by these two routines should be
2488
2625
  ** released by [sqlite3_free()]. ^Both routines return a
2489
- ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
2626
+ ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
2490
2627
  ** memory to hold the resulting string.
2491
2628
  **
2492
2629
  ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
@@ -2510,71 +2647,7 @@ SQLITE_API void sqlite3_free_table(char **result);
2510
2647
  **
2511
2648
  ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2512
2649
  **
2513
- ** These routines all implement some additional formatting
2514
- ** options that are useful for constructing SQL statements.
2515
- ** All of the usual printf() formatting options apply. In addition, there
2516
- ** is are "%q", "%Q", "%w" and "%z" options.
2517
- **
2518
- ** ^(The %q option works like %s in that it substitutes a nul-terminated
2519
- ** string from the argument list. But %q also doubles every '\'' character.
2520
- ** %q is designed for use inside a string literal.)^ By doubling each '\''
2521
- ** character it escapes that character and allows it to be inserted into
2522
- ** the string.
2523
- **
2524
- ** For example, assume the string variable zText contains text as follows:
2525
- **
2526
- ** <blockquote><pre>
2527
- ** char *zText = "It's a happy day!";
2528
- ** </pre></blockquote>
2529
- **
2530
- ** One can use this text in an SQL statement as follows:
2531
- **
2532
- ** <blockquote><pre>
2533
- ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
2534
- ** sqlite3_exec(db, zSQL, 0, 0, 0);
2535
- ** sqlite3_free(zSQL);
2536
- ** </pre></blockquote>
2537
- **
2538
- ** Because the %q format string is used, the '\'' character in zText
2539
- ** is escaped and the SQL generated is as follows:
2540
- **
2541
- ** <blockquote><pre>
2542
- ** INSERT INTO table1 VALUES('It''s a happy day!')
2543
- ** </pre></blockquote>
2544
- **
2545
- ** This is correct. Had we used %s instead of %q, the generated SQL
2546
- ** would have looked like this:
2547
- **
2548
- ** <blockquote><pre>
2549
- ** INSERT INTO table1 VALUES('It's a happy day!');
2550
- ** </pre></blockquote>
2551
- **
2552
- ** This second example is an SQL syntax error. As a general rule you should
2553
- ** always use %q instead of %s when inserting text into a string literal.
2554
- **
2555
- ** ^(The %Q option works like %q except it also adds single quotes around
2556
- ** the outside of the total string. Additionally, if the parameter in the
2557
- ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2558
- ** single quotes).)^ So, for example, one could say:
2559
- **
2560
- ** <blockquote><pre>
2561
- ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
2562
- ** sqlite3_exec(db, zSQL, 0, 0, 0);
2563
- ** sqlite3_free(zSQL);
2564
- ** </pre></blockquote>
2565
- **
2566
- ** The code above will render a correct SQL statement in the zSQL
2567
- ** variable even if the zText variable is a NULL pointer.
2568
- **
2569
- ** ^(The "%w" formatting option is like "%q" except that it expects to
2570
- ** be contained within double-quotes instead of single quotes, and it
2571
- ** escapes the double-quote character instead of the single-quote
2572
- ** character.)^ The "%w" formatting option is intended for safely inserting
2573
- ** table and column names into a constructed SQL statement.
2574
- **
2575
- ** ^(The "%z" formatting option works like "%s" but with the
2576
- ** addition that after the string has been read and copied into
2577
- ** the result, [sqlite3_free()] is called on the input string.)^
2650
+ ** See also: [built-in printf()], [printf() SQL function]
2578
2651
  */
2579
2652
  SQLITE_API char *sqlite3_mprintf(const char*,...);
2580
2653
  SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
@@ -2932,8 +3005,8 @@ SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
2932
3005
  ** KEYWORDS: SQLITE_TRACE
2933
3006
  **
2934
3007
  ** These constants identify classes of events that can be monitored
2935
- ** using the [sqlite3_trace_v2()] tracing logic. The third argument
2936
- ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
3008
+ ** using the [sqlite3_trace_v2()] tracing logic. The M argument
3009
+ ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
2937
3010
  ** the following constants. ^The first argument to the trace callback
2938
3011
  ** is one of the following constants.
2939
3012
  **
@@ -2952,7 +3025,7 @@ SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
2952
3025
  ** execution of the prepared statement, such as at the start of each
2953
3026
  ** trigger subprogram. ^The P argument is a pointer to the
2954
3027
  ** [prepared statement]. ^The X argument is a pointer to a string which
2955
- ** is the unexpanded SQL text of the prepared statement or an SQL comment
3028
+ ** is the unexpanded SQL text of the prepared statement or an SQL comment
2956
3029
  ** that indicates the invocation of a trigger. ^The callback can compute
2957
3030
  ** the same text that would have been returned by the legacy [sqlite3_trace()]
2958
3031
  ** interface by using the X argument when X begins with "--" and invoking
@@ -2968,7 +3041,7 @@ SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
2968
3041
  **
2969
3042
  ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
2970
3043
  ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
2971
- ** statement generates a single row of result.
3044
+ ** statement generates a single row of result.
2972
3045
  ** ^The P argument is a pointer to the [prepared statement] and the
2973
3046
  ** X argument is unused.
2974
3047
  **
@@ -2995,10 +3068,10 @@ SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
2995
3068
  ** M argument should be the bitwise OR-ed combination of
2996
3069
  ** zero or more [SQLITE_TRACE] constants.
2997
3070
  **
2998
- ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
3071
+ ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
2999
3072
  ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
3000
3073
  **
3001
- ** ^The X callback is invoked whenever any of the events identified by
3074
+ ** ^The X callback is invoked whenever any of the events identified by
3002
3075
  ** mask M occur. ^The integer return value from the callback is currently
3003
3076
  ** ignored, though this may change in future releases. Callback
3004
3077
  ** implementations should return zero to ensure future compatibility.
@@ -3348,13 +3421,24 @@ SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int
3348
3421
  ** [database connection] D failed, then the sqlite3_errcode(D) interface
3349
3422
  ** returns the numeric [result code] or [extended result code] for that
3350
3423
  ** API call.
3351
- ** If the most recent API call was successful,
3352
- ** then the return value from sqlite3_errcode() is undefined.
3353
3424
  ** ^The sqlite3_extended_errcode()
3354
3425
  ** interface is the same except that it always returns the
3355
3426
  ** [extended result code] even when extended result codes are
3356
3427
  ** disabled.
3357
3428
  **
3429
+ ** The values returned by sqlite3_errcode() and/or
3430
+ ** sqlite3_extended_errcode() might change with each API call.
3431
+ ** Except, there are some interfaces that are guaranteed to never
3432
+ ** change the value of the error code. The error-code preserving
3433
+ ** interfaces are:
3434
+ **
3435
+ ** <ul>
3436
+ ** <li> sqlite3_errcode()
3437
+ ** <li> sqlite3_extended_errcode()
3438
+ ** <li> sqlite3_errmsg()
3439
+ ** <li> sqlite3_errmsg16()
3440
+ ** </ul>
3441
+ **
3358
3442
  ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3359
3443
  ** text that describes the error, as either UTF-8 or UTF-16 respectively.
3360
3444
  ** ^(Memory to hold the error message string is managed internally.
@@ -3538,15 +3622,25 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3538
3622
  ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
3539
3623
  ** that the prepared statement will be retained for a long time and
3540
3624
  ** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
3541
- ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
3625
+ ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
3542
3626
  ** be used just once or at most a few times and then destroyed using
3543
3627
  ** [sqlite3_finalize()] relatively soon. The current implementation acts
3544
3628
  ** on this hint by avoiding the use of [lookaside memory] so as not to
3545
3629
  ** deplete the limited store of lookaside memory. Future versions of
3546
3630
  ** SQLite may act on this hint differently.
3631
+ **
3632
+ ** [[SQLITE_PREPARE_NORMALIZE]] ^(<dt>SQLITE_PREPARE_NORMALIZE</dt>
3633
+ ** <dd>The SQLITE_PREPARE_NORMALIZE flag indicates that a normalized
3634
+ ** representation of the SQL statement should be calculated and then
3635
+ ** associated with the prepared statement, which can be obtained via
3636
+ ** the [sqlite3_normalized_sql()] interface.)^ The semantics used to
3637
+ ** normalize a SQL statement are unspecified and subject to change.
3638
+ ** At a minimum, literal values will be replaced with suitable
3639
+ ** placeholders.
3547
3640
  ** </dl>
3548
3641
  */
3549
3642
  #define SQLITE_PREPARE_PERSISTENT 0x01
3643
+ #define SQLITE_PREPARE_NORMALIZE 0x02
3550
3644
 
3551
3645
  /*
3552
3646
  ** CAPI3REF: Compiling An SQL Statement
@@ -3640,13 +3734,13 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3640
3734
  ** or [GLOB] operator or if the parameter is compared to an indexed column
3641
3735
  ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3642
3736
  ** </li>
3737
+ ** </ol>
3643
3738
  **
3644
3739
  ** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
3645
3740
  ** the extra prepFlags parameter, which is a bit array consisting of zero or
3646
3741
  ** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
3647
3742
  ** sqlite3_prepare_v2() interface works exactly the same as
3648
3743
  ** sqlite3_prepare_v3() with a zero prepFlags parameter.
3649
- ** </ol>
3650
3744
  */
3651
3745
  SQLITE_API int sqlite3_prepare(
3652
3746
  sqlite3 *db, /* Database handle */
@@ -3704,6 +3798,11 @@ SQLITE_API int sqlite3_prepare16_v3(
3704
3798
  ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
3705
3799
  ** string containing the SQL text of prepared statement P with
3706
3800
  ** [bound parameters] expanded.
3801
+ ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
3802
+ ** string containing the normalized SQL text of prepared statement P. The
3803
+ ** semantics used to normalize a SQL statement are unspecified and subject
3804
+ ** to change. At a minimum, literal values will be replaced with suitable
3805
+ ** placeholders.
3707
3806
  **
3708
3807
  ** ^(For example, if a prepared statement is created using the SQL
3709
3808
  ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
@@ -3719,14 +3818,16 @@ SQLITE_API int sqlite3_prepare16_v3(
3719
3818
  ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
3720
3819
  ** option causes sqlite3_expanded_sql() to always return NULL.
3721
3820
  **
3722
- ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
3723
- ** automatically freed when the prepared statement is finalized.
3821
+ ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
3822
+ ** are managed by SQLite and are automatically freed when the prepared
3823
+ ** statement is finalized.
3724
3824
  ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
3725
3825
  ** is obtained from [sqlite3_malloc()] and must be free by the application
3726
3826
  ** by passing it to [sqlite3_free()].
3727
3827
  */
3728
3828
  SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
3729
3829
  SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
3830
+ SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
3730
3831
 
3731
3832
  /*
3732
3833
  ** CAPI3REF: Determine If An SQL Statement Writes The Database
@@ -4055,7 +4156,7 @@ SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
4055
4156
  ** METHOD: sqlite3_stmt
4056
4157
  **
4057
4158
  ** ^Return the number of columns in the result set returned by the
4058
- ** [prepared statement]. ^If this routine returns 0, that means the
4159
+ ** [prepared statement]. ^If this routine returns 0, that means the
4059
4160
  ** [prepared statement] returns no data (for example an [UPDATE]).
4060
4161
  ** ^However, just because this routine returns a positive number does not
4061
4162
  ** mean that one or more rows of data will be returned. ^A SELECT statement
@@ -4332,7 +4433,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4332
4433
  ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
4333
4434
  ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
4334
4435
  ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
4335
- ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
4436
+ ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
4336
4437
  ** [sqlite3_value|unprotected sqlite3_value] object.
4337
4438
  ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
4338
4439
  ** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
@@ -4380,7 +4481,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4380
4481
  ** The return value of sqlite3_column_type() can be used to decide which
4381
4482
  ** of the first six interface should be used to extract the column value.
4382
4483
  ** The value returned by sqlite3_column_type() is only meaningful if no
4383
- ** automatic type conversions have occurred for the value in question.
4484
+ ** automatic type conversions have occurred for the value in question.
4384
4485
  ** After a type conversion, the result of calling sqlite3_column_type()
4385
4486
  ** is undefined, though harmless. Future
4386
4487
  ** versions of SQLite may change the behavior of sqlite3_column_type()
@@ -4427,7 +4528,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4427
4528
  ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
4428
4529
  ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
4429
4530
  ** Hence, the sqlite3_column_value() interface
4430
- ** is normally only useful within the implementation of
4531
+ ** is normally only useful within the implementation of
4431
4532
  ** [application-defined SQL functions] or [virtual tables], not within
4432
4533
  ** top-level application code.
4433
4534
  **
@@ -4508,11 +4609,25 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4508
4609
  ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
4509
4610
  ** [sqlite3_free()].
4510
4611
  **
4511
- ** ^(If a memory allocation error occurs during the evaluation of any
4512
- ** of these routines, a default value is returned. The default value
4513
- ** is either the integer 0, the floating point number 0.0, or a NULL
4514
- ** pointer. Subsequent calls to [sqlite3_errcode()] will return
4515
- ** [SQLITE_NOMEM].)^
4612
+ ** As long as the input parameters are correct, these routines will only
4613
+ ** fail if an out-of-memory error occurs during a format conversion.
4614
+ ** Only the following subset of interfaces are subject to out-of-memory
4615
+ ** errors:
4616
+ **
4617
+ ** <ul>
4618
+ ** <li> sqlite3_column_blob()
4619
+ ** <li> sqlite3_column_text()
4620
+ ** <li> sqlite3_column_text16()
4621
+ ** <li> sqlite3_column_bytes()
4622
+ ** <li> sqlite3_column_bytes16()
4623
+ ** </ul>
4624
+ **
4625
+ ** If an out-of-memory error occurs, then the return value from these
4626
+ ** routines is the same as if the column had contained an SQL NULL value.
4627
+ ** Valid SQL NULL returns can be distinguished from out-of-memory errors
4628
+ ** by invoking the [sqlite3_errcode()] immediately after the suspect
4629
+ ** return value is obtained and before any
4630
+ ** other SQLite interface is called on the same [database connection].
4516
4631
  */
4517
4632
  SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
4518
4633
  SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
@@ -4589,11 +4704,13 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4589
4704
  **
4590
4705
  ** ^These functions (collectively known as "function creation routines")
4591
4706
  ** are used to add SQL functions or aggregates or to redefine the behavior
4592
- ** of existing SQL functions or aggregates. The only differences between
4593
- ** these routines are the text encoding expected for
4594
- ** the second parameter (the name of the function being created)
4595
- ** and the presence or absence of a destructor callback for
4596
- ** the application data pointer.
4707
+ ** of existing SQL functions or aggregates. The only differences between
4708
+ ** the three "sqlite3_create_function*" routines are the text encoding
4709
+ ** expected for the second parameter (the name of the function being
4710
+ ** created) and the presence or absence of a destructor callback for
4711
+ ** the application data pointer. Function sqlite3_create_window_function()
4712
+ ** is similar, but allows the user to supply the extra callback functions
4713
+ ** needed by [aggregate window functions].
4597
4714
  **
4598
4715
  ** ^The first parameter is the [database connection] to which the SQL
4599
4716
  ** function is to be added. ^If an application uses more than one database
@@ -4639,7 +4756,8 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4639
4756
  ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
4640
4757
  ** function can gain access to this pointer using [sqlite3_user_data()].)^
4641
4758
  **
4642
- ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
4759
+ ** ^The sixth, seventh and eighth parameters passed to the three
4760
+ ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
4643
4761
  ** pointers to C-language functions that implement the SQL function or
4644
4762
  ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
4645
4763
  ** callback only; NULL pointers must be passed as the xStep and xFinal
@@ -4648,15 +4766,24 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4648
4766
  ** SQL function or aggregate, pass NULL pointers for all three function
4649
4767
  ** callbacks.
4650
4768
  **
4651
- ** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
4652
- ** then it is destructor for the application data pointer.
4653
- ** The destructor is invoked when the function is deleted, either by being
4654
- ** overloaded or when the database connection closes.)^
4655
- ** ^The destructor is also invoked if the call to
4656
- ** sqlite3_create_function_v2() fails.
4657
- ** ^When the destructor callback of the tenth parameter is invoked, it
4658
- ** is passed a single argument which is a copy of the application data
4659
- ** pointer which was the fifth parameter to sqlite3_create_function_v2().
4769
+ ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
4770
+ ** and xInverse) passed to sqlite3_create_window_function are pointers to
4771
+ ** C-language callbacks that implement the new function. xStep and xFinal
4772
+ ** must both be non-NULL. xValue and xInverse may either both be NULL, in
4773
+ ** which case a regular aggregate function is created, or must both be
4774
+ ** non-NULL, in which case the new function may be used as either an aggregate
4775
+ ** or aggregate window function. More details regarding the implementation
4776
+ ** of aggregate window functions are
4777
+ ** [user-defined window functions|available here].
4778
+ **
4779
+ ** ^(If the final parameter to sqlite3_create_function_v2() or
4780
+ ** sqlite3_create_window_function() is not NULL, then it is destructor for
4781
+ ** the application data pointer. The destructor is invoked when the function
4782
+ ** is deleted, either by being overloaded or when the database connection
4783
+ ** closes.)^ ^The destructor is also invoked if the call to
4784
+ ** sqlite3_create_function_v2() fails. ^When the destructor callback is
4785
+ ** invoked, it is passed a single argument which is a copy of the application
4786
+ ** data pointer which was the fifth parameter to sqlite3_create_function_v2().
4660
4787
  **
4661
4788
  ** ^It is permitted to register multiple implementations of the same
4662
4789
  ** functions with the same name but with either differing numbers of
@@ -4709,6 +4836,18 @@ SQLITE_API int sqlite3_create_function_v2(
4709
4836
  void (*xFinal)(sqlite3_context*),
4710
4837
  void(*xDestroy)(void*)
4711
4838
  );
4839
+ SQLITE_API int sqlite3_create_window_function(
4840
+ sqlite3 *db,
4841
+ const char *zFunctionName,
4842
+ int nArg,
4843
+ int eTextRep,
4844
+ void *pApp,
4845
+ void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4846
+ void (*xFinal)(sqlite3_context*),
4847
+ void (*xValue)(sqlite3_context*),
4848
+ void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
4849
+ void(*xDestroy)(void*)
4850
+ );
4712
4851
 
4713
4852
  /*
4714
4853
  ** CAPI3REF: Text Encodings
@@ -4779,6 +4918,9 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4779
4918
  ** datatype of the value
4780
4919
  ** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
4781
4920
  ** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
4921
+ ** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
4922
+ ** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
4923
+ ** against a virtual table.
4782
4924
  ** </table></blockquote>
4783
4925
  **
4784
4926
  ** <b>Details:</b>
@@ -4801,11 +4943,11 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4801
4943
  ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
4802
4944
  ** extract UTF-16 strings as big-endian and little-endian respectively.
4803
4945
  **
4804
- ** ^If [sqlite3_value] object V was initialized
4946
+ ** ^If [sqlite3_value] object V was initialized
4805
4947
  ** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
4806
4948
  ** and if X and Y are strings that compare equal according to strcmp(X,Y),
4807
4949
  ** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,
4808
- ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
4950
+ ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
4809
4951
  ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
4810
4952
  **
4811
4953
  ** ^(The sqlite3_value_type(V) interface returns the
@@ -4827,6 +4969,19 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4827
4969
  ** then the conversion is performed. Otherwise no conversion occurs.
4828
4970
  ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
4829
4971
  **
4972
+ ** ^Within the [xUpdate] method of a [virtual table], the
4973
+ ** sqlite3_value_nochange(X) interface returns true if and only if
4974
+ ** the column corresponding to X is unchanged by the UPDATE operation
4975
+ ** that the xUpdate method call was invoked to implement and if
4976
+ ** and the prior [xColumn] method call that was invoked to extracted
4977
+ ** the value for that column returned without setting a result (probably
4978
+ ** because it queried [sqlite3_vtab_nochange()] and found that the column
4979
+ ** was unchanging). ^Within an [xUpdate] method, any value for which
4980
+ ** sqlite3_value_nochange(X) is true will in all other respects appear
4981
+ ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
4982
+ ** than within an [xUpdate] method call for an UPDATE statement, then
4983
+ ** the return value is arbitrary and meaningless.
4984
+ **
4830
4985
  ** Please pay particular attention to the fact that the pointer returned
4831
4986
  ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
4832
4987
  ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
@@ -4835,6 +4990,28 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4835
4990
  **
4836
4991
  ** These routines must be called from the same thread as
4837
4992
  ** the SQL function that supplied the [sqlite3_value*] parameters.
4993
+ **
4994
+ ** As long as the input parameter is correct, these routines can only
4995
+ ** fail if an out-of-memory error occurs during a format conversion.
4996
+ ** Only the following subset of interfaces are subject to out-of-memory
4997
+ ** errors:
4998
+ **
4999
+ ** <ul>
5000
+ ** <li> sqlite3_value_blob()
5001
+ ** <li> sqlite3_value_text()
5002
+ ** <li> sqlite3_value_text16()
5003
+ ** <li> sqlite3_value_text16le()
5004
+ ** <li> sqlite3_value_text16be()
5005
+ ** <li> sqlite3_value_bytes()
5006
+ ** <li> sqlite3_value_bytes16()
5007
+ ** </ul>
5008
+ **
5009
+ ** If an out-of-memory error occurs, then the return value from these
5010
+ ** routines is the same as if the column had contained an SQL NULL value.
5011
+ ** Valid SQL NULL returns can be distinguished from out-of-memory errors
5012
+ ** by invoking the [sqlite3_errcode()] immediately after the suspect
5013
+ ** return value is obtained and before any
5014
+ ** other SQLite interface is called on the same [database connection].
4838
5015
  */
4839
5016
  SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
4840
5017
  SQLITE_API double sqlite3_value_double(sqlite3_value*);
@@ -4849,6 +5026,7 @@ SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
4849
5026
  SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
4850
5027
  SQLITE_API int sqlite3_value_type(sqlite3_value*);
4851
5028
  SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
5029
+ SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
4852
5030
 
4853
5031
  /*
4854
5032
  ** CAPI3REF: Finding The Subtype Of SQL Values
@@ -4987,7 +5165,7 @@ SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
4987
5165
  ** SQL statement)^, or
4988
5166
  ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
4989
5167
  ** parameter)^, or
4990
- ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
5168
+ ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
4991
5169
  ** allocation error occurs.)^ </ul>
4992
5170
  **
4993
5171
  ** Note the last bullet in particular. The destructor X in
@@ -5143,7 +5321,7 @@ typedef void (*sqlite3_destructor_type)(void*);
5143
5321
  **
5144
5322
  ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
5145
5323
  ** SQL NULL value, just like [sqlite3_result_null(C)], except that it
5146
- ** also associates the host-language pointer P or type T with that
5324
+ ** also associates the host-language pointer P or type T with that
5147
5325
  ** NULL value such that the pointer can be retrieved within an
5148
5326
  ** [application-defined SQL function] using [sqlite3_value_pointer()].
5149
5327
  ** ^If the D parameter is not NULL, then it is a pointer to a destructor
@@ -5504,6 +5682,41 @@ SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
5504
5682
  */
5505
5683
  SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
5506
5684
 
5685
+ /*
5686
+ ** CAPI3REF: Win32 Specific Interface
5687
+ **
5688
+ ** These interfaces are available only on Windows. The
5689
+ ** [sqlite3_win32_set_directory] interface is used to set the value associated
5690
+ ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
5691
+ ** zValue, depending on the value of the type parameter. The zValue parameter
5692
+ ** should be NULL to cause the previous value to be freed via [sqlite3_free];
5693
+ ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
5694
+ ** prior to being used. The [sqlite3_win32_set_directory] interface returns
5695
+ ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
5696
+ ** or [SQLITE_NOMEM] if memory could not be allocated. The value of the
5697
+ ** [sqlite3_data_directory] variable is intended to act as a replacement for
5698
+ ** the current directory on the sub-platforms of Win32 where that concept is
5699
+ ** not present, e.g. WinRT and UWP. The [sqlite3_win32_set_directory8] and
5700
+ ** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
5701
+ ** sqlite3_win32_set_directory interface except the string parameter must be
5702
+ ** UTF-8 or UTF-16, respectively.
5703
+ */
5704
+ SQLITE_API int sqlite3_win32_set_directory(
5705
+ unsigned long type, /* Identifier for directory being set or reset */
5706
+ void *zValue /* New value for directory being set or reset */
5707
+ );
5708
+ SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
5709
+ SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
5710
+
5711
+ /*
5712
+ ** CAPI3REF: Win32 Directory Types
5713
+ **
5714
+ ** These macros are only available on Windows. They define the allowed values
5715
+ ** for the type argument to the [sqlite3_win32_set_directory] interface.
5716
+ */
5717
+ #define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1
5718
+ #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2
5719
+
5507
5720
  /*
5508
5721
  ** CAPI3REF: Test For Auto-Commit Mode
5509
5722
  ** KEYWORDS: {autocommit mode}
@@ -5698,7 +5911,7 @@ SQLITE_API void *sqlite3_update_hook(
5698
5911
  ** and disabled if the argument is false.)^
5699
5912
  **
5700
5913
  ** ^Cache sharing is enabled and disabled for an entire process.
5701
- ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
5914
+ ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
5702
5915
  ** In prior versions of SQLite,
5703
5916
  ** sharing was enabled or disabled for each thread separately.
5704
5917
  **
@@ -5793,7 +6006,7 @@ SQLITE_API int sqlite3_db_release_memory(sqlite3*);
5793
6006
  ** from the heap.
5794
6007
  ** </ul>)^
5795
6008
  **
5796
- ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
6009
+ ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
5797
6010
  ** the soft heap limit is enforced
5798
6011
  ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
5799
6012
  ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
@@ -5937,7 +6150,7 @@ SQLITE_API int sqlite3_table_column_metadata(
5937
6150
  ** prior to calling this API,
5938
6151
  ** otherwise an error will be returned.
5939
6152
  **
5940
- ** <b>Security warning:</b> It is recommended that the
6153
+ ** <b>Security warning:</b> It is recommended that the
5941
6154
  ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
5942
6155
  ** interface. The use of the [sqlite3_enable_load_extension()] interface
5943
6156
  ** should be avoided. This will keep the SQL function [load_extension()]
@@ -6104,6 +6317,9 @@ struct sqlite3_module {
6104
6317
  int (*xSavepoint)(sqlite3_vtab *pVTab, int);
6105
6318
  int (*xRelease)(sqlite3_vtab *pVTab, int);
6106
6319
  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
6320
+ /* The methods above are in versions 1 and 2 of the sqlite_module object.
6321
+ ** Those below are for version 3 and greater. */
6322
+ int (*xShadowName)(const char*);
6107
6323
  };
6108
6324
 
6109
6325
  /*
@@ -6146,7 +6362,7 @@ struct sqlite3_module {
6146
6362
  ** required by SQLite. If the table has at least 64 columns and any column
6147
6363
  ** to the right of the first 63 is required, then bit 63 of colUsed is also
6148
6364
  ** set. In other words, column iCol may be required if the expression
6149
- ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
6365
+ ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
6150
6366
  ** non-zero.
6151
6367
  **
6152
6368
  ** The [xBestIndex] method must fill aConstraintUsage[] with information
@@ -6190,14 +6406,14 @@ struct sqlite3_module {
6190
6406
  ** the xUpdate method are automatically rolled back by SQLite.
6191
6407
  **
6192
6408
  ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
6193
- ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
6409
+ ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
6194
6410
  ** If a virtual table extension is
6195
6411
  ** used with an SQLite version earlier than 3.8.2, the results of attempting
6196
6412
  ** to read or write the estimatedRows field are undefined (but are likely
6197
6413
  ** to included crashing the application). The estimatedRows field should
6198
6414
  ** therefore only be used if [sqlite3_libversion_number()] returns a
6199
6415
  ** value greater than or equal to 3008002. Similarly, the idxFlags field
6200
- ** was added for [version 3.9.0] ([dateof:3.9.0]).
6416
+ ** was added for [version 3.9.0] ([dateof:3.9.0]).
6201
6417
  ** It may therefore only be used if
6202
6418
  ** sqlite3_libversion_number() returns a value greater than or equal to
6203
6419
  ** 3009000.
@@ -6236,6 +6452,10 @@ struct sqlite3_index_info {
6236
6452
 
6237
6453
  /*
6238
6454
  ** CAPI3REF: Virtual Table Scan Flags
6455
+ **
6456
+ ** Virtual table implementations are allowed to set the
6457
+ ** [sqlite3_index_info].idxFlags field to some combination of
6458
+ ** these bits.
6239
6459
  */
6240
6460
  #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
6241
6461
 
@@ -6261,6 +6481,7 @@ struct sqlite3_index_info {
6261
6481
  #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
6262
6482
  #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
6263
6483
  #define SQLITE_INDEX_CONSTRAINT_IS 72
6484
+ #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
6264
6485
 
6265
6486
  /*
6266
6487
  ** CAPI3REF: Register A Virtual Table Implementation
@@ -6937,6 +7158,7 @@ SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
6937
7158
  /*
6938
7159
  ** CAPI3REF: Low-Level Control Of Database Files
6939
7160
  ** METHOD: sqlite3
7161
+ ** KEYWORDS: {file control}
6940
7162
  **
6941
7163
  ** ^The [sqlite3_file_control()] interface makes a direct call to the
6942
7164
  ** xFileControl method for the [sqlite3_io_methods] object associated
@@ -6951,11 +7173,18 @@ SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
6951
7173
  ** the xFileControl method. ^The return value of the xFileControl
6952
7174
  ** method becomes the return value of this routine.
6953
7175
  **
6954
- ** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
7176
+ ** A few opcodes for [sqlite3_file_control()] are handled directly
7177
+ ** by the SQLite core and never invoke the
7178
+ ** sqlite3_io_methods.xFileControl method.
7179
+ ** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes
6955
7180
  ** a pointer to the underlying [sqlite3_file] object to be written into
6956
- ** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER
6957
- ** case is a short-circuit path which does not actually invoke the
6958
- ** underlying sqlite3_io_methods.xFileControl method.
7181
+ ** the space pointed to by the 4th parameter. The
7182
+ ** [SQLITE_FCNTL_JOURNAL_POINTER] works similarly except that it returns
7183
+ ** the [sqlite3_file] object associated with the journal file instead of
7184
+ ** the main database. The [SQLITE_FCNTL_VFS_POINTER] opcode returns
7185
+ ** a pointer to the underlying [sqlite3_vfs] object for the file.
7186
+ ** The [SQLITE_FCNTL_DATA_VERSION] returns the data version counter
7187
+ ** from the pager.
6959
7188
  **
6960
7189
  ** ^If the second parameter (zDbName) does not match the name of any
6961
7190
  ** open database file, then SQLITE_ERROR is returned. ^This error
@@ -6965,7 +7194,7 @@ SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
6965
7194
  ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
6966
7195
  ** xFileControl method.
6967
7196
  **
6968
- ** See also: [SQLITE_FCNTL_LOCKSTATE]
7197
+ ** See also: [file control opcodes]
6969
7198
  */
6970
7199
  SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
6971
7200
 
@@ -7011,8 +7240,9 @@ SQLITE_API int sqlite3_test_control(int op, ...);
7011
7240
  #define SQLITE_TESTCTRL_ALWAYS 13
7012
7241
  #define SQLITE_TESTCTRL_RESERVE 14
7013
7242
  #define SQLITE_TESTCTRL_OPTIMIZATIONS 15
7014
- #define SQLITE_TESTCTRL_ISKEYWORD 16
7243
+ #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */
7015
7244
  #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
7245
+ #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17
7016
7246
  #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
7017
7247
  #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
7018
7248
  #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
@@ -7022,7 +7252,191 @@ SQLITE_API int sqlite3_test_control(int op, ...);
7022
7252
  #define SQLITE_TESTCTRL_ISINIT 23
7023
7253
  #define SQLITE_TESTCTRL_SORTER_MMAP 24
7024
7254
  #define SQLITE_TESTCTRL_IMPOSTER 25
7025
- #define SQLITE_TESTCTRL_LAST 25
7255
+ #define SQLITE_TESTCTRL_PARSER_COVERAGE 26
7256
+ #define SQLITE_TESTCTRL_LAST 26 /* Largest TESTCTRL */
7257
+
7258
+ /*
7259
+ ** CAPI3REF: SQL Keyword Checking
7260
+ **
7261
+ ** These routines provide access to the set of SQL language keywords
7262
+ ** recognized by SQLite. Applications can uses these routines to determine
7263
+ ** whether or not a specific identifier needs to be escaped (for example,
7264
+ ** by enclosing in double-quotes) so as not to confuse the parser.
7265
+ **
7266
+ ** The sqlite3_keyword_count() interface returns the number of distinct
7267
+ ** keywords understood by SQLite.
7268
+ **
7269
+ ** The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and
7270
+ ** makes *Z point to that keyword expressed as UTF8 and writes the number
7271
+ ** of bytes in the keyword into *L. The string that *Z points to is not
7272
+ ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
7273
+ ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
7274
+ ** or L are NULL or invalid pointers then calls to
7275
+ ** sqlite3_keyword_name(N,Z,L) result in undefined behavior.
7276
+ **
7277
+ ** The sqlite3_keyword_check(Z,L) interface checks to see whether or not
7278
+ ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
7279
+ ** if it is and zero if not.
7280
+ **
7281
+ ** The parser used by SQLite is forgiving. It is often possible to use
7282
+ ** a keyword as an identifier as long as such use does not result in a
7283
+ ** parsing ambiguity. For example, the statement
7284
+ ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
7285
+ ** creates a new table named "BEGIN" with three columns named
7286
+ ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
7287
+ ** using keywords as identifiers. Common techniques used to avoid keyword
7288
+ ** name collisions include:
7289
+ ** <ul>
7290
+ ** <li> Put all identifier names inside double-quotes. This is the official
7291
+ ** SQL way to escape identifier names.
7292
+ ** <li> Put identifier names inside &#91;...&#93;. This is not standard SQL,
7293
+ ** but it is what SQL Server does and so lots of programmers use this
7294
+ ** technique.
7295
+ ** <li> Begin every identifier with the letter "Z" as no SQL keywords start
7296
+ ** with "Z".
7297
+ ** <li> Include a digit somewhere in every identifier name.
7298
+ ** </ul>
7299
+ **
7300
+ ** Note that the number of keywords understood by SQLite can depend on
7301
+ ** compile-time options. For example, "VACUUM" is not a keyword if
7302
+ ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
7303
+ ** new keywords may be added to future releases of SQLite.
7304
+ */
7305
+ SQLITE_API int sqlite3_keyword_count(void);
7306
+ SQLITE_API int sqlite3_keyword_name(int,const char**,int*);
7307
+ SQLITE_API int sqlite3_keyword_check(const char*,int);
7308
+
7309
+ /*
7310
+ ** CAPI3REF: Dynamic String Object
7311
+ ** KEYWORDS: {dynamic string}
7312
+ **
7313
+ ** An instance of the sqlite3_str object contains a dynamically-sized
7314
+ ** string under construction.
7315
+ **
7316
+ ** The lifecycle of an sqlite3_str object is as follows:
7317
+ ** <ol>
7318
+ ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
7319
+ ** <li> ^Text is appended to the sqlite3_str object using various
7320
+ ** methods, such as [sqlite3_str_appendf()].
7321
+ ** <li> ^The sqlite3_str object is destroyed and the string it created
7322
+ ** is returned using the [sqlite3_str_finish()] interface.
7323
+ ** </ol>
7324
+ */
7325
+ typedef struct sqlite3_str sqlite3_str;
7326
+
7327
+ /*
7328
+ ** CAPI3REF: Create A New Dynamic String Object
7329
+ ** CONSTRUCTOR: sqlite3_str
7330
+ **
7331
+ ** ^The [sqlite3_str_new(D)] interface allocates and initializes
7332
+ ** a new [sqlite3_str] object. To avoid memory leaks, the object returned by
7333
+ ** [sqlite3_str_new()] must be freed by a subsequent call to
7334
+ ** [sqlite3_str_finish(X)].
7335
+ **
7336
+ ** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
7337
+ ** valid [sqlite3_str] object, though in the event of an out-of-memory
7338
+ ** error the returned object might be a special singleton that will
7339
+ ** silently reject new text, always return SQLITE_NOMEM from
7340
+ ** [sqlite3_str_errcode()], always return 0 for
7341
+ ** [sqlite3_str_length()], and always return NULL from
7342
+ ** [sqlite3_str_finish(X)]. It is always safe to use the value
7343
+ ** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter
7344
+ ** to any of the other [sqlite3_str] methods.
7345
+ **
7346
+ ** The D parameter to [sqlite3_str_new(D)] may be NULL. If the
7347
+ ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
7348
+ ** length of the string contained in the [sqlite3_str] object will be
7349
+ ** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead
7350
+ ** of [SQLITE_MAX_LENGTH].
7351
+ */
7352
+ SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);
7353
+
7354
+ /*
7355
+ ** CAPI3REF: Finalize A Dynamic String
7356
+ ** DESTRUCTOR: sqlite3_str
7357
+ **
7358
+ ** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X
7359
+ ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
7360
+ ** that contains the constructed string. The calling application should
7361
+ ** pass the returned value to [sqlite3_free()] to avoid a memory leak.
7362
+ ** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any
7363
+ ** errors were encountered during construction of the string. ^The
7364
+ ** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the
7365
+ ** string in [sqlite3_str] object X is zero bytes long.
7366
+ */
7367
+ SQLITE_API char *sqlite3_str_finish(sqlite3_str*);
7368
+
7369
+ /*
7370
+ ** CAPI3REF: Add Content To A Dynamic String
7371
+ ** METHOD: sqlite3_str
7372
+ **
7373
+ ** These interfaces add content to an sqlite3_str object previously obtained
7374
+ ** from [sqlite3_str_new()].
7375
+ **
7376
+ ** ^The [sqlite3_str_appendf(X,F,...)] and
7377
+ ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
7378
+ ** functionality of SQLite to append formatted text onto the end of
7379
+ ** [sqlite3_str] object X.
7380
+ **
7381
+ ** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S
7382
+ ** onto the end of the [sqlite3_str] object X. N must be non-negative.
7383
+ ** S must contain at least N non-zero bytes of content. To append a
7384
+ ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
7385
+ ** method instead.
7386
+ **
7387
+ ** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of
7388
+ ** zero-terminated string S onto the end of [sqlite3_str] object X.
7389
+ **
7390
+ ** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the
7391
+ ** single-byte character C onto the end of [sqlite3_str] object X.
7392
+ ** ^This method can be used, for example, to add whitespace indentation.
7393
+ **
7394
+ ** ^The [sqlite3_str_reset(X)] method resets the string under construction
7395
+ ** inside [sqlite3_str] object X back to zero bytes in length.
7396
+ **
7397
+ ** These methods do not return a result code. ^If an error occurs, that fact
7398
+ ** is recorded in the [sqlite3_str] object and can be recovered by a
7399
+ ** subsequent call to [sqlite3_str_errcode(X)].
7400
+ */
7401
+ SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
7402
+ SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
7403
+ SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
7404
+ SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
7405
+ SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
7406
+ SQLITE_API void sqlite3_str_reset(sqlite3_str*);
7407
+
7408
+ /*
7409
+ ** CAPI3REF: Status Of A Dynamic String
7410
+ ** METHOD: sqlite3_str
7411
+ **
7412
+ ** These interfaces return the current status of an [sqlite3_str] object.
7413
+ **
7414
+ ** ^If any prior errors have occurred while constructing the dynamic string
7415
+ ** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return
7416
+ ** an appropriate error code. ^The [sqlite3_str_errcode(X)] method returns
7417
+ ** [SQLITE_NOMEM] following any out-of-memory error, or
7418
+ ** [SQLITE_TOOBIG] if the size of the dynamic string exceeds
7419
+ ** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors.
7420
+ **
7421
+ ** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,
7422
+ ** of the dynamic string under construction in [sqlite3_str] object X.
7423
+ ** ^The length returned by [sqlite3_str_length(X)] does not include the
7424
+ ** zero-termination byte.
7425
+ **
7426
+ ** ^The [sqlite3_str_value(X)] method returns a pointer to the current
7427
+ ** content of the dynamic string under construction in X. The value
7428
+ ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
7429
+ ** and might be freed or altered by any subsequent method on the same
7430
+ ** [sqlite3_str] object. Applications must not used the pointer returned
7431
+ ** [sqlite3_str_value(X)] after any subsequent method call on the same
7432
+ ** object. ^Applications may change the content of the string returned
7433
+ ** by [sqlite3_str_value(X)] as long as they do not write into any bytes
7434
+ ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
7435
+ ** write any byte after any subsequent sqlite3_str method call.
7436
+ */
7437
+ SQLITE_API int sqlite3_str_errcode(sqlite3_str*);
7438
+ SQLITE_API int sqlite3_str_length(sqlite3_str*);
7439
+ SQLITE_API char *sqlite3_str_value(sqlite3_str*);
7026
7440
 
7027
7441
  /*
7028
7442
  ** CAPI3REF: SQLite Runtime Status
@@ -7106,7 +7520,7 @@ SQLITE_API int sqlite3_status64(
7106
7520
  ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
7107
7521
  ** <dd>This parameter records the largest memory allocation request
7108
7522
  ** handed to [pagecache memory allocator]. Only the value returned in the
7109
- ** *pHighwater parameter to [sqlite3_status()] is of interest.
7523
+ ** *pHighwater parameter to [sqlite3_status()] is of interest.
7110
7524
  ** The value written into the *pCurrent parameter is undefined.</dd>)^
7111
7525
  **
7112
7526
  ** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
@@ -7119,7 +7533,7 @@ SQLITE_API int sqlite3_status64(
7119
7533
  ** <dd>No longer used.</dd>
7120
7534
  **
7121
7535
  ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
7122
- ** <dd>The *pHighwater parameter records the deepest parser stack.
7536
+ ** <dd>The *pHighwater parameter records the deepest parser stack.
7123
7537
  ** The *pCurrent value is undefined. The *pHighwater value is only
7124
7538
  ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
7125
7539
  ** </dl>
@@ -7206,7 +7620,7 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
7206
7620
  ** memory used by all pager caches associated with the database connection.)^
7207
7621
  ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
7208
7622
  **
7209
- ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
7623
+ ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
7210
7624
  ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
7211
7625
  ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
7212
7626
  ** pager cache is shared between two or more connections the bytes of heap
@@ -7257,6 +7671,15 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
7257
7671
  ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
7258
7672
  ** </dd>
7259
7673
  **
7674
+ ** [[SQLITE_DBSTATUS_CACHE_SPILL]] ^(<dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>
7675
+ ** <dd>This parameter returns the number of dirty cache entries that have
7676
+ ** been written to disk in the middle of a transaction due to the page
7677
+ ** cache overflowing. Transactions are more efficient if they are written
7678
+ ** to disk all at once. When pages spill mid-transaction, that introduces
7679
+ ** additional overhead. This parameter can be used help identify
7680
+ ** inefficiencies that can be resolve by increasing the cache size.
7681
+ ** </dd>
7682
+ **
7260
7683
  ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
7261
7684
  ** <dd>This parameter returns zero for the current value if and only if
7262
7685
  ** all foreign key constraints (deferred or immediate) have been
@@ -7276,7 +7699,8 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
7276
7699
  #define SQLITE_DBSTATUS_CACHE_WRITE 9
7277
7700
  #define SQLITE_DBSTATUS_DEFERRED_FKS 10
7278
7701
  #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
7279
- #define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */
7702
+ #define SQLITE_DBSTATUS_CACHE_SPILL 12
7703
+ #define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */
7280
7704
 
7281
7705
 
7282
7706
  /*
@@ -7342,7 +7766,7 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
7342
7766
  **
7343
7767
  ** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
7344
7768
  ** <dd>^This is the number of times that the prepare statement has been
7345
- ** automatically regenerated due to schema changes or change to
7769
+ ** automatically regenerated due to schema changes or change to
7346
7770
  ** [bound parameters] that might affect the query plan.
7347
7771
  **
7348
7772
  ** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
@@ -7651,7 +8075,7 @@ typedef struct sqlite3_backup sqlite3_backup;
7651
8075
  ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
7652
8076
  ** an error.
7653
8077
  **
7654
- ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
8078
+ ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
7655
8079
  ** there is already a read or read-write transaction open on the
7656
8080
  ** destination database.
7657
8081
  **
@@ -8231,6 +8655,7 @@ SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
8231
8655
  ** can use to customize and optimize their behavior.
8232
8656
  **
8233
8657
  ** <dl>
8658
+ ** [[SQLITE_VTAB_CONSTRAINT_SUPPORT]]
8234
8659
  ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
8235
8660
  ** <dd>Calls of the form
8236
8661
  ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
@@ -8276,6 +8701,40 @@ SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
8276
8701
  */
8277
8702
  SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
8278
8703
 
8704
+ /*
8705
+ ** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE
8706
+ **
8707
+ ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
8708
+ ** method of a [virtual table], then it returns true if and only if the
8709
+ ** column is being fetched as part of an UPDATE operation during which the
8710
+ ** column value will not change. Applications might use this to substitute
8711
+ ** a return value that is less expensive to compute and that the corresponding
8712
+ ** [xUpdate] method understands as a "no-change" value.
8713
+ **
8714
+ ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that
8715
+ ** the column is not changed by the UPDATE statement, then the xColumn
8716
+ ** method can optionally return without setting a result, without calling
8717
+ ** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].
8718
+ ** In that case, [sqlite3_value_nochange(X)] will return true for the
8719
+ ** same column in the [xUpdate] method.
8720
+ */
8721
+ SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
8722
+
8723
+ /*
8724
+ ** CAPI3REF: Determine The Collation For a Virtual Table Constraint
8725
+ **
8726
+ ** This function may only be called from within a call to the [xBestIndex]
8727
+ ** method of a [virtual table].
8728
+ **
8729
+ ** The first argument must be the sqlite3_index_info object that is the
8730
+ ** first parameter to the xBestIndex() method. The second argument must be
8731
+ ** an index into the aConstraint[] array belonging to the sqlite3_index_info
8732
+ ** structure passed to xBestIndex. This function returns a pointer to a buffer
8733
+ ** containing the name of the collation sequence for the corresponding
8734
+ ** constraint.
8735
+ */
8736
+ SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
8737
+
8279
8738
  /*
8280
8739
  ** CAPI3REF: Conflict resolution modes
8281
8740
  ** KEYWORDS: {conflict resolution mode}
@@ -8402,15 +8861,15 @@ SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
8402
8861
  **
8403
8862
  ** ^If a write-transaction is open on [database connection] D when the
8404
8863
  ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
8405
- ** pages in the pager-cache that are not currently in use are written out
8864
+ ** pages in the pager-cache that are not currently in use are written out
8406
8865
  ** to disk. A dirty page may be in use if a database cursor created by an
8407
8866
  ** active SQL statement is reading from it, or if it is page 1 of a database
8408
8867
  ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
8409
8868
  ** interface flushes caches for all schemas - "main", "temp", and
8410
8869
  ** any [attached] databases.
8411
8870
  **
8412
- ** ^If this function needs to obtain extra database locks before dirty pages
8413
- ** can be flushed to disk, it does so. ^If those locks cannot be obtained
8871
+ ** ^If this function needs to obtain extra database locks before dirty pages
8872
+ ** can be flushed to disk, it does so. ^If those locks cannot be obtained
8414
8873
  ** immediately and there is a busy-handler callback configured, it is invoked
8415
8874
  ** in the usual manner. ^If the required lock still cannot be obtained, then
8416
8875
  ** the database is skipped and an attempt made to flush any dirty pages
@@ -8457,16 +8916,16 @@ SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
8457
8916
  ** kind of update operation that is about to occur.
8458
8917
  ** ^(The fourth parameter to the preupdate callback is the name of the
8459
8918
  ** database within the database connection that is being modified. This
8460
- ** will be "main" for the main database or "temp" for TEMP tables or
8919
+ ** will be "main" for the main database or "temp" for TEMP tables or
8461
8920
  ** the name given after the AS keyword in the [ATTACH] statement for attached
8462
8921
  ** databases.)^
8463
8922
  ** ^The fifth parameter to the preupdate callback is the name of the
8464
8923
  ** table that is being modified.
8465
8924
  **
8466
8925
  ** For an UPDATE or DELETE operation on a [rowid table], the sixth
8467
- ** parameter passed to the preupdate callback is the initial [rowid] of the
8926
+ ** parameter passed to the preupdate callback is the initial [rowid] of the
8468
8927
  ** row being modified or deleted. For an INSERT operation on a rowid table,
8469
- ** or any operation on a WITHOUT ROWID table, the value of the sixth
8928
+ ** or any operation on a WITHOUT ROWID table, the value of the sixth
8470
8929
  ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
8471
8930
  ** seventh parameter is the final rowid value of the row being inserted
8472
8931
  ** or updated. The value of the seventh parameter passed to the callback
@@ -8505,7 +8964,7 @@ SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
8505
8964
  **
8506
8965
  ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
8507
8966
  ** callback was invoked as a result of a direct insert, update, or delete
8508
- ** operation; or 1 for inserts, updates, or deletes invoked by top-level
8967
+ ** operation; or 1 for inserts, updates, or deletes invoked by top-level
8509
8968
  ** triggers; or 2 for changes resulting from triggers called by top-level
8510
8969
  ** triggers; and so forth.
8511
8970
  **
@@ -8539,14 +8998,13 @@ SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
8539
8998
  ** The return value is OS-dependent. For example, on unix systems, after
8540
8999
  ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
8541
9000
  ** called to get back the underlying "errno" that caused the problem, such
8542
- ** as ENOSPC, EAUTH, EISDIR, and so forth.
9001
+ ** as ENOSPC, EAUTH, EISDIR, and so forth.
8543
9002
  */
8544
9003
  SQLITE_API int sqlite3_system_errno(sqlite3*);
8545
9004
 
8546
9005
  /*
8547
9006
  ** CAPI3REF: Database Snapshot
8548
9007
  ** KEYWORDS: {snapshot} {sqlite3_snapshot}
8549
- ** EXPERIMENTAL
8550
9008
  **
8551
9009
  ** An instance of the snapshot object records the state of a [WAL mode]
8552
9010
  ** database for some specific point in history.
@@ -8563,11 +9021,6 @@ SQLITE_API int sqlite3_system_errno(sqlite3*);
8563
9021
  ** version of the database file so that it is possible to later open a new read
8564
9022
  ** transaction that sees that historical version of the database rather than
8565
9023
  ** the most recent version.
8566
- **
8567
- ** The constructor for this object is [sqlite3_snapshot_get()]. The
8568
- ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
8569
- ** to an historical snapshot (if possible). The destructor for
8570
- ** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
8571
9024
  */
8572
9025
  typedef struct sqlite3_snapshot {
8573
9026
  unsigned char hidden[48];
@@ -8575,7 +9028,7 @@ typedef struct sqlite3_snapshot {
8575
9028
 
8576
9029
  /*
8577
9030
  ** CAPI3REF: Record A Database Snapshot
8578
- ** EXPERIMENTAL
9031
+ ** CONSTRUCTOR: sqlite3_snapshot
8579
9032
  **
8580
9033
  ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
8581
9034
  ** new [sqlite3_snapshot] object that records the current state of
@@ -8583,15 +9036,15 @@ typedef struct sqlite3_snapshot {
8583
9036
  ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
8584
9037
  ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
8585
9038
  ** If there is not already a read-transaction open on schema S when
8586
- ** this function is called, one is opened automatically.
9039
+ ** this function is called, one is opened automatically.
8587
9040
  **
8588
9041
  ** The following must be true for this function to succeed. If any of
8589
9042
  ** the following statements are false when sqlite3_snapshot_get() is
8590
9043
  ** called, SQLITE_ERROR is returned. The final value of *P is undefined
8591
- ** in this case.
9044
+ ** in this case.
8592
9045
  **
8593
9046
  ** <ul>
8594
- ** <li> The database handle must be in [autocommit mode].
9047
+ ** <li> The database handle must not be in [autocommit mode].
8595
9048
  **
8596
9049
  ** <li> Schema S of [database connection] D must be a [WAL mode] database.
8597
9050
  **
@@ -8600,13 +9053,13 @@ typedef struct sqlite3_snapshot {
8600
9053
  **
8601
9054
  ** <li> One or more transactions must have been written to the current wal
8602
9055
  ** file since it was created on disk (by any connection). This means
8603
- ** that a snapshot cannot be taken on a wal mode database with no wal
9056
+ ** that a snapshot cannot be taken on a wal mode database with no wal
8604
9057
  ** file immediately after it is first opened. At least one transaction
8605
9058
  ** must be written to it first.
8606
9059
  ** </ul>
8607
9060
  **
8608
9061
  ** This function may also return SQLITE_NOMEM. If it is called with the
8609
- ** database handle in autocommit mode but fails for some other reason,
9062
+ ** database handle in autocommit mode but fails for some other reason,
8610
9063
  ** whether or not a read transaction is opened on schema S is undefined.
8611
9064
  **
8612
9065
  ** The [sqlite3_snapshot] object returned from a successful call to
@@ -8614,7 +9067,7 @@ typedef struct sqlite3_snapshot {
8614
9067
  ** to avoid a memory leak.
8615
9068
  **
8616
9069
  ** The [sqlite3_snapshot_get()] interface is only available when the
8617
- ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
9070
+ ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
8618
9071
  */
8619
9072
  SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
8620
9073
  sqlite3 *db,
@@ -8624,35 +9077,46 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
8624
9077
 
8625
9078
  /*
8626
9079
  ** CAPI3REF: Start a read transaction on an historical snapshot
8627
- ** EXPERIMENTAL
9080
+ ** METHOD: sqlite3_snapshot
9081
+ **
9082
+ ** ^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read
9083
+ ** transaction or upgrades an existing one for schema S of
9084
+ ** [database connection] D such that the read transaction refers to
9085
+ ** historical [snapshot] P, rather than the most recent change to the
9086
+ ** database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK
9087
+ ** on success or an appropriate [error code] if it fails.
9088
+ **
9089
+ ** ^In order to succeed, the database connection must not be in
9090
+ ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there
9091
+ ** is already a read transaction open on schema S, then the database handle
9092
+ ** must have no active statements (SELECT statements that have been passed
9093
+ ** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
9094
+ ** SQLITE_ERROR is returned if either of these conditions is violated, or
9095
+ ** if schema S does not exist, or if the snapshot object is invalid.
9096
+ **
9097
+ ** ^A call to sqlite3_snapshot_open() will fail to open if the specified
9098
+ ** snapshot has been overwritten by a [checkpoint]. In this case
9099
+ ** SQLITE_ERROR_SNAPSHOT is returned.
9100
+ **
9101
+ ** If there is already a read transaction open when this function is
9102
+ ** invoked, then the same read transaction remains open (on the same
9103
+ ** database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT
9104
+ ** is returned. If another error code - for example SQLITE_PROTOCOL or an
9105
+ ** SQLITE_IOERR error code - is returned, then the final state of the
9106
+ ** read transaction is undefined. If SQLITE_OK is returned, then the
9107
+ ** read transaction is now open on database snapshot P.
8628
9108
  **
8629
- ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
8630
- ** read transaction for schema S of
8631
- ** [database connection] D such that the read transaction
8632
- ** refers to historical [snapshot] P, rather than the most
8633
- ** recent change to the database.
8634
- ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
8635
- ** or an appropriate [error code] if it fails.
8636
- **
8637
- ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
8638
- ** the first operation following the [BEGIN] that takes the schema S
8639
- ** out of [autocommit mode].
8640
- ** ^In other words, schema S must not currently be in
8641
- ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the
8642
- ** database connection D must be out of [autocommit mode].
8643
- ** ^A [snapshot] will fail to open if it has been overwritten by a
8644
- ** [checkpoint].
8645
9109
  ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
8646
9110
  ** database connection D does not know that the database file for
8647
9111
  ** schema S is in [WAL mode]. A database connection might not know
8648
9112
  ** that the database file is in [WAL mode] if there has been no prior
8649
- ** I/O on that database connection, or if the database entered [WAL mode]
9113
+ ** I/O on that database connection, or if the database entered [WAL mode]
8650
9114
  ** after the most recent I/O on the database connection.)^
8651
9115
  ** (Hint: Run "[PRAGMA application_id]" against a newly opened
8652
9116
  ** database connection in order to make it ready to use snapshots.)
8653
9117
  **
8654
9118
  ** The [sqlite3_snapshot_open()] interface is only available when the
8655
- ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
9119
+ ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
8656
9120
  */
8657
9121
  SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
8658
9122
  sqlite3 *db,
@@ -8662,38 +9126,41 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
8662
9126
 
8663
9127
  /*
8664
9128
  ** CAPI3REF: Destroy a snapshot
8665
- ** EXPERIMENTAL
9129
+ ** DESTRUCTOR: sqlite3_snapshot
8666
9130
  **
8667
9131
  ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
8668
9132
  ** The application must eventually free every [sqlite3_snapshot] object
8669
9133
  ** using this routine to avoid a memory leak.
8670
9134
  **
8671
9135
  ** The [sqlite3_snapshot_free()] interface is only available when the
8672
- ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
9136
+ ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
8673
9137
  */
8674
9138
  SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
8675
9139
 
8676
9140
  /*
8677
9141
  ** CAPI3REF: Compare the ages of two snapshot handles.
8678
- ** EXPERIMENTAL
9142
+ ** METHOD: sqlite3_snapshot
8679
9143
  **
8680
9144
  ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
8681
- ** of two valid snapshot handles.
9145
+ ** of two valid snapshot handles.
8682
9146
  **
8683
- ** If the two snapshot handles are not associated with the same database
8684
- ** file, the result of the comparison is undefined.
9147
+ ** If the two snapshot handles are not associated with the same database
9148
+ ** file, the result of the comparison is undefined.
8685
9149
  **
8686
9150
  ** Additionally, the result of the comparison is only valid if both of the
8687
9151
  ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
8688
9152
  ** last time the wal file was deleted. The wal file is deleted when the
8689
9153
  ** database is changed back to rollback mode or when the number of database
8690
- ** clients drops to zero. If either snapshot handle was obtained before the
8691
- ** wal file was last deleted, the value returned by this function
9154
+ ** clients drops to zero. If either snapshot handle was obtained before the
9155
+ ** wal file was last deleted, the value returned by this function
8692
9156
  ** is undefined.
8693
9157
  **
8694
9158
  ** Otherwise, this API returns a negative value if P1 refers to an older
8695
9159
  ** snapshot than P2, zero if the two handles refer to the same database
8696
9160
  ** snapshot, and a positive value if P1 is a newer snapshot than P2.
9161
+ **
9162
+ ** This interface is only available if SQLite is compiled with the
9163
+ ** [SQLITE_ENABLE_SNAPSHOT] option.
8697
9164
  */
8698
9165
  SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
8699
9166
  sqlite3_snapshot *p1,
@@ -8702,26 +9169,151 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
8702
9169
 
8703
9170
  /*
8704
9171
  ** CAPI3REF: Recover snapshots from a wal file
8705
- ** EXPERIMENTAL
9172
+ ** METHOD: sqlite3_snapshot
8706
9173
  **
8707
- ** If all connections disconnect from a database file but do not perform
8708
- ** a checkpoint, the existing wal file is opened along with the database
8709
- ** file the next time the database is opened. At this point it is only
8710
- ** possible to successfully call sqlite3_snapshot_open() to open the most
8711
- ** recent snapshot of the database (the one at the head of the wal file),
8712
- ** even though the wal file may contain other valid snapshots for which
8713
- ** clients have sqlite3_snapshot handles.
9174
+ ** If a [WAL file] remains on disk after all database connections close
9175
+ ** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control]
9176
+ ** or because the last process to have the database opened exited without
9177
+ ** calling [sqlite3_close()]) and a new connection is subsequently opened
9178
+ ** on that database and [WAL file], the [sqlite3_snapshot_open()] interface
9179
+ ** will only be able to open the last transaction added to the WAL file
9180
+ ** even though the WAL file contains other valid transactions.
8714
9181
  **
8715
- ** This function attempts to scan the wal file associated with database zDb
9182
+ ** This function attempts to scan the WAL file associated with database zDb
8716
9183
  ** of database handle db and make all valid snapshots available to
8717
9184
  ** sqlite3_snapshot_open(). It is an error if there is already a read
8718
- ** transaction open on the database, or if the database is not a wal mode
9185
+ ** transaction open on the database, or if the database is not a WAL mode
8719
9186
  ** database.
8720
9187
  **
8721
9188
  ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
9189
+ **
9190
+ ** This interface is only available if SQLite is compiled with the
9191
+ ** [SQLITE_ENABLE_SNAPSHOT] option.
8722
9192
  */
8723
9193
  SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
8724
9194
 
9195
+ /*
9196
+ ** CAPI3REF: Serialize a database
9197
+ **
9198
+ ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
9199
+ ** that is a serialization of the S database on [database connection] D.
9200
+ ** If P is not a NULL pointer, then the size of the database in bytes
9201
+ ** is written into *P.
9202
+ **
9203
+ ** For an ordinary on-disk database file, the serialization is just a
9204
+ ** copy of the disk file. For an in-memory database or a "TEMP" database,
9205
+ ** the serialization is the same sequence of bytes which would be written
9206
+ ** to disk if that database where backed up to disk.
9207
+ **
9208
+ ** The usual case is that sqlite3_serialize() copies the serialization of
9209
+ ** the database into memory obtained from [sqlite3_malloc64()] and returns
9210
+ ** a pointer to that memory. The caller is responsible for freeing the
9211
+ ** returned value to avoid a memory leak. However, if the F argument
9212
+ ** contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
9213
+ ** are made, and the sqlite3_serialize() function will return a pointer
9214
+ ** to the contiguous memory representation of the database that SQLite
9215
+ ** is currently using for that database, or NULL if the no such contiguous
9216
+ ** memory representation of the database exists. A contiguous memory
9217
+ ** representation of the database will usually only exist if there has
9218
+ ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same
9219
+ ** values of D and S.
9220
+ ** The size of the database is written into *P even if the
9221
+ ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
9222
+ ** of the database exists.
9223
+ **
9224
+ ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
9225
+ ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
9226
+ ** allocation error occurs.
9227
+ **
9228
+ ** This interface is only available if SQLite is compiled with the
9229
+ ** [SQLITE_ENABLE_DESERIALIZE] option.
9230
+ */
9231
+ SQLITE_API unsigned char *sqlite3_serialize(
9232
+ sqlite3 *db, /* The database connection */
9233
+ const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */
9234
+ sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
9235
+ unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */
9236
+ );
9237
+
9238
+ /*
9239
+ ** CAPI3REF: Flags for sqlite3_serialize
9240
+ **
9241
+ ** Zero or more of the following constants can be OR-ed together for
9242
+ ** the F argument to [sqlite3_serialize(D,S,P,F)].
9243
+ **
9244
+ ** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return
9245
+ ** a pointer to contiguous in-memory database that it is currently using,
9246
+ ** without making a copy of the database. If SQLite is not currently using
9247
+ ** a contiguous in-memory database, then this option causes
9248
+ ** [sqlite3_serialize()] to return a NULL pointer. SQLite will only be
9249
+ ** using a contiguous in-memory database if it has been initialized by a
9250
+ ** prior call to [sqlite3_deserialize()].
9251
+ */
9252
+ #define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */
9253
+
9254
+ /*
9255
+ ** CAPI3REF: Deserialize a database
9256
+ **
9257
+ ** The sqlite3_deserialize(D,S,P,N,M,F) interface causes the
9258
+ ** [database connection] D to disconnect from database S and then
9259
+ ** reopen S as an in-memory database based on the serialization contained
9260
+ ** in P. The serialized database P is N bytes in size. M is the size of
9261
+ ** the buffer P, which might be larger than N. If M is larger than N, and
9262
+ ** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
9263
+ ** permitted to add content to the in-memory database as long as the total
9264
+ ** size does not exceed M bytes.
9265
+ **
9266
+ ** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
9267
+ ** invoke sqlite3_free() on the serialization buffer when the database
9268
+ ** connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
9269
+ ** SQLite will try to increase the buffer size using sqlite3_realloc64()
9270
+ ** if writes on the database cause it to grow larger than M bytes.
9271
+ **
9272
+ ** The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
9273
+ ** database is currently in a read transaction or is involved in a backup
9274
+ ** operation.
9275
+ **
9276
+ ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
9277
+ ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
9278
+ ** [sqlite3_free()] is invoked on argument P prior to returning.
9279
+ **
9280
+ ** This interface is only available if SQLite is compiled with the
9281
+ ** [SQLITE_ENABLE_DESERIALIZE] option.
9282
+ */
9283
+ SQLITE_API int sqlite3_deserialize(
9284
+ sqlite3 *db, /* The database connection */
9285
+ const char *zSchema, /* Which DB to reopen with the deserialization */
9286
+ unsigned char *pData, /* The serialized database content */
9287
+ sqlite3_int64 szDb, /* Number bytes in the deserialization */
9288
+ sqlite3_int64 szBuf, /* Total size of buffer pData[] */
9289
+ unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */
9290
+ );
9291
+
9292
+ /*
9293
+ ** CAPI3REF: Flags for sqlite3_deserialize()
9294
+ **
9295
+ ** The following are allowed values for 6th argument (the F argument) to
9296
+ ** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.
9297
+ **
9298
+ ** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
9299
+ ** in the P argument is held in memory obtained from [sqlite3_malloc64()]
9300
+ ** and that SQLite should take ownership of this memory and automatically
9301
+ ** free it when it has finished using it. Without this flag, the caller
9302
+ ** is responsible for freeing any dynamically allocated memory.
9303
+ **
9304
+ ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
9305
+ ** grow the size of the database using calls to [sqlite3_realloc64()]. This
9306
+ ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
9307
+ ** Without this flag, the deserialized database cannot increase in size beyond
9308
+ ** the number of bytes specified by the M parameter.
9309
+ **
9310
+ ** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
9311
+ ** should be treated as read-only.
9312
+ */
9313
+ #define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
9314
+ #define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */
9315
+ #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
9316
+
8725
9317
  /*
8726
9318
  ** Undo the hack that converts floating point types to integer for
8727
9319
  ** builds on processors without floating point support.
@@ -8833,7 +9425,7 @@ struct sqlite3_rtree_query_info {
8833
9425
  sqlite3_int64 iRowid; /* Rowid for current entry */
8834
9426
  sqlite3_rtree_dbl rParentScore; /* Score of parent node */
8835
9427
  int eParentWithin; /* Visibility of parent node */
8836
- int eWithin; /* OUT: Visiblity */
9428
+ int eWithin; /* OUT: Visibility */
8837
9429
  sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
8838
9430
  /* The following fields are only available in 3.8.11 and later */
8839
9431
  sqlite3_value **apSqlParam; /* Original SQL values of parameters */
@@ -8869,16 +9461,23 @@ extern "C" {
8869
9461
 
8870
9462
  /*
8871
9463
  ** CAPI3REF: Session Object Handle
9464
+ **
9465
+ ** An instance of this object is a [session] that can be used to
9466
+ ** record changes to a database.
8872
9467
  */
8873
9468
  typedef struct sqlite3_session sqlite3_session;
8874
9469
 
8875
9470
  /*
8876
9471
  ** CAPI3REF: Changeset Iterator Handle
9472
+ **
9473
+ ** An instance of this object acts as a cursor for iterating
9474
+ ** over the elements of a [changeset] or [patchset].
8877
9475
  */
8878
9476
  typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
8879
9477
 
8880
9478
  /*
8881
9479
  ** CAPI3REF: Create A New Session Object
9480
+ ** CONSTRUCTOR: sqlite3_session
8882
9481
  **
8883
9482
  ** Create a new session object attached to database handle db. If successful,
8884
9483
  ** a pointer to the new object is written to *ppSession and SQLITE_OK is
@@ -8899,7 +9498,7 @@ typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
8899
9498
  ** is not possible for an application to register a pre-update hook on a
8900
9499
  ** database handle that has one or more session objects attached. Nor is
8901
9500
  ** it possible to create a session object attached to a database handle for
8902
- ** which a pre-update hook is already defined. The results of attempting
9501
+ ** which a pre-update hook is already defined. The results of attempting
8903
9502
  ** either of these things are undefined.
8904
9503
  **
8905
9504
  ** The session object will be used to create changesets for tables in
@@ -8915,14 +9514,15 @@ SQLITE_API int sqlite3session_create(
8915
9514
 
8916
9515
  /*
8917
9516
  ** CAPI3REF: Delete A Session Object
9517
+ ** DESTRUCTOR: sqlite3_session
8918
9518
  **
8919
- ** Delete a session object previously allocated using
9519
+ ** Delete a session object previously allocated using
8920
9520
  ** [sqlite3session_create()]. Once a session object has been deleted, the
8921
9521
  ** results of attempting to use pSession with any other session module
8922
9522
  ** function are undefined.
8923
9523
  **
8924
9524
  ** Session objects must be deleted before the database handle to which they
8925
- ** are attached is closed. Refer to the documentation for
9525
+ ** are attached is closed. Refer to the documentation for
8926
9526
  ** [sqlite3session_create()] for details.
8927
9527
  */
8928
9528
  SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
@@ -8930,6 +9530,7 @@ SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
8930
9530
 
8931
9531
  /*
8932
9532
  ** CAPI3REF: Enable Or Disable A Session Object
9533
+ ** METHOD: sqlite3_session
8933
9534
  **
8934
9535
  ** Enable or disable the recording of changes by a session object. When
8935
9536
  ** enabled, a session object records changes made to the database. When
@@ -8939,16 +9540,17 @@ SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
8939
9540
  ** the eventual changesets.
8940
9541
  **
8941
9542
  ** Passing zero to this function disables the session. Passing a value
8942
- ** greater than zero enables it. Passing a value less than zero is a
9543
+ ** greater than zero enables it. Passing a value less than zero is a
8943
9544
  ** no-op, and may be used to query the current state of the session.
8944
9545
  **
8945
- ** The return value indicates the final state of the session object: 0 if
9546
+ ** The return value indicates the final state of the session object: 0 if
8946
9547
  ** the session is disabled, or 1 if it is enabled.
8947
9548
  */
8948
9549
  SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
8949
9550
 
8950
9551
  /*
8951
9552
  ** CAPI3REF: Set Or Clear the Indirect Change Flag
9553
+ ** METHOD: sqlite3_session
8952
9554
  **
8953
9555
  ** Each change recorded by a session object is marked as either direct or
8954
9556
  ** indirect. A change is marked as indirect if either:
@@ -8956,7 +9558,7 @@ SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
8956
9558
  ** <ul>
8957
9559
  ** <li> The session object "indirect" flag is set when the change is
8958
9560
  ** made, or
8959
- ** <li> The change is made by an SQL trigger or foreign key action
9561
+ ** <li> The change is made by an SQL trigger or foreign key action
8960
9562
  ** instead of directly as a result of a users SQL statement.
8961
9563
  ** </ul>
8962
9564
  **
@@ -8968,32 +9570,33 @@ SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
8968
9570
  ** flag. If the second argument passed to this function is zero, then the
8969
9571
  ** indirect flag is cleared. If it is greater than zero, the indirect flag
8970
9572
  ** is set. Passing a value less than zero does not modify the current value
8971
- ** of the indirect flag, and may be used to query the current state of the
9573
+ ** of the indirect flag, and may be used to query the current state of the
8972
9574
  ** indirect flag for the specified session object.
8973
9575
  **
8974
- ** The return value indicates the final state of the indirect flag: 0 if
9576
+ ** The return value indicates the final state of the indirect flag: 0 if
8975
9577
  ** it is clear, or 1 if it is set.
8976
9578
  */
8977
9579
  SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
8978
9580
 
8979
9581
  /*
8980
9582
  ** CAPI3REF: Attach A Table To A Session Object
9583
+ ** METHOD: sqlite3_session
8981
9584
  **
8982
9585
  ** If argument zTab is not NULL, then it is the name of a table to attach
8983
- ** to the session object passed as the first argument. All subsequent changes
8984
- ** made to the table while the session object is enabled will be recorded. See
9586
+ ** to the session object passed as the first argument. All subsequent changes
9587
+ ** made to the table while the session object is enabled will be recorded. See
8985
9588
  ** documentation for [sqlite3session_changeset()] for further details.
8986
9589
  **
8987
9590
  ** Or, if argument zTab is NULL, then changes are recorded for all tables
8988
- ** in the database. If additional tables are added to the database (by
8989
- ** executing "CREATE TABLE" statements) after this call is made, changes for
9591
+ ** in the database. If additional tables are added to the database (by
9592
+ ** executing "CREATE TABLE" statements) after this call is made, changes for
8990
9593
  ** the new tables are also recorded.
8991
9594
  **
8992
9595
  ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
8993
- ** defined as part of their CREATE TABLE statement. It does not matter if the
9596
+ ** defined as part of their CREATE TABLE statement. It does not matter if the
8994
9597
  ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
8995
9598
  ** KEY may consist of a single column, or may be a composite key.
8996
- **
9599
+ **
8997
9600
  ** It is not an error if the named table does not exist in the database. Nor
8998
9601
  ** is it an error if the named table does not have a PRIMARY KEY. However,
8999
9602
  ** no changes will be recorded in either of these scenarios.
@@ -9001,8 +9604,37 @@ SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect)
9001
9604
  ** Changes are not recorded for individual rows that have NULL values stored
9002
9605
  ** in one or more of their PRIMARY KEY columns.
9003
9606
  **
9004
- ** SQLITE_OK is returned if the call completes without error. Or, if an error
9607
+ ** SQLITE_OK is returned if the call completes without error. Or, if an error
9005
9608
  ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
9609
+ **
9610
+ ** <h3>Special sqlite_stat1 Handling</h3>
9611
+ **
9612
+ ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
9613
+ ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
9614
+ ** <pre>
9615
+ ** &nbsp; CREATE TABLE sqlite_stat1(tbl,idx,stat)
9616
+ ** </pre>
9617
+ **
9618
+ ** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
9619
+ ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
9620
+ ** are recorded for rows for which (idx IS NULL) is true. However, for such
9621
+ ** rows a zero-length blob (SQL value X'') is stored in the changeset or
9622
+ ** patchset instead of a NULL value. This allows such changesets to be
9623
+ ** manipulated by legacy implementations of sqlite3changeset_invert(),
9624
+ ** concat() and similar.
9625
+ **
9626
+ ** The sqlite3changeset_apply() function automatically converts the
9627
+ ** zero-length blob back to a NULL value when updating the sqlite_stat1
9628
+ ** table. However, if the application calls sqlite3changeset_new(),
9629
+ ** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
9630
+ ** iterator directly (including on a changeset iterator passed to a
9631
+ ** conflict-handler callback) then the X'' value is returned. The application
9632
+ ** must translate X'' to NULL itself if required.
9633
+ **
9634
+ ** Legacy (older than 3.22.0) versions of the sessions module cannot capture
9635
+ ** changes made to the sqlite_stat1 table. Legacy versions of the
9636
+ ** sqlite3changeset_apply() function silently ignore any modifications to the
9637
+ ** sqlite_stat1 table that are part of a changeset or patchset.
9006
9638
  */
9007
9639
  SQLITE_API int sqlite3session_attach(
9008
9640
  sqlite3_session *pSession, /* Session object */
@@ -9011,11 +9643,12 @@ SQLITE_API int sqlite3session_attach(
9011
9643
 
9012
9644
  /*
9013
9645
  ** CAPI3REF: Set a table filter on a Session Object.
9646
+ ** METHOD: sqlite3_session
9014
9647
  **
9015
- ** The second argument (xFilter) is the "filter callback". For changes to rows
9648
+ ** The second argument (xFilter) is the "filter callback". For changes to rows
9016
9649
  ** in tables that are not attached to the Session object, the filter is called
9017
- ** to determine whether changes to the table's rows should be tracked or not.
9018
- ** If xFilter returns 0, changes is not tracked. Note that once a table is
9650
+ ** to determine whether changes to the table's rows should be tracked or not.
9651
+ ** If xFilter returns 0, changes is not tracked. Note that once a table is
9019
9652
  ** attached, xFilter will not be called again.
9020
9653
  */
9021
9654
  SQLITE_API void sqlite3session_table_filter(
@@ -9029,10 +9662,11 @@ SQLITE_API void sqlite3session_table_filter(
9029
9662
 
9030
9663
  /*
9031
9664
  ** CAPI3REF: Generate A Changeset From A Session Object
9665
+ ** METHOD: sqlite3_session
9032
9666
  **
9033
- ** Obtain a changeset containing changes to the tables attached to the
9034
- ** session object passed as the first argument. If successful,
9035
- ** set *ppChangeset to point to a buffer containing the changeset
9667
+ ** Obtain a changeset containing changes to the tables attached to the
9668
+ ** session object passed as the first argument. If successful,
9669
+ ** set *ppChangeset to point to a buffer containing the changeset
9036
9670
  ** and *pnChangeset to the size of the changeset in bytes before returning
9037
9671
  ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
9038
9672
  ** zero and return an SQLite error code.
@@ -9047,7 +9681,7 @@ SQLITE_API void sqlite3session_table_filter(
9047
9681
  ** modifies the values of primary key columns. If such a change is made, it
9048
9682
  ** is represented in a changeset as a DELETE followed by an INSERT.
9049
9683
  **
9050
- ** Changes are not recorded for rows that have NULL values stored in one or
9684
+ ** Changes are not recorded for rows that have NULL values stored in one or
9051
9685
  ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
9052
9686
  ** no corresponding change is present in the changesets returned by this
9053
9687
  ** function. If an existing row with one or more NULL values stored in
@@ -9100,14 +9734,14 @@ SQLITE_API void sqlite3session_table_filter(
9100
9734
  ** <ul>
9101
9735
  ** <li> For each record generated by an insert, the database is queried
9102
9736
  ** for a row with a matching primary key. If one is found, an INSERT
9103
- ** change is added to the changeset. If no such row is found, no change
9737
+ ** change is added to the changeset. If no such row is found, no change
9104
9738
  ** is added to the changeset.
9105
9739
  **
9106
- ** <li> For each record generated by an update or delete, the database is
9740
+ ** <li> For each record generated by an update or delete, the database is
9107
9741
  ** queried for a row with a matching primary key. If such a row is
9108
9742
  ** found and one or more of the non-primary key fields have been
9109
- ** modified from their original values, an UPDATE change is added to
9110
- ** the changeset. Or, if no such row is found in the table, a DELETE
9743
+ ** modified from their original values, an UPDATE change is added to
9744
+ ** the changeset. Or, if no such row is found in the table, a DELETE
9111
9745
  ** change is added to the changeset. If there is a row with a matching
9112
9746
  ** primary key in the database, but all fields contain their original
9113
9747
  ** values, no change is added to the changeset.
@@ -9115,7 +9749,7 @@ SQLITE_API void sqlite3session_table_filter(
9115
9749
  **
9116
9750
  ** This means, amongst other things, that if a row is inserted and then later
9117
9751
  ** deleted while a session object is active, neither the insert nor the delete
9118
- ** will be present in the changeset. Or if a row is deleted and then later a
9752
+ ** will be present in the changeset. Or if a row is deleted and then later a
9119
9753
  ** row with the same primary key values inserted while a session object is
9120
9754
  ** active, the resulting changeset will contain an UPDATE change instead of
9121
9755
  ** a DELETE and an INSERT.
@@ -9124,10 +9758,10 @@ SQLITE_API void sqlite3session_table_filter(
9124
9758
  ** it does not accumulate records when rows are inserted, updated or deleted.
9125
9759
  ** This may appear to have some counter-intuitive effects if a single row
9126
9760
  ** is written to more than once during a session. For example, if a row
9127
- ** is inserted while a session object is enabled, then later deleted while
9761
+ ** is inserted while a session object is enabled, then later deleted while
9128
9762
  ** the same session object is disabled, no INSERT record will appear in the
9129
9763
  ** changeset, even though the delete took place while the session was disabled.
9130
- ** Or, if one field of a row is updated while a session is disabled, and
9764
+ ** Or, if one field of a row is updated while a session is disabled, and
9131
9765
  ** another field of the same row is updated while the session is enabled, the
9132
9766
  ** resulting changeset will contain an UPDATE change that updates both fields.
9133
9767
  */
@@ -9139,6 +9773,7 @@ SQLITE_API int sqlite3session_changeset(
9139
9773
 
9140
9774
  /*
9141
9775
  ** CAPI3REF: Load The Difference Between Tables Into A Session
9776
+ ** METHOD: sqlite3_session
9142
9777
  **
9143
9778
  ** If it is not already attached to the session object passed as the first
9144
9779
  ** argument, this function attaches table zTbl in the same manner as the
@@ -9147,7 +9782,7 @@ SQLITE_API int sqlite3session_changeset(
9147
9782
  ** an error).
9148
9783
  **
9149
9784
  ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
9150
- ** attached to the same database handle as the session object that contains
9785
+ ** attached to the same database handle as the session object that contains
9151
9786
  ** a table compatible with the table attached to the session by this function.
9152
9787
  ** A table is considered compatible if it:
9153
9788
  **
@@ -9163,25 +9798,25 @@ SQLITE_API int sqlite3session_changeset(
9163
9798
  ** APIs, tables without PRIMARY KEYs are simply ignored.
9164
9799
  **
9165
9800
  ** This function adds a set of changes to the session object that could be
9166
- ** used to update the table in database zFrom (call this the "from-table")
9167
- ** so that its content is the same as the table attached to the session
9801
+ ** used to update the table in database zFrom (call this the "from-table")
9802
+ ** so that its content is the same as the table attached to the session
9168
9803
  ** object (call this the "to-table"). Specifically:
9169
9804
  **
9170
9805
  ** <ul>
9171
- ** <li> For each row (primary key) that exists in the to-table but not in
9806
+ ** <li> For each row (primary key) that exists in the to-table but not in
9172
9807
  ** the from-table, an INSERT record is added to the session object.
9173
9808
  **
9174
- ** <li> For each row (primary key) that exists in the to-table but not in
9809
+ ** <li> For each row (primary key) that exists in the to-table but not in
9175
9810
  ** the from-table, a DELETE record is added to the session object.
9176
9811
  **
9177
- ** <li> For each row (primary key) that exists in both tables, but features
9812
+ ** <li> For each row (primary key) that exists in both tables, but features
9178
9813
  ** different non-PK values in each, an UPDATE record is added to the
9179
- ** session.
9814
+ ** session.
9180
9815
  ** </ul>
9181
9816
  **
9182
9817
  ** To clarify, if this function is called and then a changeset constructed
9183
- ** using [sqlite3session_changeset()], then after applying that changeset to
9184
- ** database zFrom the contents of the two compatible tables would be
9818
+ ** using [sqlite3session_changeset()], then after applying that changeset to
9819
+ ** database zFrom the contents of the two compatible tables would be
9185
9820
  ** identical.
9186
9821
  **
9187
9822
  ** It an error if database zFrom does not exist or does not contain the
@@ -9189,7 +9824,7 @@ SQLITE_API int sqlite3session_changeset(
9189
9824
  **
9190
9825
  ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
9191
9826
  ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
9192
- ** may be set to point to a buffer containing an English language error
9827
+ ** may be set to point to a buffer containing an English language error
9193
9828
  ** message. It is the responsibility of the caller to free this buffer using
9194
9829
  ** sqlite3_free().
9195
9830
  */
@@ -9203,23 +9838,24 @@ SQLITE_API int sqlite3session_diff(
9203
9838
 
9204
9839
  /*
9205
9840
  ** CAPI3REF: Generate A Patchset From A Session Object
9841
+ ** METHOD: sqlite3_session
9206
9842
  **
9207
9843
  ** The differences between a patchset and a changeset are that:
9208
9844
  **
9209
9845
  ** <ul>
9210
- ** <li> DELETE records consist of the primary key fields only. The
9846
+ ** <li> DELETE records consist of the primary key fields only. The
9211
9847
  ** original values of other fields are omitted.
9212
- ** <li> The original values of any modified fields are omitted from
9848
+ ** <li> The original values of any modified fields are omitted from
9213
9849
  ** UPDATE records.
9214
9850
  ** </ul>
9215
9851
  **
9216
- ** A patchset blob may be used with up to date versions of all
9217
- ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
9852
+ ** A patchset blob may be used with up to date versions of all
9853
+ ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
9218
9854
  ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
9219
9855
  ** attempting to use a patchset blob with old versions of the
9220
- ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
9856
+ ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
9221
9857
  **
9222
- ** Because the non-primary key "old.*" fields are omitted, no
9858
+ ** Because the non-primary key "old.*" fields are omitted, no
9223
9859
  ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
9224
9860
  ** is passed to the sqlite3changeset_apply() API. Other conflict types work
9225
9861
  ** in the same way as for changesets.
@@ -9238,29 +9874,30 @@ SQLITE_API int sqlite3session_patchset(
9238
9874
  /*
9239
9875
  ** CAPI3REF: Test if a changeset has recorded any changes.
9240
9876
  **
9241
- ** Return non-zero if no changes to attached tables have been recorded by
9242
- ** the session object passed as the first argument. Otherwise, if one or
9877
+ ** Return non-zero if no changes to attached tables have been recorded by
9878
+ ** the session object passed as the first argument. Otherwise, if one or
9243
9879
  ** more changes have been recorded, return zero.
9244
9880
  **
9245
9881
  ** Even if this function returns zero, it is possible that calling
9246
9882
  ** [sqlite3session_changeset()] on the session handle may still return a
9247
- ** changeset that contains no changes. This can happen when a row in
9248
- ** an attached table is modified and then later on the original values
9883
+ ** changeset that contains no changes. This can happen when a row in
9884
+ ** an attached table is modified and then later on the original values
9249
9885
  ** are restored. However, if this function returns non-zero, then it is
9250
- ** guaranteed that a call to sqlite3session_changeset() will return a
9886
+ ** guaranteed that a call to sqlite3session_changeset() will return a
9251
9887
  ** changeset containing zero changes.
9252
9888
  */
9253
9889
  SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
9254
9890
 
9255
9891
  /*
9256
- ** CAPI3REF: Create An Iterator To Traverse A Changeset
9892
+ ** CAPI3REF: Create An Iterator To Traverse A Changeset
9893
+ ** CONSTRUCTOR: sqlite3_changeset_iter
9257
9894
  **
9258
9895
  ** Create an iterator used to iterate through the contents of a changeset.
9259
9896
  ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
9260
9897
  ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
9261
9898
  ** SQLite error code is returned.
9262
9899
  **
9263
- ** The following functions can be used to advance and query a changeset
9900
+ ** The following functions can be used to advance and query a changeset
9264
9901
  ** iterator created by this function:
9265
9902
  **
9266
9903
  ** <ul>
@@ -9277,23 +9914,50 @@ SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
9277
9914
  **
9278
9915
  ** Assuming the changeset blob was created by one of the
9279
9916
  ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
9280
- ** [sqlite3changeset_invert()] functions, all changes within the changeset
9281
- ** that apply to a single table are grouped together. This means that when
9282
- ** an application iterates through a changeset using an iterator created by
9283
- ** this function, all changes that relate to a single table are visited
9284
- ** consecutively. There is no chance that the iterator will visit a change
9285
- ** the applies to table X, then one for table Y, and then later on visit
9917
+ ** [sqlite3changeset_invert()] functions, all changes within the changeset
9918
+ ** that apply to a single table are grouped together. This means that when
9919
+ ** an application iterates through a changeset using an iterator created by
9920
+ ** this function, all changes that relate to a single table are visited
9921
+ ** consecutively. There is no chance that the iterator will visit a change
9922
+ ** the applies to table X, then one for table Y, and then later on visit
9286
9923
  ** another change for table X.
9924
+ **
9925
+ ** The behavior of sqlite3changeset_start_v2() and its streaming equivalent
9926
+ ** may be modified by passing a combination of
9927
+ ** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter.
9928
+ **
9929
+ ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
9930
+ ** and therefore subject to change.
9287
9931
  */
9288
9932
  SQLITE_API int sqlite3changeset_start(
9289
9933
  sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
9290
9934
  int nChangeset, /* Size of changeset blob in bytes */
9291
9935
  void *pChangeset /* Pointer to blob containing changeset */
9292
9936
  );
9937
+ SQLITE_API int sqlite3changeset_start_v2(
9938
+ sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
9939
+ int nChangeset, /* Size of changeset blob in bytes */
9940
+ void *pChangeset, /* Pointer to blob containing changeset */
9941
+ int flags /* SESSION_CHANGESETSTART_* flags */
9942
+ );
9943
+
9944
+ /*
9945
+ ** CAPI3REF: Flags for sqlite3changeset_start_v2
9946
+ **
9947
+ ** The following flags may passed via the 4th parameter to
9948
+ ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:
9949
+ **
9950
+ ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
9951
+ ** Invert the changeset while iterating through it. This is equivalent to
9952
+ ** inverting a changeset using sqlite3changeset_invert() before applying it.
9953
+ ** It is an error to specify this flag with a patchset.
9954
+ */
9955
+ #define SQLITE_CHANGESETSTART_INVERT 0x0002
9293
9956
 
9294
9957
 
9295
9958
  /*
9296
9959
  ** CAPI3REF: Advance A Changeset Iterator
9960
+ ** METHOD: sqlite3_changeset_iter
9297
9961
  **
9298
9962
  ** This function may only be used with iterators created by function
9299
9963
  ** [sqlite3changeset_start()]. If it is called on an iterator passed to
@@ -9306,18 +9970,19 @@ SQLITE_API int sqlite3changeset_start(
9306
9970
  ** point to the first change in the changeset. Each subsequent call advances
9307
9971
  ** the iterator to point to the next change in the changeset (if any). If
9308
9972
  ** no error occurs and the iterator points to a valid change after a call
9309
- ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
9973
+ ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
9310
9974
  ** Otherwise, if all changes in the changeset have already been visited,
9311
9975
  ** SQLITE_DONE is returned.
9312
9976
  **
9313
- ** If an error occurs, an SQLite error code is returned. Possible error
9314
- ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
9977
+ ** If an error occurs, an SQLite error code is returned. Possible error
9978
+ ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
9315
9979
  ** SQLITE_NOMEM.
9316
9980
  */
9317
9981
  SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
9318
9982
 
9319
9983
  /*
9320
9984
  ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
9985
+ ** METHOD: sqlite3_changeset_iter
9321
9986
  **
9322
9987
  ** The pIter argument passed to this function may either be an iterator
9323
9988
  ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
@@ -9328,14 +9993,14 @@ SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
9328
9993
  ** If argument pzTab is not NULL, then *pzTab is set to point to a
9329
9994
  ** nul-terminated utf-8 encoded string containing the name of the table
9330
9995
  ** affected by the current change. The buffer remains valid until either
9331
- ** sqlite3changeset_next() is called on the iterator or until the
9332
- ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
9996
+ ** sqlite3changeset_next() is called on the iterator or until the
9997
+ ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
9333
9998
  ** set to the number of columns in the table affected by the change. If
9334
9999
  ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
9335
10000
  ** is an indirect change, or false (0) otherwise. See the documentation for
9336
10001
  ** [sqlite3session_indirect()] for a description of direct and indirect
9337
- ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
9338
- ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
10002
+ ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
10003
+ ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
9339
10004
  ** type of change that the iterator currently points to.
9340
10005
  **
9341
10006
  ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
@@ -9352,6 +10017,7 @@ SQLITE_API int sqlite3changeset_op(
9352
10017
 
9353
10018
  /*
9354
10019
  ** CAPI3REF: Obtain The Primary Key Definition Of A Table
10020
+ ** METHOD: sqlite3_changeset_iter
9355
10021
  **
9356
10022
  ** For each modified table, a changeset includes the following:
9357
10023
  **
@@ -9383,11 +10049,12 @@ SQLITE_API int sqlite3changeset_pk(
9383
10049
 
9384
10050
  /*
9385
10051
  ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
10052
+ ** METHOD: sqlite3_changeset_iter
9386
10053
  **
9387
10054
  ** The pIter argument passed to this function may either be an iterator
9388
10055
  ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9389
10056
  ** created by [sqlite3changeset_start()]. In the latter case, the most recent
9390
- ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
10057
+ ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
9391
10058
  ** Furthermore, it may only be called if the type of change that the iterator
9392
10059
  ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
9393
10060
  ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
@@ -9397,9 +10064,9 @@ SQLITE_API int sqlite3changeset_pk(
9397
10064
  ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9398
10065
  **
9399
10066
  ** If successful, this function sets *ppValue to point to a protected
9400
- ** sqlite3_value object containing the iVal'th value from the vector of
10067
+ ** sqlite3_value object containing the iVal'th value from the vector of
9401
10068
  ** original row values stored as part of the UPDATE or DELETE change and
9402
- ** returns SQLITE_OK. The name of the function comes from the fact that this
10069
+ ** returns SQLITE_OK. The name of the function comes from the fact that this
9403
10070
  ** is similar to the "old.*" columns available to update or delete triggers.
9404
10071
  **
9405
10072
  ** If some other error occurs (e.g. an OOM condition), an SQLite error code
@@ -9413,11 +10080,12 @@ SQLITE_API int sqlite3changeset_old(
9413
10080
 
9414
10081
  /*
9415
10082
  ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
10083
+ ** METHOD: sqlite3_changeset_iter
9416
10084
  **
9417
10085
  ** The pIter argument passed to this function may either be an iterator
9418
10086
  ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9419
10087
  ** created by [sqlite3changeset_start()]. In the latter case, the most recent
9420
- ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
10088
+ ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
9421
10089
  ** Furthermore, it may only be called if the type of change that the iterator
9422
10090
  ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
9423
10091
  ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
@@ -9427,12 +10095,12 @@ SQLITE_API int sqlite3changeset_old(
9427
10095
  ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9428
10096
  **
9429
10097
  ** If successful, this function sets *ppValue to point to a protected
9430
- ** sqlite3_value object containing the iVal'th value from the vector of
10098
+ ** sqlite3_value object containing the iVal'th value from the vector of
9431
10099
  ** new row values stored as part of the UPDATE or INSERT change and
9432
10100
  ** returns SQLITE_OK. If the change is an UPDATE and does not include
9433
- ** a new value for the requested column, *ppValue is set to NULL and
9434
- ** SQLITE_OK returned. The name of the function comes from the fact that
9435
- ** this is similar to the "new.*" columns available to update or delete
10101
+ ** a new value for the requested column, *ppValue is set to NULL and
10102
+ ** SQLITE_OK returned. The name of the function comes from the fact that
10103
+ ** this is similar to the "new.*" columns available to update or delete
9436
10104
  ** triggers.
9437
10105
  **
9438
10106
  ** If some other error occurs (e.g. an OOM condition), an SQLite error code
@@ -9446,6 +10114,7 @@ SQLITE_API int sqlite3changeset_new(
9446
10114
 
9447
10115
  /*
9448
10116
  ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
10117
+ ** METHOD: sqlite3_changeset_iter
9449
10118
  **
9450
10119
  ** This function should only be used with iterator objects passed to a
9451
10120
  ** conflict-handler callback by [sqlite3changeset_apply()] with either
@@ -9458,7 +10127,7 @@ SQLITE_API int sqlite3changeset_new(
9458
10127
  ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9459
10128
  **
9460
10129
  ** If successful, this function sets *ppValue to point to a protected
9461
- ** sqlite3_value object containing the iVal'th value from the
10130
+ ** sqlite3_value object containing the iVal'th value from the
9462
10131
  ** "conflicting row" associated with the current conflict-handler callback
9463
10132
  ** and returns SQLITE_OK.
9464
10133
  **
@@ -9473,6 +10142,7 @@ SQLITE_API int sqlite3changeset_conflict(
9473
10142
 
9474
10143
  /*
9475
10144
  ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
10145
+ ** METHOD: sqlite3_changeset_iter
9476
10146
  **
9477
10147
  ** This function may only be called with an iterator passed to an
9478
10148
  ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
@@ -9489,6 +10159,7 @@ SQLITE_API int sqlite3changeset_fk_conflicts(
9489
10159
 
9490
10160
  /*
9491
10161
  ** CAPI3REF: Finalize A Changeset Iterator
10162
+ ** METHOD: sqlite3_changeset_iter
9492
10163
  **
9493
10164
  ** This function is used to finalize an iterator allocated with
9494
10165
  ** [sqlite3changeset_start()].
@@ -9500,19 +10171,21 @@ SQLITE_API int sqlite3changeset_fk_conflicts(
9500
10171
  ** call has no effect.
9501
10172
  **
9502
10173
  ** If an error was encountered within a call to an sqlite3changeset_xxx()
9503
- ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
10174
+ ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
9504
10175
  ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
9505
10176
  ** to that error is returned by this function. Otherwise, SQLITE_OK is
9506
10177
  ** returned. This is to allow the following pattern (pseudo-code):
9507
10178
  **
10179
+ ** <pre>
9508
10180
  ** sqlite3changeset_start();
9509
10181
  ** while( SQLITE_ROW==sqlite3changeset_next() ){
9510
10182
  ** // Do something with change.
9511
10183
  ** }
9512
10184
  ** rc = sqlite3changeset_finalize();
9513
10185
  ** if( rc!=SQLITE_OK ){
9514
- ** // An error has occurred
10186
+ ** // An error has occurred
9515
10187
  ** }
10188
+ ** </pre>
9516
10189
  */
9517
10190
  SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
9518
10191
 
@@ -9538,7 +10211,7 @@ SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
9538
10211
  ** zeroed and an SQLite error code returned.
9539
10212
  **
9540
10213
  ** It is the responsibility of the caller to eventually call sqlite3_free()
9541
- ** on the *ppOut pointer to free the buffer allocation following a successful
10214
+ ** on the *ppOut pointer to free the buffer allocation following a successful
9542
10215
  ** call to this function.
9543
10216
  **
9544
10217
  ** WARNING/TODO: This function currently assumes that the input is a valid
@@ -9552,14 +10225,15 @@ SQLITE_API int sqlite3changeset_invert(
9552
10225
  /*
9553
10226
  ** CAPI3REF: Concatenate Two Changeset Objects
9554
10227
  **
9555
- ** This function is used to concatenate two changesets, A and B, into a
10228
+ ** This function is used to concatenate two changesets, A and B, into a
9556
10229
  ** single changeset. The result is a changeset equivalent to applying
9557
- ** changeset A followed by changeset B.
10230
+ ** changeset A followed by changeset B.
9558
10231
  **
9559
- ** This function combines the two input changesets using an
10232
+ ** This function combines the two input changesets using an
9560
10233
  ** sqlite3_changegroup object. Calling it produces similar results as the
9561
10234
  ** following code fragment:
9562
10235
  **
10236
+ ** <pre>
9563
10237
  ** sqlite3_changegroup *pGrp;
9564
10238
  ** rc = sqlite3_changegroup_new(&pGrp);
9565
10239
  ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
@@ -9570,6 +10244,7 @@ SQLITE_API int sqlite3changeset_invert(
9570
10244
  ** *ppOut = 0;
9571
10245
  ** *pnOut = 0;
9572
10246
  ** }
10247
+ ** </pre>
9573
10248
  **
9574
10249
  ** Refer to the sqlite3_changegroup documentation below for details.
9575
10250
  */
@@ -9585,11 +10260,15 @@ SQLITE_API int sqlite3changeset_concat(
9585
10260
 
9586
10261
  /*
9587
10262
  ** CAPI3REF: Changegroup Handle
10263
+ **
10264
+ ** A changegroup is an object used to combine two or more
10265
+ ** [changesets] or [patchsets]
9588
10266
  */
9589
10267
  typedef struct sqlite3_changegroup sqlite3_changegroup;
9590
10268
 
9591
10269
  /*
9592
10270
  ** CAPI3REF: Create A New Changegroup Object
10271
+ ** CONSTRUCTOR: sqlite3_changegroup
9593
10272
  **
9594
10273
  ** An sqlite3_changegroup object is used to combine two or more changesets
9595
10274
  ** (or patchsets) into a single changeset (or patchset). A single changegroup
@@ -9598,7 +10277,7 @@ typedef struct sqlite3_changegroup sqlite3_changegroup;
9598
10277
  **
9599
10278
  ** If successful, this function returns SQLITE_OK and populates (*pp) with
9600
10279
  ** a pointer to a new sqlite3_changegroup object before returning. The caller
9601
- ** should eventually free the returned object using a call to
10280
+ ** should eventually free the returned object using a call to
9602
10281
  ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
9603
10282
  ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
9604
10283
  **
@@ -9610,7 +10289,7 @@ typedef struct sqlite3_changegroup sqlite3_changegroup;
9610
10289
  ** <li> Zero or more changesets (or patchsets) are added to the object
9611
10290
  ** by calling sqlite3changegroup_add().
9612
10291
  **
9613
- ** <li> The result of combining all input changesets together is obtained
10292
+ ** <li> The result of combining all input changesets together is obtained
9614
10293
  ** by the application via a call to sqlite3changegroup_output().
9615
10294
  **
9616
10295
  ** <li> The object is deleted using a call to sqlite3changegroup_delete().
@@ -9619,7 +10298,7 @@ typedef struct sqlite3_changegroup sqlite3_changegroup;
9619
10298
  ** Any number of calls to add() and output() may be made between the calls to
9620
10299
  ** new() and delete(), and in any order.
9621
10300
  **
9622
- ** As well as the regular sqlite3changegroup_add() and
10301
+ ** As well as the regular sqlite3changegroup_add() and
9623
10302
  ** sqlite3changegroup_output() functions, also available are the streaming
9624
10303
  ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
9625
10304
  */
@@ -9627,9 +10306,10 @@ SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
9627
10306
 
9628
10307
  /*
9629
10308
  ** CAPI3REF: Add A Changeset To A Changegroup
10309
+ ** METHOD: sqlite3_changegroup
9630
10310
  **
9631
10311
  ** Add all changes within the changeset (or patchset) in buffer pData (size
9632
- ** nData bytes) to the changegroup.
10312
+ ** nData bytes) to the changegroup.
9633
10313
  **
9634
10314
  ** If the buffer contains a patchset, then all prior calls to this function
9635
10315
  ** on the same changegroup object must also have specified patchsets. Or, if
@@ -9656,7 +10336,7 @@ SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
9656
10336
  ** changeset was recorded immediately after the changesets already
9657
10337
  ** added to the changegroup.
9658
10338
  ** <tr><td>INSERT <td>UPDATE <td>
9659
- ** The INSERT change remains in the changegroup. The values in the
10339
+ ** The INSERT change remains in the changegroup. The values in the
9660
10340
  ** INSERT change are modified as if the row was inserted by the
9661
10341
  ** existing change and then updated according to the new change.
9662
10342
  ** <tr><td>INSERT <td>DELETE <td>
@@ -9667,17 +10347,17 @@ SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
9667
10347
  ** changeset was recorded immediately after the changesets already
9668
10348
  ** added to the changegroup.
9669
10349
  ** <tr><td>UPDATE <td>UPDATE <td>
9670
- ** The existing UPDATE remains within the changegroup. It is amended
9671
- ** so that the accompanying values are as if the row was updated once
10350
+ ** The existing UPDATE remains within the changegroup. It is amended
10351
+ ** so that the accompanying values are as if the row was updated once
9672
10352
  ** by the existing change and then again by the new change.
9673
10353
  ** <tr><td>UPDATE <td>DELETE <td>
9674
10354
  ** The existing UPDATE is replaced by the new DELETE within the
9675
10355
  ** changegroup.
9676
10356
  ** <tr><td>DELETE <td>INSERT <td>
9677
10357
  ** If one or more of the column values in the row inserted by the
9678
- ** new change differ from those in the row deleted by the existing
10358
+ ** new change differ from those in the row deleted by the existing
9679
10359
  ** change, the existing DELETE is replaced by an UPDATE within the
9680
- ** changegroup. Otherwise, if the inserted row is exactly the same
10360
+ ** changegroup. Otherwise, if the inserted row is exactly the same
9681
10361
  ** as the deleted row, the existing DELETE is simply discarded.
9682
10362
  ** <tr><td>DELETE <td>UPDATE <td>
9683
10363
  ** The new change is ignored. This case does not occur if the new
@@ -9704,6 +10384,7 @@ SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pDa
9704
10384
 
9705
10385
  /*
9706
10386
  ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
10387
+ ** METHOD: sqlite3_changegroup
9707
10388
  **
9708
10389
  ** Obtain a buffer containing a changeset (or patchset) representing the
9709
10390
  ** current contents of the changegroup. If the inputs to the changegroup
@@ -9721,7 +10402,7 @@ SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pDa
9721
10402
  **
9722
10403
  ** If an error occurs, an SQLite error code is returned and the output
9723
10404
  ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
9724
- ** is returned and the output variables are set to the size of and a
10405
+ ** is returned and the output variables are set to the size of and a
9725
10406
  ** pointer to the output buffer, respectively. In this case it is the
9726
10407
  ** responsibility of the caller to eventually free the buffer using a
9727
10408
  ** call to sqlite3_free().
@@ -9734,36 +10415,36 @@ SQLITE_API int sqlite3changegroup_output(
9734
10415
 
9735
10416
  /*
9736
10417
  ** CAPI3REF: Delete A Changegroup Object
10418
+ ** DESTRUCTOR: sqlite3_changegroup
9737
10419
  */
9738
10420
  SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9739
10421
 
9740
10422
  /*
9741
10423
  ** CAPI3REF: Apply A Changeset To A Database
9742
10424
  **
9743
- ** Apply a changeset to a database. This function attempts to update the
9744
- ** "main" database attached to handle db with the changes found in the
9745
- ** changeset passed via the second and third arguments.
10425
+ ** Apply a changeset or patchset to a database. These functions attempt to
10426
+ ** update the "main" database attached to handle db with the changes found in
10427
+ ** the changeset passed via the second and third arguments.
9746
10428
  **
9747
- ** The fourth argument (xFilter) passed to this function is the "filter
10429
+ ** The fourth argument (xFilter) passed to these functions is the "filter
9748
10430
  ** callback". If it is not NULL, then for each table affected by at least one
9749
10431
  ** change in the changeset, the filter callback is invoked with
9750
10432
  ** the table name as the second argument, and a copy of the context pointer
9751
- ** passed as the sixth argument to this function as the first. If the "filter
9752
- ** callback" returns zero, then no attempt is made to apply any changes to
9753
- ** the table. Otherwise, if the return value is non-zero or the xFilter
9754
- ** argument to this function is NULL, all changes related to the table are
9755
- ** attempted.
9756
- **
9757
- ** For each table that is not excluded by the filter callback, this function
9758
- ** tests that the target database contains a compatible table. A table is
10433
+ ** passed as the sixth argument as the first. If the "filter callback"
10434
+ ** returns zero, then no attempt is made to apply any changes to the table.
10435
+ ** Otherwise, if the return value is non-zero or the xFilter argument to
10436
+ ** is NULL, all changes related to the table are attempted.
10437
+ **
10438
+ ** For each table that is not excluded by the filter callback, this function
10439
+ ** tests that the target database contains a compatible table. A table is
9759
10440
  ** considered compatible if all of the following are true:
9760
10441
  **
9761
10442
  ** <ul>
9762
- ** <li> The table has the same name as the name recorded in the
10443
+ ** <li> The table has the same name as the name recorded in the
9763
10444
  ** changeset, and
9764
- ** <li> The table has at least as many columns as recorded in the
10445
+ ** <li> The table has at least as many columns as recorded in the
9765
10446
  ** changeset, and
9766
- ** <li> The table has primary key columns in the same position as
10447
+ ** <li> The table has primary key columns in the same position as
9767
10448
  ** recorded in the changeset.
9768
10449
  ** </ul>
9769
10450
  **
@@ -9772,11 +10453,11 @@ SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9772
10453
  ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
9773
10454
  ** one such warning is issued for each table in the changeset.
9774
10455
  **
9775
- ** For each change for which there is a compatible table, an attempt is made
9776
- ** to modify the table contents according to the UPDATE, INSERT or DELETE
9777
- ** change. If a change cannot be applied cleanly, the conflict handler
9778
- ** function passed as the fifth argument to sqlite3changeset_apply() may be
9779
- ** invoked. A description of exactly when the conflict handler is invoked for
10456
+ ** For each change for which there is a compatible table, an attempt is made
10457
+ ** to modify the table contents according to the UPDATE, INSERT or DELETE
10458
+ ** change. If a change cannot be applied cleanly, the conflict handler
10459
+ ** function passed as the fifth argument to sqlite3changeset_apply() may be
10460
+ ** invoked. A description of exactly when the conflict handler is invoked for
9780
10461
  ** each type of change is below.
9781
10462
  **
9782
10463
  ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
@@ -9784,23 +10465,23 @@ SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9784
10465
  ** argument are undefined.
9785
10466
  **
9786
10467
  ** Each time the conflict handler function is invoked, it must return one
9787
- ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
10468
+ ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
9788
10469
  ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
9789
10470
  ** if the second argument passed to the conflict handler is either
9790
10471
  ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
9791
10472
  ** returns an illegal value, any changes already made are rolled back and
9792
- ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
10473
+ ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
9793
10474
  ** actions are taken by sqlite3changeset_apply() depending on the value
9794
10475
  ** returned by each invocation of the conflict-handler function. Refer to
9795
- ** the documentation for the three
10476
+ ** the documentation for the three
9796
10477
  ** [SQLITE_CHANGESET_OMIT|available return values] for details.
9797
10478
  **
9798
10479
  ** <dl>
9799
10480
  ** <dt>DELETE Changes<dd>
9800
- ** For each DELETE change, this function checks if the target database
9801
- ** contains a row with the same primary key value (or values) as the
9802
- ** original row values stored in the changeset. If it does, and the values
9803
- ** stored in all non-primary key columns also match the values stored in
10481
+ ** For each DELETE change, the function checks if the target database
10482
+ ** contains a row with the same primary key value (or values) as the
10483
+ ** original row values stored in the changeset. If it does, and the values
10484
+ ** stored in all non-primary key columns also match the values stored in
9804
10485
  ** the changeset the row is deleted from the target database.
9805
10486
  **
9806
10487
  ** If a row with matching primary key values is found, but one or more of
@@ -9829,22 +10510,22 @@ SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9829
10510
  ** database table, the trailing fields are populated with their default
9830
10511
  ** values.
9831
10512
  **
9832
- ** If the attempt to insert the row fails because the database already
10513
+ ** If the attempt to insert the row fails because the database already
9833
10514
  ** contains a row with the same primary key values, the conflict handler
9834
- ** function is invoked with the second argument set to
10515
+ ** function is invoked with the second argument set to
9835
10516
  ** [SQLITE_CHANGESET_CONFLICT].
9836
10517
  **
9837
10518
  ** If the attempt to insert the row fails because of some other constraint
9838
- ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
10519
+ ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
9839
10520
  ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
9840
- ** This includes the case where the INSERT operation is re-attempted because
9841
- ** an earlier call to the conflict handler function returned
10521
+ ** This includes the case where the INSERT operation is re-attempted because
10522
+ ** an earlier call to the conflict handler function returned
9842
10523
  ** [SQLITE_CHANGESET_REPLACE].
9843
10524
  **
9844
10525
  ** <dt>UPDATE Changes<dd>
9845
- ** For each UPDATE change, this function checks if the target database
9846
- ** contains a row with the same primary key value (or values) as the
9847
- ** original row values stored in the changeset. If it does, and the values
10526
+ ** For each UPDATE change, the function checks if the target database
10527
+ ** contains a row with the same primary key value (or values) as the
10528
+ ** original row values stored in the changeset. If it does, and the values
9848
10529
  ** stored in all modified non-primary key columns also match the values
9849
10530
  ** stored in the changeset the row is updated within the target database.
9850
10531
  **
@@ -9860,12 +10541,12 @@ SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9860
10541
  ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9861
10542
  ** passed as the second argument.
9862
10543
  **
9863
- ** If the UPDATE operation is attempted, but SQLite returns
9864
- ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
10544
+ ** If the UPDATE operation is attempted, but SQLite returns
10545
+ ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
9865
10546
  ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
9866
- ** This includes the case where the UPDATE operation is attempted after
10547
+ ** This includes the case where the UPDATE operation is attempted after
9867
10548
  ** an earlier call to the conflict handler function returned
9868
- ** [SQLITE_CHANGESET_REPLACE].
10549
+ ** [SQLITE_CHANGESET_REPLACE].
9869
10550
  ** </dl>
9870
10551
  **
9871
10552
  ** It is safe to execute SQL statements, including those that write to the
@@ -9873,11 +10554,28 @@ SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
9873
10554
  ** This can be used to further customize the applications conflict
9874
10555
  ** resolution strategy.
9875
10556
  **
9876
- ** All changes made by this function are enclosed in a savepoint transaction.
10557
+ ** All changes made by these functions are enclosed in a savepoint transaction.
9877
10558
  ** If any other error (aside from a constraint failure when attempting to
9878
10559
  ** write to the target database) occurs, then the savepoint transaction is
9879
- ** rolled back, restoring the target database to its original state, and an
10560
+ ** rolled back, restoring the target database to its original state, and an
9880
10561
  ** SQLite error code returned.
10562
+ **
10563
+ ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
10564
+ ** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
10565
+ ** may set (*ppRebase) to point to a "rebase" that may be used with the
10566
+ ** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
10567
+ ** is set to the size of the buffer in bytes. It is the responsibility of the
10568
+ ** caller to eventually free any such buffer using sqlite3_free(). The buffer
10569
+ ** is only allocated and populated if one or more conflicts were encountered
10570
+ ** while applying the patchset. See comments surrounding the sqlite3_rebaser
10571
+ ** APIs for further details.
10572
+ **
10573
+ ** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
10574
+ ** may be modified by passing a combination of
10575
+ ** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.
10576
+ **
10577
+ ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
10578
+ ** and therefore subject to change.
9881
10579
  */
9882
10580
  SQLITE_API int sqlite3changeset_apply(
9883
10581
  sqlite3 *db, /* Apply change to "main" db of this handle */
@@ -9894,8 +10592,49 @@ SQLITE_API int sqlite3changeset_apply(
9894
10592
  ),
9895
10593
  void *pCtx /* First argument passed to xConflict */
9896
10594
  );
10595
+ SQLITE_API int sqlite3changeset_apply_v2(
10596
+ sqlite3 *db, /* Apply change to "main" db of this handle */
10597
+ int nChangeset, /* Size of changeset in bytes */
10598
+ void *pChangeset, /* Changeset blob */
10599
+ int(*xFilter)(
10600
+ void *pCtx, /* Copy of sixth arg to _apply() */
10601
+ const char *zTab /* Table name */
10602
+ ),
10603
+ int(*xConflict)(
10604
+ void *pCtx, /* Copy of sixth arg to _apply() */
10605
+ int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
10606
+ sqlite3_changeset_iter *p /* Handle describing change and conflict */
10607
+ ),
10608
+ void *pCtx, /* First argument passed to xConflict */
10609
+ void **ppRebase, int *pnRebase, /* OUT: Rebase data */
10610
+ int flags /* SESSION_CHANGESETAPPLY_* flags */
10611
+ );
9897
10612
 
9898
10613
  /*
10614
+ ** CAPI3REF: Flags for sqlite3changeset_apply_v2
10615
+ **
10616
+ ** The following flags may passed via the 9th parameter to
10617
+ ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
10618
+ **
10619
+ ** <dl>
10620
+ ** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
10621
+ ** Usually, the sessions module encloses all operations performed by
10622
+ ** a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The
10623
+ ** SAVEPOINT is committed if the changeset or patchset is successfully
10624
+ ** applied, or rolled back if an error occurs. Specifying this flag
10625
+ ** causes the sessions module to omit this savepoint. In this case, if the
10626
+ ** caller has an open transaction or savepoint when apply_v2() is called,
10627
+ ** it may revert the partially applied changeset by rolling it back.
10628
+ **
10629
+ ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
10630
+ ** Invert the changeset before applying it. This is equivalent to inverting
10631
+ ** a changeset using sqlite3changeset_invert() before applying it. It is
10632
+ ** an error to specify this flag with a patchset.
10633
+ */
10634
+ #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
10635
+ #define SQLITE_CHANGESETAPPLY_INVERT 0x0002
10636
+
10637
+ /*
9899
10638
  ** CAPI3REF: Constants Passed To The Conflict Handler
9900
10639
  **
9901
10640
  ** Values that may be passed as the second argument to a conflict-handler.
@@ -9904,32 +10643,32 @@ SQLITE_API int sqlite3changeset_apply(
9904
10643
  ** <dt>SQLITE_CHANGESET_DATA<dd>
9905
10644
  ** The conflict handler is invoked with CHANGESET_DATA as the second argument
9906
10645
  ** when processing a DELETE or UPDATE change if a row with the required
9907
- ** PRIMARY KEY fields is present in the database, but one or more other
9908
- ** (non primary-key) fields modified by the update do not contain the
10646
+ ** PRIMARY KEY fields is present in the database, but one or more other
10647
+ ** (non primary-key) fields modified by the update do not contain the
9909
10648
  ** expected "before" values.
9910
- **
10649
+ **
9911
10650
  ** The conflicting row, in this case, is the database row with the matching
9912
10651
  ** primary key.
9913
- **
10652
+ **
9914
10653
  ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
9915
10654
  ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
9916
10655
  ** argument when processing a DELETE or UPDATE change if a row with the
9917
10656
  ** required PRIMARY KEY fields is not present in the database.
9918
- **
10657
+ **
9919
10658
  ** There is no conflicting row in this case. The results of invoking the
9920
10659
  ** sqlite3changeset_conflict() API are undefined.
9921
- **
10660
+ **
9922
10661
  ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
9923
10662
  ** CHANGESET_CONFLICT is passed as the second argument to the conflict
9924
- ** handler while processing an INSERT change if the operation would result
10663
+ ** handler while processing an INSERT change if the operation would result
9925
10664
  ** in duplicate primary key values.
9926
- **
10665
+ **
9927
10666
  ** The conflicting row in this case is the database row with the matching
9928
10667
  ** primary key.
9929
10668
  **
9930
10669
  ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
9931
10670
  ** If foreign key handling is enabled, and applying a changeset leaves the
9932
- ** database in a state containing foreign key violations, the conflict
10671
+ ** database in a state containing foreign key violations, the conflict
9933
10672
  ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
9934
10673
  ** exactly once before the changeset is committed. If the conflict handler
9935
10674
  ** returns CHANGESET_OMIT, the changes, including those that caused the
@@ -9939,12 +10678,12 @@ SQLITE_API int sqlite3changeset_apply(
9939
10678
  ** No current or conflicting row information is provided. The only function
9940
10679
  ** it is possible to call on the supplied sqlite3_changeset_iter handle
9941
10680
  ** is sqlite3changeset_fk_conflicts().
9942
- **
10681
+ **
9943
10682
  ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
9944
- ** If any other constraint violation occurs while applying a change (i.e.
9945
- ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
10683
+ ** If any other constraint violation occurs while applying a change (i.e.
10684
+ ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
9946
10685
  ** invoked with CHANGESET_CONSTRAINT as the second argument.
9947
- **
10686
+ **
9948
10687
  ** There is no conflicting row in this case. The results of invoking the
9949
10688
  ** sqlite3changeset_conflict() API are undefined.
9950
10689
  **
@@ -9956,7 +10695,7 @@ SQLITE_API int sqlite3changeset_apply(
9956
10695
  #define SQLITE_CHANGESET_CONSTRAINT 4
9957
10696
  #define SQLITE_CHANGESET_FOREIGN_KEY 5
9958
10697
 
9959
- /*
10698
+ /*
9960
10699
  ** CAPI3REF: Constants Returned By The Conflict Handler
9961
10700
  **
9962
10701
  ** A conflict handler callback must return one of the following three values.
@@ -9964,13 +10703,13 @@ SQLITE_API int sqlite3changeset_apply(
9964
10703
  ** <dl>
9965
10704
  ** <dt>SQLITE_CHANGESET_OMIT<dd>
9966
10705
  ** If a conflict handler returns this value no special action is taken. The
9967
- ** change that caused the conflict is not applied. The session module
10706
+ ** change that caused the conflict is not applied. The session module
9968
10707
  ** continues to the next change in the changeset.
9969
10708
  **
9970
10709
  ** <dt>SQLITE_CHANGESET_REPLACE<dd>
9971
10710
  ** This value may only be returned if the second argument to the conflict
9972
10711
  ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
9973
- ** is not the case, any changes applied so far are rolled back and the
10712
+ ** is not the case, any changes applied so far are rolled back and the
9974
10713
  ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
9975
10714
  **
9976
10715
  ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
@@ -9983,7 +10722,7 @@ SQLITE_API int sqlite3changeset_apply(
9983
10722
  ** the original row is restored to the database before continuing.
9984
10723
  **
9985
10724
  ** <dt>SQLITE_CHANGESET_ABORT<dd>
9986
- ** If this value is returned, any changes applied so far are rolled back
10725
+ ** If this value is returned, any changes applied so far are rolled back
9987
10726
  ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
9988
10727
  ** </dl>
9989
10728
  */
@@ -9991,27 +10730,183 @@ SQLITE_API int sqlite3changeset_apply(
9991
10730
  #define SQLITE_CHANGESET_REPLACE 1
9992
10731
  #define SQLITE_CHANGESET_ABORT 2
9993
10732
 
10733
+ /*
10734
+ ** CAPI3REF: Rebasing changesets
10735
+ ** EXPERIMENTAL
10736
+ **
10737
+ ** Suppose there is a site hosting a database in state S0. And that
10738
+ ** modifications are made that move that database to state S1 and a
10739
+ ** changeset recorded (the "local" changeset). Then, a changeset based
10740
+ ** on S0 is received from another site (the "remote" changeset) and
10741
+ ** applied to the database. The database is then in state
10742
+ ** (S1+"remote"), where the exact state depends on any conflict
10743
+ ** resolution decisions (OMIT or REPLACE) made while applying "remote".
10744
+ ** Rebasing a changeset is to update it to take those conflict
10745
+ ** resolution decisions into account, so that the same conflicts
10746
+ ** do not have to be resolved elsewhere in the network.
10747
+ **
10748
+ ** For example, if both the local and remote changesets contain an
10749
+ ** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
10750
+ **
10751
+ ** local: INSERT INTO t1 VALUES(1, 'v1');
10752
+ ** remote: INSERT INTO t1 VALUES(1, 'v2');
10753
+ **
10754
+ ** and the conflict resolution is REPLACE, then the INSERT change is
10755
+ ** removed from the local changeset (it was overridden). Or, if the
10756
+ ** conflict resolution was "OMIT", then the local changeset is modified
10757
+ ** to instead contain:
10758
+ **
10759
+ ** UPDATE t1 SET b = 'v2' WHERE a=1;
10760
+ **
10761
+ ** Changes within the local changeset are rebased as follows:
10762
+ **
10763
+ ** <dl>
10764
+ ** <dt>Local INSERT<dd>
10765
+ ** This may only conflict with a remote INSERT. If the conflict
10766
+ ** resolution was OMIT, then add an UPDATE change to the rebased
10767
+ ** changeset. Or, if the conflict resolution was REPLACE, add
10768
+ ** nothing to the rebased changeset.
10769
+ **
10770
+ ** <dt>Local DELETE<dd>
10771
+ ** This may conflict with a remote UPDATE or DELETE. In both cases the
10772
+ ** only possible resolution is OMIT. If the remote operation was a
10773
+ ** DELETE, then add no change to the rebased changeset. If the remote
10774
+ ** operation was an UPDATE, then the old.* fields of change are updated
10775
+ ** to reflect the new.* values in the UPDATE.
10776
+ **
10777
+ ** <dt>Local UPDATE<dd>
10778
+ ** This may conflict with a remote UPDATE or DELETE. If it conflicts
10779
+ ** with a DELETE, and the conflict resolution was OMIT, then the update
10780
+ ** is changed into an INSERT. Any undefined values in the new.* record
10781
+ ** from the update change are filled in using the old.* values from
10782
+ ** the conflicting DELETE. Or, if the conflict resolution was REPLACE,
10783
+ ** the UPDATE change is simply omitted from the rebased changeset.
10784
+ **
10785
+ ** If conflict is with a remote UPDATE and the resolution is OMIT, then
10786
+ ** the old.* values are rebased using the new.* values in the remote
10787
+ ** change. Or, if the resolution is REPLACE, then the change is copied
10788
+ ** into the rebased changeset with updates to columns also updated by
10789
+ ** the conflicting remote UPDATE removed. If this means no columns would
10790
+ ** be updated, the change is omitted.
10791
+ ** </dl>
10792
+ **
10793
+ ** A local change may be rebased against multiple remote changes
10794
+ ** simultaneously. If a single key is modified by multiple remote
10795
+ ** changesets, they are combined as follows before the local changeset
10796
+ ** is rebased:
10797
+ **
10798
+ ** <ul>
10799
+ ** <li> If there has been one or more REPLACE resolutions on a
10800
+ ** key, it is rebased according to a REPLACE.
10801
+ **
10802
+ ** <li> If there have been no REPLACE resolutions on a key, then
10803
+ ** the local changeset is rebased according to the most recent
10804
+ ** of the OMIT resolutions.
10805
+ ** </ul>
10806
+ **
10807
+ ** Note that conflict resolutions from multiple remote changesets are
10808
+ ** combined on a per-field basis, not per-row. This means that in the
10809
+ ** case of multiple remote UPDATE operations, some fields of a single
10810
+ ** local change may be rebased for REPLACE while others are rebased for
10811
+ ** OMIT.
10812
+ **
10813
+ ** In order to rebase a local changeset, the remote changeset must first
10814
+ ** be applied to the local database using sqlite3changeset_apply_v2() and
10815
+ ** the buffer of rebase information captured. Then:
10816
+ **
10817
+ ** <ol>
10818
+ ** <li> An sqlite3_rebaser object is created by calling
10819
+ ** sqlite3rebaser_create().
10820
+ ** <li> The new object is configured with the rebase buffer obtained from
10821
+ ** sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
10822
+ ** If the local changeset is to be rebased against multiple remote
10823
+ ** changesets, then sqlite3rebaser_configure() should be called
10824
+ ** multiple times, in the same order that the multiple
10825
+ ** sqlite3changeset_apply_v2() calls were made.
10826
+ ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
10827
+ ** <li> The sqlite3_rebaser object is deleted by calling
10828
+ ** sqlite3rebaser_delete().
10829
+ ** </ol>
10830
+ */
10831
+ typedef struct sqlite3_rebaser sqlite3_rebaser;
10832
+
10833
+ /*
10834
+ ** CAPI3REF: Create a changeset rebaser object.
10835
+ ** EXPERIMENTAL
10836
+ **
10837
+ ** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
10838
+ ** point to the new object and return SQLITE_OK. Otherwise, if an error
10839
+ ** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
10840
+ ** to NULL.
10841
+ */
10842
+ SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
10843
+
10844
+ /*
10845
+ ** CAPI3REF: Configure a changeset rebaser object.
10846
+ ** EXPERIMENTAL
10847
+ **
10848
+ ** Configure the changeset rebaser object to rebase changesets according
10849
+ ** to the conflict resolutions described by buffer pRebase (size nRebase
10850
+ ** bytes), which must have been obtained from a previous call to
10851
+ ** sqlite3changeset_apply_v2().
10852
+ */
10853
+ SQLITE_API int sqlite3rebaser_configure(
10854
+ sqlite3_rebaser*,
10855
+ int nRebase, const void *pRebase
10856
+ );
10857
+
10858
+ /*
10859
+ ** CAPI3REF: Rebase a changeset
10860
+ ** EXPERIMENTAL
10861
+ **
10862
+ ** Argument pIn must point to a buffer containing a changeset nIn bytes
10863
+ ** in size. This function allocates and populates a buffer with a copy
10864
+ ** of the changeset rebased rebased according to the configuration of the
10865
+ ** rebaser object passed as the first argument. If successful, (*ppOut)
10866
+ ** is set to point to the new buffer containing the rebased changset and
10867
+ ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
10868
+ ** responsibility of the caller to eventually free the new buffer using
10869
+ ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
10870
+ ** are set to zero and an SQLite error code returned.
10871
+ */
10872
+ SQLITE_API int sqlite3rebaser_rebase(
10873
+ sqlite3_rebaser*,
10874
+ int nIn, const void *pIn,
10875
+ int *pnOut, void **ppOut
10876
+ );
10877
+
10878
+ /*
10879
+ ** CAPI3REF: Delete a changeset rebaser object.
10880
+ ** EXPERIMENTAL
10881
+ **
10882
+ ** Delete the changeset rebaser object and all associated resources. There
10883
+ ** should be one call to this function for each successful invocation
10884
+ ** of sqlite3rebaser_create().
10885
+ */
10886
+ SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p);
10887
+
9994
10888
  /*
9995
10889
  ** CAPI3REF: Streaming Versions of API functions.
9996
10890
  **
9997
- ** The six streaming API xxx_strm() functions serve similar purposes to the
10891
+ ** The six streaming API xxx_strm() functions serve similar purposes to the
9998
10892
  ** corresponding non-streaming API functions:
9999
10893
  **
10000
10894
  ** <table border=1 style="margin-left:8ex;margin-right:8ex">
10001
10895
  ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
10002
- ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
10003
- ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
10004
- ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
10005
- ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
10006
- ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
10007
- ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
10896
+ ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
10897
+ ** <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2]
10898
+ ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
10899
+ ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
10900
+ ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
10901
+ ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
10902
+ ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
10008
10903
  ** </table>
10009
10904
  **
10010
10905
  ** Non-streaming functions that accept changesets (or patchsets) as input
10011
- ** require that the entire changeset be stored in a single buffer in memory.
10012
- ** Similarly, those that return a changeset or patchset do so by returning
10013
- ** a pointer to a single large buffer allocated using sqlite3_malloc().
10014
- ** Normally this is convenient. However, if an application running in a
10906
+ ** require that the entire changeset be stored in a single buffer in memory.
10907
+ ** Similarly, those that return a changeset or patchset do so by returning
10908
+ ** a pointer to a single large buffer allocated using sqlite3_malloc().
10909
+ ** Normally this is convenient. However, if an application running in a
10015
10910
  ** low-memory environment is required to handle very large changesets, the
10016
10911
  ** large contiguous memory allocations required can become onerous.
10017
10912
  **
@@ -10033,12 +10928,12 @@ SQLITE_API int sqlite3changeset_apply(
10033
10928
  ** </pre>
10034
10929
  **
10035
10930
  ** Each time the xInput callback is invoked by the sessions module, the first
10036
- ** argument passed is a copy of the supplied pIn context pointer. The second
10037
- ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
10038
- ** error occurs the xInput method should copy up to (*pnData) bytes of data
10039
- ** into the buffer and set (*pnData) to the actual number of bytes copied
10040
- ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
10041
- ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
10931
+ ** argument passed is a copy of the supplied pIn context pointer. The second
10932
+ ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
10933
+ ** error occurs the xInput method should copy up to (*pnData) bytes of data
10934
+ ** into the buffer and set (*pnData) to the actual number of bytes copied
10935
+ ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
10936
+ ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
10042
10937
  ** error code should be returned. In all cases, if an xInput callback returns
10043
10938
  ** an error, all processing is abandoned and the streaming API function
10044
10939
  ** returns a copy of the error code to the caller.
@@ -10046,7 +10941,7 @@ SQLITE_API int sqlite3changeset_apply(
10046
10941
  ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
10047
10942
  ** invoked by the sessions module at any point during the lifetime of the
10048
10943
  ** iterator. If such an xInput callback returns an error, the iterator enters
10049
- ** an error state, whereby all subsequent calls to iterator functions
10944
+ ** an error state, whereby all subsequent calls to iterator functions
10050
10945
  ** immediately fail with the same error code as returned by xInput.
10051
10946
  **
10052
10947
  ** Similarly, streaming API functions that return changesets (or patchsets)
@@ -10076,7 +10971,7 @@ SQLITE_API int sqlite3changeset_apply(
10076
10971
  ** is immediately abandoned and the streaming API function returns a copy
10077
10972
  ** of the xOutput error code to the application.
10078
10973
  **
10079
- ** The sessions module never invokes an xOutput callback with the third
10974
+ ** The sessions module never invokes an xOutput callback with the third
10080
10975
  ** parameter set to a value less than or equal to zero. Other than this,
10081
10976
  ** no guarantees are made as to the size of the chunks of data returned.
10082
10977
  */
@@ -10095,6 +10990,23 @@ SQLITE_API int sqlite3changeset_apply_strm(
10095
10990
  ),
10096
10991
  void *pCtx /* First argument passed to xConflict */
10097
10992
  );
10993
+ SQLITE_API int sqlite3changeset_apply_v2_strm(
10994
+ sqlite3 *db, /* Apply change to "main" db of this handle */
10995
+ int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
10996
+ void *pIn, /* First arg for xInput */
10997
+ int(*xFilter)(
10998
+ void *pCtx, /* Copy of sixth arg to _apply() */
10999
+ const char *zTab /* Table name */
11000
+ ),
11001
+ int(*xConflict)(
11002
+ void *pCtx, /* Copy of sixth arg to _apply() */
11003
+ int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
11004
+ sqlite3_changeset_iter *p /* Handle describing change and conflict */
11005
+ ),
11006
+ void *pCtx, /* First argument passed to xConflict */
11007
+ void **ppRebase, int *pnRebase,
11008
+ int flags
11009
+ );
10098
11010
  SQLITE_API int sqlite3changeset_concat_strm(
10099
11011
  int (*xInputA)(void *pIn, void *pData, int *pnData),
10100
11012
  void *pInA,
@@ -10114,6 +11026,12 @@ SQLITE_API int sqlite3changeset_start_strm(
10114
11026
  int (*xInput)(void *pIn, void *pData, int *pnData),
10115
11027
  void *pIn
10116
11028
  );
11029
+ SQLITE_API int sqlite3changeset_start_v2_strm(
11030
+ sqlite3_changeset_iter **pp,
11031
+ int (*xInput)(void *pIn, void *pData, int *pnData),
11032
+ void *pIn,
11033
+ int flags
11034
+ );
10117
11035
  SQLITE_API int sqlite3session_changeset_strm(
10118
11036
  sqlite3_session *pSession,
10119
11037
  int (*xOutput)(void *pOut, const void *pData, int nData),
@@ -10124,15 +11042,61 @@ SQLITE_API int sqlite3session_patchset_strm(
10124
11042
  int (*xOutput)(void *pOut, const void *pData, int nData),
10125
11043
  void *pOut
10126
11044
  );
10127
- SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
11045
+ SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
10128
11046
  int (*xInput)(void *pIn, void *pData, int *pnData),
10129
11047
  void *pIn
10130
11048
  );
10131
11049
  SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
10132
- int (*xOutput)(void *pOut, const void *pData, int nData),
11050
+ int (*xOutput)(void *pOut, const void *pData, int nData),
10133
11051
  void *pOut
10134
11052
  );
11053
+ SQLITE_API int sqlite3rebaser_rebase_strm(
11054
+ sqlite3_rebaser *pRebaser,
11055
+ int (*xInput)(void *pIn, void *pData, int *pnData),
11056
+ void *pIn,
11057
+ int (*xOutput)(void *pOut, const void *pData, int nData),
11058
+ void *pOut
11059
+ );
11060
+
11061
+ /*
11062
+ ** CAPI3REF: Configure global parameters
11063
+ **
11064
+ ** The sqlite3session_config() interface is used to make global configuration
11065
+ ** changes to the sessions module in order to tune it to the specific needs
11066
+ ** of the application.
11067
+ **
11068
+ ** The sqlite3session_config() interface is not threadsafe. If it is invoked
11069
+ ** while any other thread is inside any other sessions method then the
11070
+ ** results are undefined. Furthermore, if it is invoked after any sessions
11071
+ ** related objects have been created, the results are also undefined.
11072
+ **
11073
+ ** The first argument to the sqlite3session_config() function must be one
11074
+ ** of the SQLITE_SESSION_CONFIG_XXX constants defined below. The
11075
+ ** interpretation of the (void*) value passed as the second parameter and
11076
+ ** the effect of calling this function depends on the value of the first
11077
+ ** parameter.
11078
+ **
11079
+ ** <dl>
11080
+ ** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>
11081
+ ** By default, the sessions module streaming interfaces attempt to input
11082
+ ** and output data in approximately 1 KiB chunks. This operand may be used
11083
+ ** to set and query the value of this configuration setting. The pointer
11084
+ ** passed as the second argument must point to a value of type (int).
11085
+ ** If this value is greater than 0, it is used as the new streaming data
11086
+ ** chunk size for both input and output. Before returning, the (int) value
11087
+ ** pointed to by pArg is set to the final value of the streaming interface
11088
+ ** chunk size.
11089
+ ** </dl>
11090
+ **
11091
+ ** This function returns SQLITE_OK if successful, or an SQLite error code
11092
+ ** otherwise.
11093
+ */
11094
+ SQLITE_API int sqlite3session_config(int op, void *pArg);
10135
11095
 
11096
+ /*
11097
+ ** CAPI3REF: Values for sqlite3session_config().
11098
+ */
11099
+ #define SQLITE_SESSION_CONFIG_STRMSIZE 1
10136
11100
 
10137
11101
  /*
10138
11102
  ** Make sure we can call this stuff from C++.
@@ -10254,8 +11218,8 @@ struct Fts5PhraseIter {
10254
11218
  ** an error code (i.e. SQLITE_NOMEM) if an error occurs.
10255
11219
  **
10256
11220
  ** This API can be quite slow if used with an FTS5 table created with the
10257
- ** "detail=none" or "detail=column" option. If the FTS5 table is created
10258
- ** with either "detail=none" or "detail=column" and "content=" option
11221
+ ** "detail=none" or "detail=column" option. If the FTS5 table is created
11222
+ ** with either "detail=none" or "detail=column" and "content=" option
10259
11223
  ** (i.e. if it is a contentless table), then this API always returns 0.
10260
11224
  **
10261
11225
  ** xInst:
@@ -10274,7 +11238,7 @@ struct Fts5PhraseIter {
10274
11238
  ** if an error occurs.
10275
11239
  **
10276
11240
  ** This API can be quite slow if used with an FTS5 table created with the
10277
- ** "detail=none" or "detail=column" option.
11241
+ ** "detail=none" or "detail=column" option.
10278
11242
  **
10279
11243
  ** xRowid:
10280
11244
  ** Returns the rowid of the current row.
@@ -10290,11 +11254,11 @@ struct Fts5PhraseIter {
10290
11254
  **
10291
11255
  ** with $p set to a phrase equivalent to the phrase iPhrase of the
10292
11256
  ** current query is executed. Any column filter that applies to
10293
- ** phrase iPhrase of the current query is included in $p. For each
10294
- ** row visited, the callback function passed as the fourth argument
10295
- ** is invoked. The context and API objects passed to the callback
11257
+ ** phrase iPhrase of the current query is included in $p. For each
11258
+ ** row visited, the callback function passed as the fourth argument
11259
+ ** is invoked. The context and API objects passed to the callback
10296
11260
  ** function may be used to access the properties of each matched row.
10297
- ** Invoking Api.xUserData() returns a copy of the pointer passed as
11261
+ ** Invoking Api.xUserData() returns a copy of the pointer passed as
10298
11262
  ** the third argument to pUserData.
10299
11263
  **
10300
11264
  ** If the callback function returns any value other than SQLITE_OK, the
@@ -10373,8 +11337,8 @@ struct Fts5PhraseIter {
10373
11337
  ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
10374
11338
  **
10375
11339
  ** This API can be quite slow if used with an FTS5 table created with the
10376
- ** "detail=none" or "detail=column" option. If the FTS5 table is created
10377
- ** with either "detail=none" or "detail=column" and "content=" option
11340
+ ** "detail=none" or "detail=column" option. If the FTS5 table is created
11341
+ ** with either "detail=none" or "detail=column" and "content=" option
10378
11342
  ** (i.e. if it is a contentless table), then this API always iterates
10379
11343
  ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
10380
11344
  **
@@ -10398,16 +11362,16 @@ struct Fts5PhraseIter {
10398
11362
  ** }
10399
11363
  **
10400
11364
  ** This API can be quite slow if used with an FTS5 table created with the
10401
- ** "detail=none" option. If the FTS5 table is created with either
10402
- ** "detail=none" "content=" option (i.e. if it is a contentless table),
10403
- ** then this API always iterates through an empty set (all calls to
11365
+ ** "detail=none" option. If the FTS5 table is created with either
11366
+ ** "detail=none" "content=" option (i.e. if it is a contentless table),
11367
+ ** then this API always iterates through an empty set (all calls to
10404
11368
  ** xPhraseFirstColumn() set iCol to -1).
10405
11369
  **
10406
11370
  ** The information accessed using this API and its companion
10407
11371
  ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
10408
11372
  ** (or xInst/xInstCount). The chief advantage of this API is that it is
10409
11373
  ** significantly more efficient than those alternatives when used with
10410
- ** "detail=column" tables.
11374
+ ** "detail=column" tables.
10411
11375
  **
10412
11376
  ** xPhraseNextColumn()
10413
11377
  ** See xPhraseFirstColumn above.
@@ -10590,7 +11554,7 @@ struct Fts5ExtensionApi {
10590
11554
  ** This way, even if the tokenizer does not provide synonyms
10591
11555
  ** when tokenizing query text (it should not - to do would be
10592
11556
  ** inefficient), it doesn't matter if the user queries for
10593
- ** 'first + place' or '1st + place', as there are entires in the
11557
+ ** 'first + place' or '1st + place', as there are entries in the
10594
11558
  ** FTS index corresponding to both forms of the first token.
10595
11559
  ** </ol>
10596
11560
  **
@@ -10618,7 +11582,7 @@ struct Fts5ExtensionApi {
10618
11582
  ** extra data to the FTS index or require FTS5 to query for multiple terms,
10619
11583
  ** so it is efficient in terms of disk space and query speed. However, it
10620
11584
  ** does not support prefix queries very well. If, as suggested above, the
10621
- ** token "first" is subsituted for "1st" by the tokenizer, then the query:
11585
+ ** token "first" is substituted for "1st" by the tokenizer, then the query:
10622
11586
  **
10623
11587
  ** <codeblock>
10624
11588
  ** ... MATCH '1s*'</codeblock>