amalgalite 1.6.1-x64-mingw32 → 1.6.3-x64-mingw32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/CONTRIBUTING.md +11 -0
- data/HISTORY.md +11 -0
- data/README.md +10 -14
- data/ext/amalgalite/c/extconf.rb +3 -2
- data/ext/amalgalite/c/sqlite3.c +37134 -21953
- data/ext/amalgalite/c/sqlite3.h +1376 -412
- data/ext/amalgalite/c/sqlite3ext.h +50 -0
- data/lib/amalgalite/2.2/amalgalite.so +0 -0
- data/lib/amalgalite/2.3/amalgalite.so +0 -0
- data/lib/amalgalite/2.4/amalgalite.so +0 -0
- data/lib/amalgalite/2.5/amalgalite.so +0 -0
- data/lib/amalgalite/2.6/amalgalite.so +0 -0
- data/lib/amalgalite/version.rb +1 -1
- data/spec/sqlite3/version_spec.rb +6 -6
- data/tasks/this.rb +4 -4
- metadata +16 -12
- data/lib/amalgalite/2.0/amalgalite.so +0 -0
- data/lib/amalgalite/2.1/amalgalite.so +0 -0
data/ext/amalgalite/c/sqlite3.h
CHANGED
@@ -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.
|
127
|
-
#define SQLITE_VERSION_NUMBER
|
128
|
-
#define SQLITE_SOURCE_ID "
|
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
|
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
|
1135
|
-
**
|
1136
|
-
**
|
1137
|
-
**
|
1138
|
-
** SQLite version 3.
|
1139
|
-
**
|
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 -
|
2048
|
-
** default) to enable them
|
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
|
2481
|
-
**
|
2482
|
-
**
|
2483
|
-
**
|
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 [
|
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 [
|
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
|
-
**
|
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
|
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
|
3723
|
-
** automatically freed when the prepared
|
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>→<td>64-bit INTEGER result
|
4333
4434
|
** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
|
4334
4435
|
** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
|
4335
|
-
** <tr><td><b>sqlite3_column_value</b><td>→<td>The result as an
|
4436
|
+
** <tr><td><b>sqlite3_column_value</b><td>→<td>The result as an
|
4336
4437
|
** [sqlite3_value|unprotected sqlite3_value] object.
|
4337
4438
|
** <tr><td> <td> <td>
|
4338
4439
|
** <tr><td><b>sqlite3_column_bytes</b><td>→<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
|
-
**
|
4512
|
-
**
|
4513
|
-
**
|
4514
|
-
**
|
4515
|
-
**
|
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.
|
4593
|
-
**
|
4594
|
-
** the second parameter (the name of the function being
|
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
|
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
|
-
** ^
|
4652
|
-
**
|
4653
|
-
**
|
4654
|
-
**
|
4655
|
-
**
|
4656
|
-
**
|
4657
|
-
**
|
4658
|
-
**
|
4659
|
-
**
|
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 </b>
|
4781
4920
|
** <td>→ <td>Best numeric datatype of the value
|
4921
|
+
** <tr><td><b>sqlite3_value_nochange </b>
|
4922
|
+
** <td>→ <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
|
-
**
|
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.
|
6957
|
-
**
|
6958
|
-
**
|
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: [
|
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
|
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 [...]. 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
|
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
|
-
**
|
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
|
-
**
|
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
|
-
**
|
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
|
-
**
|
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
|
-
**
|
9172
|
+
** METHOD: sqlite3_snapshot
|
8706
9173
|
**
|
8707
|
-
** If
|
8708
|
-
**
|
8709
|
-
**
|
8710
|
-
**
|
8711
|
-
**
|
8712
|
-
**
|
8713
|
-
**
|
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
|
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
|
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:
|
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
|
+
** 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.
|
9744
|
-
** "main" database attached to handle db with the changes found in
|
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
|
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
|
9752
|
-
**
|
9753
|
-
**
|
9754
|
-
**
|
9755
|
-
**
|
9756
|
-
**
|
9757
|
-
**
|
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,
|
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,
|
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
|
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>
|
10004
|
-
** <tr><td>
|
10005
|
-
** <tr><td>
|
10006
|
-
** <tr><td>
|
10007
|
-
** <tr><td>
|
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
|
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
|
11585
|
+
** token "first" is substituted for "1st" by the tokenizer, then the query:
|
10622
11586
|
**
|
10623
11587
|
** <codeblock>
|
10624
11588
|
** ... MATCH '1s*'</codeblock>
|