amalgalite 1.7.0-x86-mingw32 → 1.9.0-x86-mingw32
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/HISTORY.md +26 -0
- data/LICENSE +1 -1
- data/README.md +3 -2
- data/Rakefile +9 -8
- data/ext/amalgalite/c/amalgalite_requires_bootstrap.c +2 -1
- data/ext/amalgalite/c/extconf.rb +17 -4
- data/ext/amalgalite/c/sqlite3.c +27647 -14145
- data/ext/amalgalite/c/sqlite3.h +895 -162
- data/ext/amalgalite/c/sqlite3ext.h +48 -2
- 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/2.7/amalgalite.so +0 -0
- data/lib/amalgalite/3.0/amalgalite.so +0 -0
- data/lib/amalgalite/3.1/amalgalite.so +0 -0
- data/lib/amalgalite/csv_table_importer.rb +3 -2
- data/lib/amalgalite/sqlite3/version.rb +3 -3
- data/lib/amalgalite/version.rb +1 -1
- data/spec/sqlite3/version_spec.rb +7 -7
- data/tasks/custom.rake +7 -8
- data/tasks/default.rake +29 -12
- data/tasks/extension.rake +12 -22
- data/tasks/this.rb +6 -6
- metadata +39 -32
- data/lib/amalgalite/2.2/amalgalite.so +0 -0
- data/lib/amalgalite/2.3/amalgalite.so +0 -0
data/ext/amalgalite/c/sqlite3.h
CHANGED
@@ -43,7 +43,30 @@ extern "C" {
|
|
43
43
|
|
44
44
|
|
45
45
|
/*
|
46
|
-
**
|
46
|
+
** Facilitate override of interface linkage and calling conventions.
|
47
|
+
** Be aware that these macros may not be used within this particular
|
48
|
+
** translation of the amalgamation and its associated header file.
|
49
|
+
**
|
50
|
+
** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
|
51
|
+
** compiler that the target identifier should have external linkage.
|
52
|
+
**
|
53
|
+
** The SQLITE_CDECL macro is used to set the calling convention for
|
54
|
+
** public functions that accept a variable number of arguments.
|
55
|
+
**
|
56
|
+
** The SQLITE_APICALL macro is used to set the calling convention for
|
57
|
+
** public functions that accept a fixed number of arguments.
|
58
|
+
**
|
59
|
+
** The SQLITE_STDCALL macro is no longer used and is now deprecated.
|
60
|
+
**
|
61
|
+
** The SQLITE_CALLBACK macro is used to set the calling convention for
|
62
|
+
** function pointers.
|
63
|
+
**
|
64
|
+
** The SQLITE_SYSAPI macro is used to set the calling convention for
|
65
|
+
** functions provided by the operating system.
|
66
|
+
**
|
67
|
+
** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and
|
68
|
+
** SQLITE_SYSAPI macros are used only when building for environments
|
69
|
+
** that require non-default calling conventions.
|
47
70
|
*/
|
48
71
|
#ifndef SQLITE_EXTERN
|
49
72
|
# define SQLITE_EXTERN extern
|
@@ -123,9 +146,9 @@ extern "C" {
|
|
123
146
|
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
|
124
147
|
** [sqlite_version()] and [sqlite_source_id()].
|
125
148
|
*/
|
126
|
-
#define SQLITE_VERSION "3.
|
127
|
-
#define SQLITE_VERSION_NUMBER
|
128
|
-
#define SQLITE_SOURCE_ID "
|
149
|
+
#define SQLITE_VERSION "3.41.2"
|
150
|
+
#define SQLITE_VERSION_NUMBER 3041002
|
151
|
+
#define SQLITE_SOURCE_ID "2023-03-22 11:56:21 0d1fc92f94cb6b76bffe3ec34d69cffde2924203304e8ffc4155597af0c191da"
|
129
152
|
|
130
153
|
/*
|
131
154
|
** CAPI3REF: Run-Time Library Version Numbers
|
@@ -537,12 +560,14 @@ SQLITE_API int sqlite3_exec(
|
|
537
560
|
#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
|
538
561
|
#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
|
539
562
|
#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
|
563
|
+
#define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8))
|
540
564
|
#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
|
541
565
|
#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
|
566
|
+
#define SQLITE_NOTICE_RBU (SQLITE_NOTICE | (3<<8))
|
542
567
|
#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
|
543
568
|
#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
|
544
569
|
#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
|
545
|
-
#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8))
|
570
|
+
#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */
|
546
571
|
|
547
572
|
/*
|
548
573
|
** CAPI3REF: Flags For File Open Operations
|
@@ -550,6 +575,19 @@ SQLITE_API int sqlite3_exec(
|
|
550
575
|
** These bit values are intended for use in the
|
551
576
|
** 3rd parameter to the [sqlite3_open_v2()] interface and
|
552
577
|
** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
|
578
|
+
**
|
579
|
+
** Only those flags marked as "Ok for sqlite3_open_v2()" may be
|
580
|
+
** used as the third argument to the [sqlite3_open_v2()] interface.
|
581
|
+
** The other flags have historically been ignored by sqlite3_open_v2(),
|
582
|
+
** though future versions of SQLite might change so that an error is
|
583
|
+
** raised if any of the disallowed bits are passed into sqlite3_open_v2().
|
584
|
+
** Applications should not depend on the historical behavior.
|
585
|
+
**
|
586
|
+
** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
|
587
|
+
** [sqlite3_open_v2()] does *not* cause the underlying database file
|
588
|
+
** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
|
589
|
+
** [sqlite3_open_v2()] has historically be a no-op and might become an
|
590
|
+
** error in future versions of SQLite.
|
553
591
|
*/
|
554
592
|
#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
|
555
593
|
#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
|
@@ -572,6 +610,7 @@ SQLITE_API int sqlite3_exec(
|
|
572
610
|
#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
|
573
611
|
#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
|
574
612
|
#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
|
613
|
+
#define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
|
575
614
|
|
576
615
|
/* Reserved: 0x00F00000 */
|
577
616
|
/* Legacy compatibility: */
|
@@ -632,13 +671,17 @@ SQLITE_API int sqlite3_exec(
|
|
632
671
|
**
|
633
672
|
** SQLite uses one of these integer values as the second
|
634
673
|
** argument to calls it makes to the xLock() and xUnlock() methods
|
635
|
-
** of an [sqlite3_io_methods] object.
|
674
|
+
** of an [sqlite3_io_methods] object. These values are ordered from
|
675
|
+
** lest restrictive to most restrictive.
|
676
|
+
**
|
677
|
+
** The argument to xLock() is always SHARED or higher. The argument to
|
678
|
+
** xUnlock is either SHARED or NONE.
|
636
679
|
*/
|
637
|
-
#define SQLITE_LOCK_NONE 0
|
638
|
-
#define SQLITE_LOCK_SHARED 1
|
639
|
-
#define SQLITE_LOCK_RESERVED 2
|
640
|
-
#define SQLITE_LOCK_PENDING 3
|
641
|
-
#define SQLITE_LOCK_EXCLUSIVE 4
|
680
|
+
#define SQLITE_LOCK_NONE 0 /* xUnlock() only */
|
681
|
+
#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */
|
682
|
+
#define SQLITE_LOCK_RESERVED 2 /* xLock() only */
|
683
|
+
#define SQLITE_LOCK_PENDING 3 /* xLock() only */
|
684
|
+
#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */
|
642
685
|
|
643
686
|
/*
|
644
687
|
** CAPI3REF: Synchronization Type Flags
|
@@ -716,7 +759,14 @@ struct sqlite3_file {
|
|
716
759
|
** <li> [SQLITE_LOCK_PENDING], or
|
717
760
|
** <li> [SQLITE_LOCK_EXCLUSIVE].
|
718
761
|
** </ul>
|
719
|
-
** xLock()
|
762
|
+
** xLock() upgrades the database file lock. In other words, xLock() moves the
|
763
|
+
** database file lock in the direction NONE toward EXCLUSIVE. The argument to
|
764
|
+
** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
|
765
|
+
** SQLITE_LOCK_NONE. If the database file lock is already at or above the
|
766
|
+
** requested lock, then the call to xLock() is a no-op.
|
767
|
+
** xUnlock() downgrades the database file lock to either SHARED or NONE.
|
768
|
+
* If the lock is already at or below the requested lock state, then the call
|
769
|
+
** to xUnlock() is a no-op.
|
720
770
|
** The xCheckReservedLock() method checks whether any database connection,
|
721
771
|
** either in this process or in some other process, is holding a RESERVED,
|
722
772
|
** PENDING, or EXCLUSIVE lock on the file. It returns true
|
@@ -821,9 +871,8 @@ struct sqlite3_io_methods {
|
|
821
871
|
** opcode causes the xFileControl method to write the current state of
|
822
872
|
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
|
823
873
|
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
|
824
|
-
** into an integer that the pArg argument points to.
|
825
|
-
** is
|
826
|
-
** compile-time option is used.
|
874
|
+
** into an integer that the pArg argument points to.
|
875
|
+
** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
|
827
876
|
**
|
828
877
|
** <li>[[SQLITE_FCNTL_SIZE_HINT]]
|
829
878
|
** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
|
@@ -1127,6 +1176,28 @@ struct sqlite3_io_methods {
|
|
1127
1176
|
** in wal mode after the client has finished copying pages from the wal
|
1128
1177
|
** file to the database file, but before the *-shm file is updated to
|
1129
1178
|
** record the fact that the pages have been checkpointed.
|
1179
|
+
**
|
1180
|
+
** <li>[[SQLITE_FCNTL_EXTERNAL_READER]]
|
1181
|
+
** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
|
1182
|
+
** whether or not there is a database client in another process with a wal-mode
|
1183
|
+
** transaction open on the database or not. It is only available on unix.The
|
1184
|
+
** (void*) argument passed with this file-control should be a pointer to a
|
1185
|
+
** value of type (int). The integer value is set to 1 if the database is a wal
|
1186
|
+
** mode database and there exists at least one client in another process that
|
1187
|
+
** currently has an SQL transaction open on the database. It is set to 0 if
|
1188
|
+
** the database is not a wal-mode db, or if there is no such connection in any
|
1189
|
+
** other process. This opcode cannot be used to detect transactions opened
|
1190
|
+
** by clients within the current process, only within other processes.
|
1191
|
+
**
|
1192
|
+
** <li>[[SQLITE_FCNTL_CKSM_FILE]]
|
1193
|
+
** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use interally by the
|
1194
|
+
** [checksum VFS shim] only.
|
1195
|
+
**
|
1196
|
+
** <li>[[SQLITE_FCNTL_RESET_CACHE]]
|
1197
|
+
** If there is currently no transaction open on the database, and the
|
1198
|
+
** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control
|
1199
|
+
** purges the contents of the in-memory page cache. If there is an open
|
1200
|
+
** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
|
1130
1201
|
** </ul>
|
1131
1202
|
*/
|
1132
1203
|
#define SQLITE_FCNTL_LOCKSTATE 1
|
@@ -1167,6 +1238,9 @@ struct sqlite3_io_methods {
|
|
1167
1238
|
#define SQLITE_FCNTL_CKPT_DONE 37
|
1168
1239
|
#define SQLITE_FCNTL_RESERVE_BYTES 38
|
1169
1240
|
#define SQLITE_FCNTL_CKPT_START 39
|
1241
|
+
#define SQLITE_FCNTL_EXTERNAL_READER 40
|
1242
|
+
#define SQLITE_FCNTL_CKSM_FILE 41
|
1243
|
+
#define SQLITE_FCNTL_RESET_CACHE 42
|
1170
1244
|
|
1171
1245
|
/* deprecated names */
|
1172
1246
|
#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
|
@@ -1196,6 +1270,26 @@ typedef struct sqlite3_mutex sqlite3_mutex;
|
|
1196
1270
|
*/
|
1197
1271
|
typedef struct sqlite3_api_routines sqlite3_api_routines;
|
1198
1272
|
|
1273
|
+
/*
|
1274
|
+
** CAPI3REF: File Name
|
1275
|
+
**
|
1276
|
+
** Type [sqlite3_filename] is used by SQLite to pass filenames to the
|
1277
|
+
** xOpen method of a [VFS]. It may be cast to (const char*) and treated
|
1278
|
+
** as a normal, nul-terminated, UTF-8 buffer containing the filename, but
|
1279
|
+
** may also be passed to special APIs such as:
|
1280
|
+
**
|
1281
|
+
** <ul>
|
1282
|
+
** <li> sqlite3_filename_database()
|
1283
|
+
** <li> sqlite3_filename_journal()
|
1284
|
+
** <li> sqlite3_filename_wal()
|
1285
|
+
** <li> sqlite3_uri_parameter()
|
1286
|
+
** <li> sqlite3_uri_boolean()
|
1287
|
+
** <li> sqlite3_uri_int64()
|
1288
|
+
** <li> sqlite3_uri_key()
|
1289
|
+
** </ul>
|
1290
|
+
*/
|
1291
|
+
typedef const char *sqlite3_filename;
|
1292
|
+
|
1199
1293
|
/*
|
1200
1294
|
** CAPI3REF: OS Interface Object
|
1201
1295
|
**
|
@@ -1374,7 +1468,7 @@ struct sqlite3_vfs {
|
|
1374
1468
|
sqlite3_vfs *pNext; /* Next registered VFS */
|
1375
1469
|
const char *zName; /* Name of this virtual file system */
|
1376
1470
|
void *pAppData; /* Pointer to application-specific data */
|
1377
|
-
int (*xOpen)(sqlite3_vfs*,
|
1471
|
+
int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
|
1378
1472
|
int flags, int *pOutFlags);
|
1379
1473
|
int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
|
1380
1474
|
int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
|
@@ -2090,7 +2184,7 @@ struct sqlite3_mem_methods {
|
|
2090
2184
|
** configuration for a database connection can only be changed when that
|
2091
2185
|
** connection is not currently using lookaside memory, or in other words
|
2092
2186
|
** when the "current value" returned by
|
2093
|
-
** [sqlite3_db_status](D,[
|
2187
|
+
** [sqlite3_db_status](D,[SQLITE_DBSTATUS_LOOKASIDE_USED],...) is zero.
|
2094
2188
|
** Any attempt to change the lookaside memory configuration when lookaside
|
2095
2189
|
** memory is in use leaves the configuration unchanged and returns
|
2096
2190
|
** [SQLITE_BUSY].)^</dd>
|
@@ -2115,7 +2209,13 @@ struct sqlite3_mem_methods {
|
|
2115
2209
|
** The second parameter is a pointer to an integer into which
|
2116
2210
|
** is written 0 or 1 to indicate whether triggers are disabled or enabled
|
2117
2211
|
** following this call. The second parameter may be a NULL pointer, in
|
2118
|
-
** which case the trigger setting is not reported back.
|
2212
|
+
** which case the trigger setting is not reported back.
|
2213
|
+
**
|
2214
|
+
** <p>Originally this option disabled all triggers. ^(However, since
|
2215
|
+
** SQLite version 3.35.0, TEMP triggers are still allowed even if
|
2216
|
+
** this option is off. So, in other words, this option now only disables
|
2217
|
+
** triggers in the main database schema or in the schemas of ATTACH-ed
|
2218
|
+
** databases.)^ </dd>
|
2119
2219
|
**
|
2120
2220
|
** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
|
2121
2221
|
** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
|
@@ -2126,7 +2226,13 @@ struct sqlite3_mem_methods {
|
|
2126
2226
|
** The second parameter is a pointer to an integer into which
|
2127
2227
|
** is written 0 or 1 to indicate whether views are disabled or enabled
|
2128
2228
|
** following this call. The second parameter may be a NULL pointer, in
|
2129
|
-
** which case the view setting is not reported back.
|
2229
|
+
** which case the view setting is not reported back.
|
2230
|
+
**
|
2231
|
+
** <p>Originally this option disabled all views. ^(However, since
|
2232
|
+
** SQLite version 3.35.0, TEMP views are still allowed even if
|
2233
|
+
** this option is off. So, in other words, this option now only disables
|
2234
|
+
** views in the main database schema or in the schemas of ATTACH-ed
|
2235
|
+
** databases.)^ </dd>
|
2130
2236
|
**
|
2131
2237
|
** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
|
2132
2238
|
** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
|
@@ -2228,8 +2334,12 @@ struct sqlite3_mem_methods {
|
|
2228
2334
|
** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
|
2229
2335
|
** </ol>
|
2230
2336
|
** Because resetting a database is destructive and irreversible, the
|
2231
|
-
** process requires the use of this obscure API and multiple steps to
|
2232
|
-
** ensure that it does not happen by accident.
|
2337
|
+
** process requires the use of this obscure API and multiple steps to
|
2338
|
+
** help ensure that it does not happen by accident. Because this
|
2339
|
+
** feature must be capable of resetting corrupt databases, and
|
2340
|
+
** shutting down virtual tables may require access to that corrupt
|
2341
|
+
** storage, the library must abandon any installed virtual tables
|
2342
|
+
** without calling their xDestroy() methods.
|
2233
2343
|
**
|
2234
2344
|
** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
|
2235
2345
|
** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
|
@@ -2240,6 +2350,7 @@ struct sqlite3_mem_methods {
|
|
2240
2350
|
** <ul>
|
2241
2351
|
** <li> The [PRAGMA writable_schema=ON] statement.
|
2242
2352
|
** <li> The [PRAGMA journal_mode=OFF] statement.
|
2353
|
+
** <li> The [PRAGMA schema_version=N] statement.
|
2243
2354
|
** <li> Writes to the [sqlite_dbpage] virtual table.
|
2244
2355
|
** <li> Direct writes to [shadow tables].
|
2245
2356
|
** </ul>
|
@@ -2433,11 +2544,14 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
|
|
2433
2544
|
** CAPI3REF: Count The Number Of Rows Modified
|
2434
2545
|
** METHOD: sqlite3
|
2435
2546
|
**
|
2436
|
-
** ^
|
2547
|
+
** ^These functions return the number of rows modified, inserted or
|
2437
2548
|
** deleted by the most recently completed INSERT, UPDATE or DELETE
|
2438
2549
|
** statement on the database connection specified by the only parameter.
|
2439
|
-
**
|
2440
|
-
**
|
2550
|
+
** The two functions are identical except for the type of the return value
|
2551
|
+
** and that if the number of rows modified by the most recent INSERT, UPDATE
|
2552
|
+
** or DELETE is greater than the maximum value supported by type "int", then
|
2553
|
+
** the return value of sqlite3_changes() is undefined. ^Executing any other
|
2554
|
+
** type of SQL statement does not modify the value returned by these functions.
|
2441
2555
|
**
|
2442
2556
|
** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
|
2443
2557
|
** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
|
@@ -2486,16 +2600,21 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
|
|
2486
2600
|
** </ul>
|
2487
2601
|
*/
|
2488
2602
|
SQLITE_API int sqlite3_changes(sqlite3*);
|
2603
|
+
SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*);
|
2489
2604
|
|
2490
2605
|
/*
|
2491
2606
|
** CAPI3REF: Total Number Of Rows Modified
|
2492
2607
|
** METHOD: sqlite3
|
2493
2608
|
**
|
2494
|
-
** ^
|
2609
|
+
** ^These functions return the total number of rows inserted, modified or
|
2495
2610
|
** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
|
2496
2611
|
** since the database connection was opened, including those executed as
|
2497
|
-
** part of trigger programs.
|
2498
|
-
**
|
2612
|
+
** part of trigger programs. The two functions are identical except for the
|
2613
|
+
** type of the return value and that if the number of rows modified by the
|
2614
|
+
** connection exceeds the maximum value supported by type "int", then
|
2615
|
+
** the return value of sqlite3_total_changes() is undefined. ^Executing
|
2616
|
+
** any other type of SQL statement does not affect the value returned by
|
2617
|
+
** sqlite3_total_changes().
|
2499
2618
|
**
|
2500
2619
|
** ^Changes made as part of [foreign key actions] are included in the
|
2501
2620
|
** count, but those made as part of REPLACE constraint resolution are
|
@@ -2523,6 +2642,7 @@ SQLITE_API int sqlite3_changes(sqlite3*);
|
|
2523
2642
|
** </ul>
|
2524
2643
|
*/
|
2525
2644
|
SQLITE_API int sqlite3_total_changes(sqlite3*);
|
2645
|
+
SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*);
|
2526
2646
|
|
2527
2647
|
/*
|
2528
2648
|
** CAPI3REF: Interrupt A Long-Running Query
|
@@ -2558,8 +2678,12 @@ SQLITE_API int sqlite3_total_changes(sqlite3*);
|
|
2558
2678
|
** ^A call to sqlite3_interrupt(D) that occurs when there are no running
|
2559
2679
|
** SQL statements is a no-op and has no effect on SQL statements
|
2560
2680
|
** that are started after the sqlite3_interrupt() call returns.
|
2681
|
+
**
|
2682
|
+
** ^The [sqlite3_is_interrupted(D)] interface can be used to determine whether
|
2683
|
+
** or not an interrupt is currently in effect for [database connection] D.
|
2561
2684
|
*/
|
2562
2685
|
SQLITE_API void sqlite3_interrupt(sqlite3*);
|
2686
|
+
SQLITE_API int sqlite3_is_interrupted(sqlite3*);
|
2563
2687
|
|
2564
2688
|
/*
|
2565
2689
|
** CAPI3REF: Determine If An SQL Statement Is Complete
|
@@ -3177,8 +3301,8 @@ SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
|
|
3177
3301
|
** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
|
3178
3302
|
** information as is provided by the [sqlite3_profile()] callback.
|
3179
3303
|
** ^The P argument is a pointer to the [prepared statement] and the
|
3180
|
-
** X argument points to a 64-bit integer which is
|
3181
|
-
** the number of
|
3304
|
+
** X argument points to a 64-bit integer which is approximately
|
3305
|
+
** the number of nanoseconds that the prepared statement took to run.
|
3182
3306
|
** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
|
3183
3307
|
**
|
3184
3308
|
** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
|
@@ -3241,7 +3365,7 @@ SQLITE_API int sqlite3_trace_v2(
|
|
3241
3365
|
**
|
3242
3366
|
** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
|
3243
3367
|
** function X to be invoked periodically during long running calls to
|
3244
|
-
** [
|
3368
|
+
** [sqlite3_step()] and [sqlite3_prepare()] and similar for
|
3245
3369
|
** database connection D. An example use for this
|
3246
3370
|
** interface is to keep a GUI updated during a large query.
|
3247
3371
|
**
|
@@ -3266,6 +3390,13 @@ SQLITE_API int sqlite3_trace_v2(
|
|
3266
3390
|
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
|
3267
3391
|
** database connections for the meaning of "modify" in this paragraph.
|
3268
3392
|
**
|
3393
|
+
** The progress handler callback would originally only be invoked from the
|
3394
|
+
** bytecode engine. It still might be invoked during [sqlite3_prepare()]
|
3395
|
+
** and similar because those routines might force a reparse of the schema
|
3396
|
+
** which involves running the bytecode engine. However, beginning with
|
3397
|
+
** SQLite version 3.41.0, the progress handler callback might also be
|
3398
|
+
** invoked directly from [sqlite3_prepare()] while analyzing and generating
|
3399
|
+
** code for complex queries.
|
3269
3400
|
*/
|
3270
3401
|
SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
3271
3402
|
|
@@ -3302,13 +3433,18 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
3302
3433
|
**
|
3303
3434
|
** <dl>
|
3304
3435
|
** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
|
3305
|
-
** <dd>The database is opened in read-only mode. If the database does
|
3306
|
-
** already exist, an error is returned.</dd>)^
|
3436
|
+
** <dd>The database is opened in read-only mode. If the database does
|
3437
|
+
** not already exist, an error is returned.</dd>)^
|
3307
3438
|
**
|
3308
3439
|
** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
|
3309
|
-
** <dd>The database is opened for reading and writing if possible, or
|
3310
|
-
** only if the file is write protected by the operating
|
3311
|
-
** case the database must already exist, otherwise
|
3440
|
+
** <dd>The database is opened for reading and writing if possible, or
|
3441
|
+
** reading only if the file is write protected by the operating
|
3442
|
+
** system. In either case the database must already exist, otherwise
|
3443
|
+
** an error is returned. For historical reasons, if opening in
|
3444
|
+
** read-write mode fails due to OS-level permissions, an attempt is
|
3445
|
+
** made to open it in read-only mode. [sqlite3_db_readonly()] can be
|
3446
|
+
** used to determine whether the database is actually
|
3447
|
+
** read-write.</dd>)^
|
3312
3448
|
**
|
3313
3449
|
** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
|
3314
3450
|
** <dd>The database is opened for reading and writing, and is created if
|
@@ -3346,20 +3482,39 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
3346
3482
|
** <dd>The database is opened [shared cache] enabled, overriding
|
3347
3483
|
** the default shared cache setting provided by
|
3348
3484
|
** [sqlite3_enable_shared_cache()].)^
|
3485
|
+
** The [use of shared cache mode is discouraged] and hence shared cache
|
3486
|
+
** capabilities may be omitted from many builds of SQLite. In such cases,
|
3487
|
+
** this option is a no-op.
|
3349
3488
|
**
|
3350
3489
|
** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
|
3351
3490
|
** <dd>The database is opened [shared cache] disabled, overriding
|
3352
3491
|
** the default shared cache setting provided by
|
3353
3492
|
** [sqlite3_enable_shared_cache()].)^
|
3354
3493
|
**
|
3494
|
+
** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt>
|
3495
|
+
** <dd>The database connection comes up in "extended result code mode".
|
3496
|
+
** In other words, the database behaves has if
|
3497
|
+
** [sqlite3_extended_result_codes(db,1)] where called on the database
|
3498
|
+
** connection as soon as the connection is created. In addition to setting
|
3499
|
+
** the extended result code mode, this flag also causes [sqlite3_open_v2()]
|
3500
|
+
** to return an extended result code.</dd>
|
3501
|
+
**
|
3355
3502
|
** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
|
3356
|
-
** <dd>The database filename is not allowed to
|
3503
|
+
** <dd>The database filename is not allowed to contain a symbolic link</dd>
|
3357
3504
|
** </dl>)^
|
3358
3505
|
**
|
3359
3506
|
** If the 3rd parameter to sqlite3_open_v2() is not one of the
|
3360
3507
|
** required combinations shown above optionally combined with other
|
3361
3508
|
** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
|
3362
|
-
** then the behavior is undefined.
|
3509
|
+
** then the behavior is undefined. Historic versions of SQLite
|
3510
|
+
** have silently ignored surplus bits in the flags parameter to
|
3511
|
+
** sqlite3_open_v2(), however that behavior might not be carried through
|
3512
|
+
** into future versions of SQLite and so applications should not rely
|
3513
|
+
** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
|
3514
|
+
** for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
|
3515
|
+
** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
|
3516
|
+
** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
|
3517
|
+
** by sqlite3_open_v2().
|
3363
3518
|
**
|
3364
3519
|
** ^The fourth parameter to sqlite3_open_v2() is the name of the
|
3365
3520
|
** [sqlite3_vfs] object that defines the operating system interface that
|
@@ -3499,6 +3654,7 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
3499
3654
|
** that uses dot-files in place of posix advisory locking.
|
3500
3655
|
** <tr><td> file:data.db?mode=readonly <td>
|
3501
3656
|
** An error. "readonly" is not a valid option for the "mode" parameter.
|
3657
|
+
** Use "ro" instead: "file:data.db?mode=ro".
|
3502
3658
|
** </table>
|
3503
3659
|
**
|
3504
3660
|
** ^URI hexadecimal escape sequences (%HH) are supported within the path and
|
@@ -3603,10 +3759,10 @@ SQLITE_API int sqlite3_open_v2(
|
|
3603
3759
|
**
|
3604
3760
|
** See the [URI filename] documentation for additional information.
|
3605
3761
|
*/
|
3606
|
-
SQLITE_API const char *sqlite3_uri_parameter(
|
3607
|
-
SQLITE_API int sqlite3_uri_boolean(
|
3608
|
-
SQLITE_API sqlite3_int64 sqlite3_uri_int64(
|
3609
|
-
SQLITE_API const char *sqlite3_uri_key(
|
3762
|
+
SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
|
3763
|
+
SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
|
3764
|
+
SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
|
3765
|
+
SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);
|
3610
3766
|
|
3611
3767
|
/*
|
3612
3768
|
** CAPI3REF: Translate filenames
|
@@ -3635,9 +3791,9 @@ SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
|
|
3635
3791
|
** return value from [sqlite3_db_filename()], then the result is
|
3636
3792
|
** undefined and is likely a memory access violation.
|
3637
3793
|
*/
|
3638
|
-
SQLITE_API const char *sqlite3_filename_database(
|
3639
|
-
SQLITE_API const char *sqlite3_filename_journal(
|
3640
|
-
SQLITE_API const char *sqlite3_filename_wal(
|
3794
|
+
SQLITE_API const char *sqlite3_filename_database(sqlite3_filename);
|
3795
|
+
SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename);
|
3796
|
+
SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename);
|
3641
3797
|
|
3642
3798
|
/*
|
3643
3799
|
** CAPI3REF: Database File Corresponding To A Journal
|
@@ -3697,20 +3853,20 @@ SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
|
|
3697
3853
|
** If the Y parameter to sqlite3_free_filename(Y) is anything other
|
3698
3854
|
** than a NULL pointer or a pointer previously acquired from
|
3699
3855
|
** sqlite3_create_filename(), then bad things such as heap
|
3700
|
-
** corruption or segfaults may occur. The value Y should be
|
3856
|
+
** corruption or segfaults may occur. The value Y should not be
|
3701
3857
|
** used again after sqlite3_free_filename(Y) has been called. This means
|
3702
3858
|
** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
|
3703
3859
|
** then the corresponding [sqlite3_module.xClose() method should also be
|
3704
3860
|
** invoked prior to calling sqlite3_free_filename(Y).
|
3705
3861
|
*/
|
3706
|
-
SQLITE_API
|
3862
|
+
SQLITE_API sqlite3_filename sqlite3_create_filename(
|
3707
3863
|
const char *zDatabase,
|
3708
3864
|
const char *zJournal,
|
3709
3865
|
const char *zWal,
|
3710
3866
|
int nParam,
|
3711
3867
|
const char **azParam
|
3712
3868
|
);
|
3713
|
-
SQLITE_API void sqlite3_free_filename(
|
3869
|
+
SQLITE_API void sqlite3_free_filename(sqlite3_filename);
|
3714
3870
|
|
3715
3871
|
/*
|
3716
3872
|
** CAPI3REF: Error Codes And Messages
|
@@ -3729,13 +3885,14 @@ SQLITE_API void sqlite3_free_filename(char*);
|
|
3729
3885
|
** sqlite3_extended_errcode() might change with each API call.
|
3730
3886
|
** Except, there are some interfaces that are guaranteed to never
|
3731
3887
|
** change the value of the error code. The error-code preserving
|
3732
|
-
** interfaces
|
3888
|
+
** interfaces include the following:
|
3733
3889
|
**
|
3734
3890
|
** <ul>
|
3735
3891
|
** <li> sqlite3_errcode()
|
3736
3892
|
** <li> sqlite3_extended_errcode()
|
3737
3893
|
** <li> sqlite3_errmsg()
|
3738
3894
|
** <li> sqlite3_errmsg16()
|
3895
|
+
** <li> sqlite3_error_offset()
|
3739
3896
|
** </ul>
|
3740
3897
|
**
|
3741
3898
|
** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
|
@@ -3750,6 +3907,13 @@ SQLITE_API void sqlite3_free_filename(char*);
|
|
3750
3907
|
** ^(Memory to hold the error message string is managed internally
|
3751
3908
|
** and must not be freed by the application)^.
|
3752
3909
|
**
|
3910
|
+
** ^If the most recent error references a specific token in the input
|
3911
|
+
** SQL, the sqlite3_error_offset() interface returns the byte offset
|
3912
|
+
** of the start of that token. ^The byte offset returned by
|
3913
|
+
** sqlite3_error_offset() assumes that the input SQL is UTF8.
|
3914
|
+
** ^If the most recent error does not reference a specific token in the input
|
3915
|
+
** SQL, then the sqlite3_error_offset() function returns -1.
|
3916
|
+
**
|
3753
3917
|
** When the serialized [threading mode] is in use, it might be the
|
3754
3918
|
** case that a second error occurs on a separate thread in between
|
3755
3919
|
** the time of the first error and the call to these interfaces.
|
@@ -3769,6 +3933,7 @@ SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
|
|
3769
3933
|
SQLITE_API const char *sqlite3_errmsg(sqlite3*);
|
3770
3934
|
SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
|
3771
3935
|
SQLITE_API const char *sqlite3_errstr(int);
|
3936
|
+
SQLITE_API int sqlite3_error_offset(sqlite3 *db);
|
3772
3937
|
|
3773
3938
|
/*
|
3774
3939
|
** CAPI3REF: Prepared Statement Object
|
@@ -4126,12 +4291,17 @@ SQLITE_API int sqlite3_prepare16_v3(
|
|
4126
4291
|
** are managed by SQLite and are automatically freed when the prepared
|
4127
4292
|
** statement is finalized.
|
4128
4293
|
** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
|
4129
|
-
** is obtained from [sqlite3_malloc()] and must be
|
4294
|
+
** is obtained from [sqlite3_malloc()] and must be freed by the application
|
4130
4295
|
** by passing it to [sqlite3_free()].
|
4296
|
+
**
|
4297
|
+
** ^The sqlite3_normalized_sql() interface is only available if
|
4298
|
+
** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
|
4131
4299
|
*/
|
4132
4300
|
SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
|
4133
4301
|
SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
|
4302
|
+
#ifdef SQLITE_ENABLE_NORMALIZE
|
4134
4303
|
SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
|
4304
|
+
#endif
|
4135
4305
|
|
4136
4306
|
/*
|
4137
4307
|
** CAPI3REF: Determine If An SQL Statement Writes The Database
|
@@ -4166,6 +4336,19 @@ SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
|
|
4166
4336
|
** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
|
4167
4337
|
** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
|
4168
4338
|
** sqlite3_stmt_readonly() returns false for those commands.
|
4339
|
+
**
|
4340
|
+
** ^This routine returns false if there is any possibility that the
|
4341
|
+
** statement might change the database file. ^A false return does
|
4342
|
+
** not guarantee that the statement will change the database file.
|
4343
|
+
** ^For example, an UPDATE statement might have a WHERE clause that
|
4344
|
+
** makes it a no-op, but the sqlite3_stmt_readonly() result would still
|
4345
|
+
** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
|
4346
|
+
** read-only no-op if the table already exists, but
|
4347
|
+
** sqlite3_stmt_readonly() still returns false for such a statement.
|
4348
|
+
**
|
4349
|
+
** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
|
4350
|
+
** statement, then sqlite3_stmt_readonly(X) returns the same value as
|
4351
|
+
** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
|
4169
4352
|
*/
|
4170
4353
|
SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
4171
4354
|
|
@@ -4234,6 +4417,8 @@ SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
|
|
4234
4417
|
**
|
4235
4418
|
** ^The sqlite3_value objects that are passed as parameters into the
|
4236
4419
|
** implementation of [application-defined SQL functions] are protected.
|
4420
|
+
** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()]
|
4421
|
+
** are protected.
|
4237
4422
|
** ^The sqlite3_value object returned by
|
4238
4423
|
** [sqlite3_column_value()] is unprotected.
|
4239
4424
|
** Unprotected sqlite3_value objects may only be used as arguments
|
@@ -4335,18 +4520,22 @@ typedef struct sqlite3_context sqlite3_context;
|
|
4335
4520
|
** contain embedded NULs. The result of expressions involving strings
|
4336
4521
|
** with embedded NULs is undefined.
|
4337
4522
|
**
|
4338
|
-
** ^The fifth argument to the BLOB and string binding interfaces
|
4339
|
-
**
|
4340
|
-
**
|
4341
|
-
** to dispose of the BLOB or string
|
4342
|
-
**
|
4343
|
-
**
|
4344
|
-
**
|
4345
|
-
**
|
4346
|
-
**
|
4347
|
-
**
|
4348
|
-
**
|
4349
|
-
**
|
4523
|
+
** ^The fifth argument to the BLOB and string binding interfaces controls
|
4524
|
+
** or indicates the lifetime of the object referenced by the third parameter.
|
4525
|
+
** These three options exist:
|
4526
|
+
** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished
|
4527
|
+
** with it may be passed. ^It is called to dispose of the BLOB or string even
|
4528
|
+
** if the call to the bind API fails, except the destructor is not called if
|
4529
|
+
** the third parameter is a NULL pointer or the fourth parameter is negative.
|
4530
|
+
** ^ (2) The special constant, [SQLITE_STATIC], may be passsed to indicate that
|
4531
|
+
** the application remains responsible for disposing of the object. ^In this
|
4532
|
+
** case, the object and the provided pointer to it must remain valid until
|
4533
|
+
** either the prepared statement is finalized or the same SQL parameter is
|
4534
|
+
** bound to something else, whichever occurs sooner.
|
4535
|
+
** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the
|
4536
|
+
** object is to be copied prior to the return from sqlite3_bind_*(). ^The
|
4537
|
+
** object and pointer to it must remain valid until then. ^SQLite will then
|
4538
|
+
** manage the lifetime of its private copy.
|
4350
4539
|
**
|
4351
4540
|
** ^The sixth argument to sqlite3_bind_text64() must be one of
|
4352
4541
|
** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
|
@@ -4851,6 +5040,10 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
4851
5040
|
** even empty strings, are always zero-terminated. ^The return
|
4852
5041
|
** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
|
4853
5042
|
**
|
5043
|
+
** ^Strings returned by sqlite3_column_text16() always have the endianness
|
5044
|
+
** which is native to the platform, regardless of the text encoding set
|
5045
|
+
** for the database.
|
5046
|
+
**
|
4854
5047
|
** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
|
4855
5048
|
** [unprotected sqlite3_value] object. In a multithreaded environment,
|
4856
5049
|
** an unprotected sqlite3_value object may only be used safely with
|
@@ -4864,7 +5057,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
4864
5057
|
** [application-defined SQL functions] or [virtual tables], not within
|
4865
5058
|
** top-level application code.
|
4866
5059
|
**
|
4867
|
-
**
|
5060
|
+
** These routines may attempt to convert the datatype of the result.
|
4868
5061
|
** ^For example, if the internal representation is FLOAT and a text result
|
4869
5062
|
** is requested, [sqlite3_snprintf()] is used internally to perform the
|
4870
5063
|
** conversion automatically. ^(The following table details the conversions
|
@@ -4889,7 +5082,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
4889
5082
|
** <tr><td> TEXT <td> BLOB <td> No change
|
4890
5083
|
** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
|
4891
5084
|
** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
|
4892
|
-
** <tr><td> BLOB <td> TEXT <td>
|
5085
|
+
** <tr><td> BLOB <td> TEXT <td> [CAST] to TEXT, ensure zero terminator
|
4893
5086
|
** </table>
|
4894
5087
|
** </blockquote>)^
|
4895
5088
|
**
|
@@ -5088,7 +5281,6 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
|
|
5088
5281
|
** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
|
5089
5282
|
** index expressions, or the WHERE clause of partial indexes.
|
5090
5283
|
**
|
5091
|
-
** <span style="background-color:#ffff90;">
|
5092
5284
|
** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
|
5093
5285
|
** all application-defined SQL functions that do not need to be
|
5094
5286
|
** used inside of triggers, view, CHECK constraints, or other elements of
|
@@ -5098,7 +5290,6 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
|
|
5098
5290
|
** a database file to include invocations of the function with parameters
|
5099
5291
|
** chosen by the attacker, which the application will then execute when
|
5100
5292
|
** the database file is opened and read.
|
5101
|
-
** </span>
|
5102
5293
|
**
|
5103
5294
|
** ^(The fifth parameter is an arbitrary pointer. The implementation of the
|
5104
5295
|
** function can gain access to this pointer using [sqlite3_user_data()].)^
|
@@ -5234,10 +5425,21 @@ SQLITE_API int sqlite3_create_window_function(
|
|
5234
5425
|
** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
|
5235
5426
|
** schema structures such as [CHECK constraints], [DEFAULT clauses],
|
5236
5427
|
** [expression indexes], [partial indexes], or [generated columns].
|
5237
|
-
**
|
5238
|
-
**
|
5239
|
-
**
|
5240
|
-
** information.
|
5428
|
+
** <p>
|
5429
|
+
** The SQLITE_DIRECTONLY flag is recommended for any
|
5430
|
+
** [application-defined SQL function]
|
5431
|
+
** that has side-effects or that could potentially leak sensitive information.
|
5432
|
+
** This will prevent attacks in which an application is tricked
|
5433
|
+
** into using a database file that has had its schema surreptiously
|
5434
|
+
** modified to invoke the application-defined function in ways that are
|
5435
|
+
** harmful.
|
5436
|
+
** <p>
|
5437
|
+
** Some people say it is good practice to set SQLITE_DIRECTONLY on all
|
5438
|
+
** [application-defined SQL functions], regardless of whether or not they
|
5439
|
+
** are security sensitive, as doing so prevents those functions from being used
|
5440
|
+
** inside of the database schema, and thus ensures that the database
|
5441
|
+
** can be inspected and modified using generic tools (such as the [CLI])
|
5442
|
+
** that do not have access to the application-defined functions.
|
5241
5443
|
** </dd>
|
5242
5444
|
**
|
5243
5445
|
** [[SQLITE_INNOCUOUS]] <dt>SQLITE_INNOCUOUS</dt><dd>
|
@@ -5443,6 +5645,28 @@ SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
|
|
5443
5645
|
SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
|
5444
5646
|
SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
|
5445
5647
|
|
5648
|
+
/*
|
5649
|
+
** CAPI3REF: Report the internal text encoding state of an sqlite3_value object
|
5650
|
+
** METHOD: sqlite3_value
|
5651
|
+
**
|
5652
|
+
** ^(The sqlite3_value_encoding(X) interface returns one of [SQLITE_UTF8],
|
5653
|
+
** [SQLITE_UTF16BE], or [SQLITE_UTF16LE] according to the current text encoding
|
5654
|
+
** of the value X, assuming that X has type TEXT.)^ If sqlite3_value_type(X)
|
5655
|
+
** returns something other than SQLITE_TEXT, then the return value from
|
5656
|
+
** sqlite3_value_encoding(X) is meaningless. ^Calls to
|
5657
|
+
** [sqlite3_value_text(X)], [sqlite3_value_text16(X)], [sqlite3_value_text16be(X)],
|
5658
|
+
** [sqlite3_value_text16le(X)], [sqlite3_value_bytes(X)], or
|
5659
|
+
** [sqlite3_value_bytes16(X)] might change the encoding of the value X and
|
5660
|
+
** thus change the return from subsequent calls to sqlite3_value_encoding(X).
|
5661
|
+
**
|
5662
|
+
** This routine is intended for used by applications that test and validate
|
5663
|
+
** the SQLite implementation. This routine is inquiring about the opaque
|
5664
|
+
** internal state of an [sqlite3_value] object. Ordinary applications should
|
5665
|
+
** not need to know what the internal state of an sqlite3_value object is and
|
5666
|
+
** hence should not need to use this interface.
|
5667
|
+
*/
|
5668
|
+
SQLITE_API int sqlite3_value_encoding(sqlite3_value*);
|
5669
|
+
|
5446
5670
|
/*
|
5447
5671
|
** CAPI3REF: Finding The Subtype Of SQL Values
|
5448
5672
|
** METHOD: sqlite3_value
|
@@ -5463,7 +5687,8 @@ SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
|
|
5463
5687
|
** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
|
5464
5688
|
** is a [protected sqlite3_value] object even if the input is not.
|
5465
5689
|
** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
|
5466
|
-
** memory allocation fails.
|
5690
|
+
** memory allocation fails. ^If V is a [pointer value], then the result
|
5691
|
+
** of sqlite3_value_dup(V) is a NULL value.
|
5467
5692
|
**
|
5468
5693
|
** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
|
5469
5694
|
** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
|
@@ -5494,7 +5719,7 @@ SQLITE_API void sqlite3_value_free(sqlite3_value*);
|
|
5494
5719
|
**
|
5495
5720
|
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
|
5496
5721
|
** when first called if N is less than or equal to zero or if a memory
|
5497
|
-
**
|
5722
|
+
** allocation error occurs.
|
5498
5723
|
**
|
5499
5724
|
** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
|
5500
5725
|
** determined by the N parameter on first successful call. Changing the
|
@@ -5699,9 +5924,10 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
5699
5924
|
** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
|
5700
5925
|
** ^SQLite takes the text result from the application from
|
5701
5926
|
** the 2nd parameter of the sqlite3_result_text* interfaces.
|
5702
|
-
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
|
5703
|
-
** is negative, then SQLite
|
5704
|
-
**
|
5927
|
+
** ^If the 3rd parameter to any of the sqlite3_result_text* interfaces
|
5928
|
+
** other than sqlite3_result_text64() is negative, then SQLite computes
|
5929
|
+
** the string length itself by searching the 2nd parameter for the first
|
5930
|
+
** zero character.
|
5705
5931
|
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
|
5706
5932
|
** is non-negative, then as many bytes (not characters) of the text
|
5707
5933
|
** pointed to by the 2nd parameter are taken as the application-defined
|
@@ -6145,6 +6371,28 @@ SQLITE_API int sqlite3_get_autocommit(sqlite3*);
|
|
6145
6371
|
*/
|
6146
6372
|
SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
|
6147
6373
|
|
6374
|
+
/*
|
6375
|
+
** CAPI3REF: Return The Schema Name For A Database Connection
|
6376
|
+
** METHOD: sqlite3
|
6377
|
+
**
|
6378
|
+
** ^The sqlite3_db_name(D,N) interface returns a pointer to the schema name
|
6379
|
+
** for the N-th database on database connection D, or a NULL pointer of N is
|
6380
|
+
** out of range. An N value of 0 means the main database file. An N of 1 is
|
6381
|
+
** the "temp" schema. Larger values of N correspond to various ATTACH-ed
|
6382
|
+
** databases.
|
6383
|
+
**
|
6384
|
+
** Space to hold the string that is returned by sqlite3_db_name() is managed
|
6385
|
+
** by SQLite itself. The string might be deallocated by any operation that
|
6386
|
+
** changes the schema, including [ATTACH] or [DETACH] or calls to
|
6387
|
+
** [sqlite3_serialize()] or [sqlite3_deserialize()], even operations that
|
6388
|
+
** occur on a different thread. Applications that need to
|
6389
|
+
** remember the string long-term should make their own copy. Applications that
|
6390
|
+
** are accessing the same database connection simultaneously on multiple
|
6391
|
+
** threads should mutex-protect calls to this API and should make their own
|
6392
|
+
** private copy of the result prior to releasing the mutex.
|
6393
|
+
*/
|
6394
|
+
SQLITE_API const char *sqlite3_db_name(sqlite3 *db, int N);
|
6395
|
+
|
6148
6396
|
/*
|
6149
6397
|
** CAPI3REF: Return The Filename For A Database Connection
|
6150
6398
|
** METHOD: sqlite3
|
@@ -6175,7 +6423,7 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
|
|
6175
6423
|
** <li> [sqlite3_filename_wal()]
|
6176
6424
|
** </ul>
|
6177
6425
|
*/
|
6178
|
-
SQLITE_API
|
6426
|
+
SQLITE_API sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);
|
6179
6427
|
|
6180
6428
|
/*
|
6181
6429
|
** CAPI3REF: Determine if a database is read-only
|
@@ -6304,6 +6552,72 @@ SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
|
6304
6552
|
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
|
6305
6553
|
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
6306
6554
|
|
6555
|
+
/*
|
6556
|
+
** CAPI3REF: Autovacuum Compaction Amount Callback
|
6557
|
+
** METHOD: sqlite3
|
6558
|
+
**
|
6559
|
+
** ^The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback
|
6560
|
+
** function C that is invoked prior to each autovacuum of the database
|
6561
|
+
** file. ^The callback is passed a copy of the generic data pointer (P),
|
6562
|
+
** the schema-name of the attached database that is being autovacuumed,
|
6563
|
+
** the size of the database file in pages, the number of free pages,
|
6564
|
+
** and the number of bytes per page, respectively. The callback should
|
6565
|
+
** return the number of free pages that should be removed by the
|
6566
|
+
** autovacuum. ^If the callback returns zero, then no autovacuum happens.
|
6567
|
+
** ^If the value returned is greater than or equal to the number of
|
6568
|
+
** free pages, then a complete autovacuum happens.
|
6569
|
+
**
|
6570
|
+
** <p>^If there are multiple ATTACH-ed database files that are being
|
6571
|
+
** modified as part of a transaction commit, then the autovacuum pages
|
6572
|
+
** callback is invoked separately for each file.
|
6573
|
+
**
|
6574
|
+
** <p><b>The callback is not reentrant.</b> The callback function should
|
6575
|
+
** not attempt to invoke any other SQLite interface. If it does, bad
|
6576
|
+
** things may happen, including segmentation faults and corrupt database
|
6577
|
+
** files. The callback function should be a simple function that
|
6578
|
+
** does some arithmetic on its input parameters and returns a result.
|
6579
|
+
**
|
6580
|
+
** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
|
6581
|
+
** destructor for the P parameter. ^If X is not NULL, then X(P) is
|
6582
|
+
** invoked whenever the database connection closes or when the callback
|
6583
|
+
** is overwritten by another invocation of sqlite3_autovacuum_pages().
|
6584
|
+
**
|
6585
|
+
** <p>^There is only one autovacuum pages callback per database connection.
|
6586
|
+
** ^Each call to the sqlite3_autovacuum_pages() interface overrides all
|
6587
|
+
** previous invocations for that database connection. ^If the callback
|
6588
|
+
** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
|
6589
|
+
** then the autovacuum steps callback is cancelled. The return value
|
6590
|
+
** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
|
6591
|
+
** be some other error code if something goes wrong. The current
|
6592
|
+
** implementation will only return SQLITE_OK or SQLITE_MISUSE, but other
|
6593
|
+
** return codes might be added in future releases.
|
6594
|
+
**
|
6595
|
+
** <p>If no autovacuum pages callback is specified (the usual case) or
|
6596
|
+
** a NULL pointer is provided for the callback,
|
6597
|
+
** then the default behavior is to vacuum all free pages. So, in other
|
6598
|
+
** words, the default behavior is the same as if the callback function
|
6599
|
+
** were something like this:
|
6600
|
+
**
|
6601
|
+
** <blockquote><pre>
|
6602
|
+
** unsigned int demonstration_autovac_pages_callback(
|
6603
|
+
** void *pClientData,
|
6604
|
+
** const char *zSchema,
|
6605
|
+
** unsigned int nDbPage,
|
6606
|
+
** unsigned int nFreePage,
|
6607
|
+
** unsigned int nBytePerPage
|
6608
|
+
** ){
|
6609
|
+
** return nFreePage;
|
6610
|
+
** }
|
6611
|
+
** </pre></blockquote>
|
6612
|
+
*/
|
6613
|
+
SQLITE_API int sqlite3_autovacuum_pages(
|
6614
|
+
sqlite3 *db,
|
6615
|
+
unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
|
6616
|
+
void*,
|
6617
|
+
void(*)(void*)
|
6618
|
+
);
|
6619
|
+
|
6620
|
+
|
6307
6621
|
/*
|
6308
6622
|
** CAPI3REF: Data Change Notification Callbacks
|
6309
6623
|
** METHOD: sqlite3
|
@@ -6367,6 +6681,11 @@ SQLITE_API void *sqlite3_update_hook(
|
|
6367
6681
|
** to the same database. Sharing is enabled if the argument is true
|
6368
6682
|
** and disabled if the argument is false.)^
|
6369
6683
|
**
|
6684
|
+
** This interface is omitted if SQLite is compiled with
|
6685
|
+
** [-DSQLITE_OMIT_SHARED_CACHE]. The [-DSQLITE_OMIT_SHARED_CACHE]
|
6686
|
+
** compile-time option is recommended because the
|
6687
|
+
** [use of shared cache mode is discouraged].
|
6688
|
+
**
|
6370
6689
|
** ^Cache sharing is enabled and disabled for an entire process.
|
6371
6690
|
** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
|
6372
6691
|
** In prior versions of SQLite,
|
@@ -6465,7 +6784,7 @@ SQLITE_API int sqlite3_db_release_memory(sqlite3*);
|
|
6465
6784
|
** ^The soft heap limit may not be greater than the hard heap limit.
|
6466
6785
|
** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
|
6467
6786
|
** is invoked with a value of N that is greater than the hard heap limit,
|
6468
|
-
** the
|
6787
|
+
** the soft heap limit is set to the value of the hard heap limit.
|
6469
6788
|
** ^The soft heap limit is automatically enabled whenever the hard heap
|
6470
6789
|
** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
|
6471
6790
|
** the soft heap limit is outside the range of 1..N, then the soft heap
|
@@ -6726,15 +7045,6 @@ SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
|
|
6726
7045
|
*/
|
6727
7046
|
SQLITE_API void sqlite3_reset_auto_extension(void);
|
6728
7047
|
|
6729
|
-
/*
|
6730
|
-
** The interface to the virtual-table mechanism is currently considered
|
6731
|
-
** to be experimental. The interface might change in incompatible ways.
|
6732
|
-
** If this is a problem for you, do not use the interface at this time.
|
6733
|
-
**
|
6734
|
-
** When the virtual-table mechanism stabilizes, we will declare the
|
6735
|
-
** interface fixed, support it indefinitely, and remove this comment.
|
6736
|
-
*/
|
6737
|
-
|
6738
7048
|
/*
|
6739
7049
|
** Structures used by the virtual table interface
|
6740
7050
|
*/
|
@@ -6853,10 +7163,10 @@ struct sqlite3_module {
|
|
6853
7163
|
** when the omit flag is true there is no guarantee that the constraint will
|
6854
7164
|
** not be checked again using byte code.)^
|
6855
7165
|
**
|
6856
|
-
** ^The idxNum and
|
7166
|
+
** ^The idxNum and idxStr values are recorded and passed into the
|
6857
7167
|
** [xFilter] method.
|
6858
|
-
** ^[sqlite3_free()] is used to free
|
6859
|
-
**
|
7168
|
+
** ^[sqlite3_free()] is used to free idxStr if and only if
|
7169
|
+
** needToFreeIdxStr is true.
|
6860
7170
|
**
|
6861
7171
|
** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
|
6862
7172
|
** the correct order to satisfy the ORDER BY clause so that no separate
|
@@ -6945,24 +7255,56 @@ struct sqlite3_index_info {
|
|
6945
7255
|
**
|
6946
7256
|
** These macros define the allowed values for the
|
6947
7257
|
** [sqlite3_index_info].aConstraint[].op field. Each value represents
|
6948
|
-
** an operator that is part of a constraint term in the
|
7258
|
+
** an operator that is part of a constraint term in the WHERE clause of
|
6949
7259
|
** a query that uses a [virtual table].
|
6950
|
-
|
6951
|
-
|
6952
|
-
|
6953
|
-
|
6954
|
-
|
6955
|
-
|
6956
|
-
|
6957
|
-
|
6958
|
-
|
6959
|
-
|
6960
|
-
|
6961
|
-
|
6962
|
-
|
6963
|
-
|
6964
|
-
|
6965
|
-
|
7260
|
+
**
|
7261
|
+
** ^The left-hand operand of the operator is given by the corresponding
|
7262
|
+
** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand
|
7263
|
+
** operand is the rowid.
|
7264
|
+
** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
|
7265
|
+
** operators have no left-hand operand, and so for those operators the
|
7266
|
+
** corresponding aConstraint[].iColumn is meaningless and should not be
|
7267
|
+
** used.
|
7268
|
+
**
|
7269
|
+
** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
|
7270
|
+
** value 255 are reserved to represent functions that are overloaded
|
7271
|
+
** by the [xFindFunction|xFindFunction method] of the virtual table
|
7272
|
+
** implementation.
|
7273
|
+
**
|
7274
|
+
** The right-hand operands for each constraint might be accessible using
|
7275
|
+
** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand
|
7276
|
+
** operand is only available if it appears as a single constant literal
|
7277
|
+
** in the input SQL. If the right-hand operand is another column or an
|
7278
|
+
** expression (even a constant expression) or a parameter, then the
|
7279
|
+
** sqlite3_vtab_rhs_value() probably will not be able to extract it.
|
7280
|
+
** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and
|
7281
|
+
** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
|
7282
|
+
** and hence calls to sqlite3_vtab_rhs_value() for those operators will
|
7283
|
+
** always return SQLITE_NOTFOUND.
|
7284
|
+
**
|
7285
|
+
** The collating sequence to be used for comparison can be found using
|
7286
|
+
** the [sqlite3_vtab_collation()] interface. For most real-world virtual
|
7287
|
+
** tables, the collating sequence of constraints does not matter (for example
|
7288
|
+
** because the constraints are numeric) and so the sqlite3_vtab_collation()
|
7289
|
+
** interface is not commonly needed.
|
7290
|
+
*/
|
7291
|
+
#define SQLITE_INDEX_CONSTRAINT_EQ 2
|
7292
|
+
#define SQLITE_INDEX_CONSTRAINT_GT 4
|
7293
|
+
#define SQLITE_INDEX_CONSTRAINT_LE 8
|
7294
|
+
#define SQLITE_INDEX_CONSTRAINT_LT 16
|
7295
|
+
#define SQLITE_INDEX_CONSTRAINT_GE 32
|
7296
|
+
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
|
7297
|
+
#define SQLITE_INDEX_CONSTRAINT_LIKE 65
|
7298
|
+
#define SQLITE_INDEX_CONSTRAINT_GLOB 66
|
7299
|
+
#define SQLITE_INDEX_CONSTRAINT_REGEXP 67
|
7300
|
+
#define SQLITE_INDEX_CONSTRAINT_NE 68
|
7301
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNOT 69
|
7302
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
|
7303
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNULL 71
|
7304
|
+
#define SQLITE_INDEX_CONSTRAINT_IS 72
|
7305
|
+
#define SQLITE_INDEX_CONSTRAINT_LIMIT 73
|
7306
|
+
#define SQLITE_INDEX_CONSTRAINT_OFFSET 74
|
7307
|
+
#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
|
6966
7308
|
|
6967
7309
|
/*
|
6968
7310
|
** CAPI3REF: Register A Virtual Table Implementation
|
@@ -6991,7 +7333,7 @@ struct sqlite3_index_info {
|
|
6991
7333
|
** destructor.
|
6992
7334
|
**
|
6993
7335
|
** ^If the third parameter (the pointer to the sqlite3_module object) is
|
6994
|
-
** NULL then no new module is
|
7336
|
+
** NULL then no new module is created and any existing modules with the
|
6995
7337
|
** same name are dropped.
|
6996
7338
|
**
|
6997
7339
|
** See also: [sqlite3_drop_modules()]
|
@@ -7103,16 +7445,6 @@ SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
|
7103
7445
|
*/
|
7104
7446
|
SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
|
7105
7447
|
|
7106
|
-
/*
|
7107
|
-
** The interface to the virtual-table mechanism defined above (back up
|
7108
|
-
** to a comment remarkably similar to this one) is currently considered
|
7109
|
-
** to be experimental. The interface might change in incompatible ways.
|
7110
|
-
** If this is a problem for you, do not use the interface at this time.
|
7111
|
-
**
|
7112
|
-
** When the virtual-table mechanism stabilizes, we will declare the
|
7113
|
-
** interface fixed, support it indefinitely, and remove this comment.
|
7114
|
-
*/
|
7115
|
-
|
7116
7448
|
/*
|
7117
7449
|
** CAPI3REF: A Handle To An Open BLOB
|
7118
7450
|
** KEYWORDS: {BLOB handle} {BLOB handles}
|
@@ -7765,7 +8097,10 @@ SQLITE_API int sqlite3_test_control(int op, ...);
|
|
7765
8097
|
#define SQLITE_TESTCTRL_PRNG_SEED 28
|
7766
8098
|
#define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29
|
7767
8099
|
#define SQLITE_TESTCTRL_SEEK_COUNT 30
|
7768
|
-
#define
|
8100
|
+
#define SQLITE_TESTCTRL_TRACEFLAGS 31
|
8101
|
+
#define SQLITE_TESTCTRL_TUNE 32
|
8102
|
+
#define SQLITE_TESTCTRL_LOGEST 33
|
8103
|
+
#define SQLITE_TESTCTRL_LAST 33 /* Largest TESTCTRL */
|
7769
8104
|
|
7770
8105
|
/*
|
7771
8106
|
** CAPI3REF: SQL Keyword Checking
|
@@ -8288,6 +8623,16 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
|
8288
8623
|
** The counter is incremented on the first [sqlite3_step()] call of each
|
8289
8624
|
** cycle.
|
8290
8625
|
**
|
8626
|
+
** [[SQLITE_STMTSTATUS_FILTER_MISS]]
|
8627
|
+
** [[SQLITE_STMTSTATUS_FILTER HIT]]
|
8628
|
+
** <dt>SQLITE_STMTSTATUS_FILTER_HIT<br>
|
8629
|
+
** SQLITE_STMTSTATUS_FILTER_MISS</dt>
|
8630
|
+
** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
|
8631
|
+
** step was bypassed because a Bloom filter returned not-found. The
|
8632
|
+
** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
|
8633
|
+
** times that the Bloom filter returned a find, and thus the join step
|
8634
|
+
** had to be processed as normal.
|
8635
|
+
**
|
8291
8636
|
** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
|
8292
8637
|
** <dd>^This is the approximate number of bytes of heap memory
|
8293
8638
|
** used to store the prepared statement. ^This value is not actually
|
@@ -8302,6 +8647,8 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
|
8302
8647
|
#define SQLITE_STMTSTATUS_VM_STEP 4
|
8303
8648
|
#define SQLITE_STMTSTATUS_REPREPARE 5
|
8304
8649
|
#define SQLITE_STMTSTATUS_RUN 6
|
8650
|
+
#define SQLITE_STMTSTATUS_FILTER_MISS 7
|
8651
|
+
#define SQLITE_STMTSTATUS_FILTER_HIT 8
|
8305
8652
|
#define SQLITE_STMTSTATUS_MEMUSED 99
|
8306
8653
|
|
8307
8654
|
/*
|
@@ -8713,7 +9060,7 @@ typedef struct sqlite3_backup sqlite3_backup;
|
|
8713
9060
|
** if the application incorrectly accesses the destination [database connection]
|
8714
9061
|
** and so no error code is reported, but the operations may malfunction
|
8715
9062
|
** nevertheless. Use of the destination database connection while a
|
8716
|
-
** backup is in progress might also
|
9063
|
+
** backup is in progress might also cause a mutex deadlock.
|
8717
9064
|
**
|
8718
9065
|
** If running in [shared cache mode], the application must
|
8719
9066
|
** guarantee that the shared cache used by the destination database
|
@@ -8965,8 +9312,9 @@ SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
|
|
8965
9312
|
**
|
8966
9313
|
** A single database handle may have at most a single write-ahead log callback
|
8967
9314
|
** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
|
8968
|
-
** previously registered write-ahead log callback. ^
|
8969
|
-
**
|
9315
|
+
** previously registered write-ahead log callback. ^The return value is
|
9316
|
+
** a copy of the third parameter from the previous call, if any, or 0.
|
9317
|
+
** ^Note that the [sqlite3_wal_autocheckpoint()] interface and the
|
8970
9318
|
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
|
8971
9319
|
** overwrite any prior [sqlite3_wal_hook()] settings.
|
8972
9320
|
*/
|
@@ -9140,7 +9488,7 @@ SQLITE_API int sqlite3_wal_checkpoint_v2(
|
|
9140
9488
|
*/
|
9141
9489
|
#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
|
9142
9490
|
#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
|
9143
|
-
#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for
|
9491
|
+
#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */
|
9144
9492
|
#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
|
9145
9493
|
|
9146
9494
|
/*
|
@@ -9269,18 +9617,274 @@ SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
|
|
9269
9617
|
|
9270
9618
|
/*
|
9271
9619
|
** CAPI3REF: Determine The Collation For a Virtual Table Constraint
|
9620
|
+
** METHOD: sqlite3_index_info
|
9272
9621
|
**
|
9273
9622
|
** This function may only be called from within a call to the [xBestIndex]
|
9274
|
-
** method of a [virtual table].
|
9623
|
+
** method of a [virtual table]. This function returns a pointer to a string
|
9624
|
+
** that is the name of the appropriate collation sequence to use for text
|
9625
|
+
** comparisons on the constraint identified by its arguments.
|
9626
|
+
**
|
9627
|
+
** The first argument must be the pointer to the [sqlite3_index_info] object
|
9628
|
+
** that is the first parameter to the xBestIndex() method. The second argument
|
9629
|
+
** must be an index into the aConstraint[] array belonging to the
|
9630
|
+
** sqlite3_index_info structure passed to xBestIndex.
|
9631
|
+
**
|
9632
|
+
** Important:
|
9633
|
+
** The first parameter must be the same pointer that is passed into the
|
9634
|
+
** xBestMethod() method. The first parameter may not be a pointer to a
|
9635
|
+
** different [sqlite3_index_info] object, even an exact copy.
|
9275
9636
|
**
|
9276
|
-
** The
|
9277
|
-
**
|
9278
|
-
**
|
9279
|
-
**
|
9280
|
-
**
|
9281
|
-
**
|
9637
|
+
** The return value is computed as follows:
|
9638
|
+
**
|
9639
|
+
** <ol>
|
9640
|
+
** <li><p> If the constraint comes from a WHERE clause expression that contains
|
9641
|
+
** a [COLLATE operator], then the name of the collation specified by
|
9642
|
+
** that COLLATE operator is returned.
|
9643
|
+
** <li><p> If there is no COLLATE operator, but the column that is the subject
|
9644
|
+
** of the constraint specifies an alternative collating sequence via
|
9645
|
+
** a [COLLATE clause] on the column definition within the CREATE TABLE
|
9646
|
+
** statement that was passed into [sqlite3_declare_vtab()], then the
|
9647
|
+
** name of that alternative collating sequence is returned.
|
9648
|
+
** <li><p> Otherwise, "BINARY" is returned.
|
9649
|
+
** </ol>
|
9650
|
+
*/
|
9651
|
+
SQLITE_API const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
|
9652
|
+
|
9653
|
+
/*
|
9654
|
+
** CAPI3REF: Determine if a virtual table query is DISTINCT
|
9655
|
+
** METHOD: sqlite3_index_info
|
9656
|
+
**
|
9657
|
+
** This API may only be used from within an [xBestIndex|xBestIndex method]
|
9658
|
+
** of a [virtual table] implementation. The result of calling this
|
9659
|
+
** interface from outside of xBestIndex() is undefined and probably harmful.
|
9660
|
+
**
|
9661
|
+
** ^The sqlite3_vtab_distinct() interface returns an integer between 0 and
|
9662
|
+
** 3. The integer returned by sqlite3_vtab_distinct()
|
9663
|
+
** gives the virtual table additional information about how the query
|
9664
|
+
** planner wants the output to be ordered. As long as the virtual table
|
9665
|
+
** can meet the ordering requirements of the query planner, it may set
|
9666
|
+
** the "orderByConsumed" flag.
|
9667
|
+
**
|
9668
|
+
** <ol><li value="0"><p>
|
9669
|
+
** ^If the sqlite3_vtab_distinct() interface returns 0, that means
|
9670
|
+
** that the query planner needs the virtual table to return all rows in the
|
9671
|
+
** sort order defined by the "nOrderBy" and "aOrderBy" fields of the
|
9672
|
+
** [sqlite3_index_info] object. This is the default expectation. If the
|
9673
|
+
** virtual table outputs all rows in sorted order, then it is always safe for
|
9674
|
+
** the xBestIndex method to set the "orderByConsumed" flag, regardless of
|
9675
|
+
** the return value from sqlite3_vtab_distinct().
|
9676
|
+
** <li value="1"><p>
|
9677
|
+
** ^(If the sqlite3_vtab_distinct() interface returns 1, that means
|
9678
|
+
** that the query planner does not need the rows to be returned in sorted order
|
9679
|
+
** as long as all rows with the same values in all columns identified by the
|
9680
|
+
** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
|
9681
|
+
** is doing a GROUP BY.
|
9682
|
+
** <li value="2"><p>
|
9683
|
+
** ^(If the sqlite3_vtab_distinct() interface returns 2, that means
|
9684
|
+
** that the query planner does not need the rows returned in any particular
|
9685
|
+
** order, as long as rows with the same values in all "aOrderBy" columns
|
9686
|
+
** are adjacent.)^ ^(Furthermore, only a single row for each particular
|
9687
|
+
** combination of values in the columns identified by the "aOrderBy" field
|
9688
|
+
** needs to be returned.)^ ^It is always ok for two or more rows with the same
|
9689
|
+
** values in all "aOrderBy" columns to be returned, as long as all such rows
|
9690
|
+
** are adjacent. ^The virtual table may, if it chooses, omit extra rows
|
9691
|
+
** that have the same value for all columns identified by "aOrderBy".
|
9692
|
+
** ^However omitting the extra rows is optional.
|
9693
|
+
** This mode is used for a DISTINCT query.
|
9694
|
+
** <li value="3"><p>
|
9695
|
+
** ^(If the sqlite3_vtab_distinct() interface returns 3, that means
|
9696
|
+
** that the query planner needs only distinct rows but it does need the
|
9697
|
+
** rows to be sorted.)^ ^The virtual table implementation is free to omit
|
9698
|
+
** rows that are identical in all aOrderBy columns, if it wants to, but
|
9699
|
+
** it is not required to omit any rows. This mode is used for queries
|
9700
|
+
** that have both DISTINCT and ORDER BY clauses.
|
9701
|
+
** </ol>
|
9702
|
+
**
|
9703
|
+
** ^For the purposes of comparing virtual table output values to see if the
|
9704
|
+
** values are same value for sorting purposes, two NULL values are considered
|
9705
|
+
** to be the same. In other words, the comparison operator is "IS"
|
9706
|
+
** (or "IS NOT DISTINCT FROM") and not "==".
|
9707
|
+
**
|
9708
|
+
** If a virtual table implementation is unable to meet the requirements
|
9709
|
+
** specified above, then it must not set the "orderByConsumed" flag in the
|
9710
|
+
** [sqlite3_index_info] object or an incorrect answer may result.
|
9711
|
+
**
|
9712
|
+
** ^A virtual table implementation is always free to return rows in any order
|
9713
|
+
** it wants, as long as the "orderByConsumed" flag is not set. ^When the
|
9714
|
+
** the "orderByConsumed" flag is unset, the query planner will add extra
|
9715
|
+
** [bytecode] to ensure that the final results returned by the SQL query are
|
9716
|
+
** ordered correctly. The use of the "orderByConsumed" flag and the
|
9717
|
+
** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
|
9718
|
+
** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
|
9719
|
+
** flag might help queries against a virtual table to run faster. Being
|
9720
|
+
** overly aggressive and setting the "orderByConsumed" flag when it is not
|
9721
|
+
** valid to do so, on the other hand, might cause SQLite to return incorrect
|
9722
|
+
** results.
|
9723
|
+
*/
|
9724
|
+
SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*);
|
9725
|
+
|
9726
|
+
/*
|
9727
|
+
** CAPI3REF: Identify and handle IN constraints in xBestIndex
|
9728
|
+
**
|
9729
|
+
** This interface may only be used from within an
|
9730
|
+
** [xBestIndex|xBestIndex() method] of a [virtual table] implementation.
|
9731
|
+
** The result of invoking this interface from any other context is
|
9732
|
+
** undefined and probably harmful.
|
9733
|
+
**
|
9734
|
+
** ^(A constraint on a virtual table of the form
|
9735
|
+
** "[IN operator|column IN (...)]" is
|
9736
|
+
** communicated to the xBestIndex method as a
|
9737
|
+
** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use
|
9738
|
+
** this constraint, it must set the corresponding
|
9739
|
+
** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under
|
9740
|
+
** the usual mode of handling IN operators, SQLite generates [bytecode]
|
9741
|
+
** that invokes the [xFilter|xFilter() method] once for each value
|
9742
|
+
** on the right-hand side of the IN operator.)^ Thus the virtual table
|
9743
|
+
** only sees a single value from the right-hand side of the IN operator
|
9744
|
+
** at a time.
|
9745
|
+
**
|
9746
|
+
** In some cases, however, it would be advantageous for the virtual
|
9747
|
+
** table to see all values on the right-hand of the IN operator all at
|
9748
|
+
** once. The sqlite3_vtab_in() interfaces facilitates this in two ways:
|
9749
|
+
**
|
9750
|
+
** <ol>
|
9751
|
+
** <li><p>
|
9752
|
+
** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
|
9753
|
+
** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
|
9754
|
+
** is an [IN operator] that can be processed all at once. ^In other words,
|
9755
|
+
** sqlite3_vtab_in() with -1 in the third argument is a mechanism
|
9756
|
+
** by which the virtual table can ask SQLite if all-at-once processing
|
9757
|
+
** of the IN operator is even possible.
|
9758
|
+
**
|
9759
|
+
** <li><p>
|
9760
|
+
** ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
|
9761
|
+
** to SQLite that the virtual table does or does not want to process
|
9762
|
+
** the IN operator all-at-once, respectively. ^Thus when the third
|
9763
|
+
** parameter (F) is non-negative, this interface is the mechanism by
|
9764
|
+
** which the virtual table tells SQLite how it wants to process the
|
9765
|
+
** IN operator.
|
9766
|
+
** </ol>
|
9767
|
+
**
|
9768
|
+
** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
|
9769
|
+
** within the same xBestIndex method call. ^For any given P,N pair,
|
9770
|
+
** the return value from sqlite3_vtab_in(P,N,F) will always be the same
|
9771
|
+
** within the same xBestIndex call. ^If the interface returns true
|
9772
|
+
** (non-zero), that means that the constraint is an IN operator
|
9773
|
+
** that can be processed all-at-once. ^If the constraint is not an IN
|
9774
|
+
** operator or cannot be processed all-at-once, then the interface returns
|
9775
|
+
** false.
|
9776
|
+
**
|
9777
|
+
** ^(All-at-once processing of the IN operator is selected if both of the
|
9778
|
+
** following conditions are met:
|
9779
|
+
**
|
9780
|
+
** <ol>
|
9781
|
+
** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
|
9782
|
+
** integer. This is how the virtual table tells SQLite that it wants to
|
9783
|
+
** use the N-th constraint.
|
9784
|
+
**
|
9785
|
+
** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was
|
9786
|
+
** non-negative had F>=1.
|
9787
|
+
** </ol>)^
|
9788
|
+
**
|
9789
|
+
** ^If either or both of the conditions above are false, then SQLite uses
|
9790
|
+
** the traditional one-at-a-time processing strategy for the IN constraint.
|
9791
|
+
** ^If both conditions are true, then the argvIndex-th parameter to the
|
9792
|
+
** xFilter method will be an [sqlite3_value] that appears to be NULL,
|
9793
|
+
** but which can be passed to [sqlite3_vtab_in_first()] and
|
9794
|
+
** [sqlite3_vtab_in_next()] to find all values on the right-hand side
|
9795
|
+
** of the IN constraint.
|
9282
9796
|
*/
|
9283
|
-
SQLITE_API
|
9797
|
+
SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
|
9798
|
+
|
9799
|
+
/*
|
9800
|
+
** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
|
9801
|
+
**
|
9802
|
+
** These interfaces are only useful from within the
|
9803
|
+
** [xFilter|xFilter() method] of a [virtual table] implementation.
|
9804
|
+
** The result of invoking these interfaces from any other context
|
9805
|
+
** is undefined and probably harmful.
|
9806
|
+
**
|
9807
|
+
** The X parameter in a call to sqlite3_vtab_in_first(X,P) or
|
9808
|
+
** sqlite3_vtab_in_next(X,P) should be one of the parameters to the
|
9809
|
+
** xFilter method which invokes these routines, and specifically
|
9810
|
+
** a parameter that was previously selected for all-at-once IN constraint
|
9811
|
+
** processing use the [sqlite3_vtab_in()] interface in the
|
9812
|
+
** [xBestIndex|xBestIndex method]. ^(If the X parameter is not
|
9813
|
+
** an xFilter argument that was selected for all-at-once IN constraint
|
9814
|
+
** processing, then these routines return [SQLITE_ERROR].)^
|
9815
|
+
**
|
9816
|
+
** ^(Use these routines to access all values on the right-hand side
|
9817
|
+
** of the IN constraint using code like the following:
|
9818
|
+
**
|
9819
|
+
** <blockquote><pre>
|
9820
|
+
** for(rc=sqlite3_vtab_in_first(pList, &pVal);
|
9821
|
+
** rc==SQLITE_OK && pVal;
|
9822
|
+
** rc=sqlite3_vtab_in_next(pList, &pVal)
|
9823
|
+
** ){
|
9824
|
+
** // do something with pVal
|
9825
|
+
** }
|
9826
|
+
** if( rc!=SQLITE_OK ){
|
9827
|
+
** // an error has occurred
|
9828
|
+
** }
|
9829
|
+
** </pre></blockquote>)^
|
9830
|
+
**
|
9831
|
+
** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
|
9832
|
+
** routines return SQLITE_OK and set *P to point to the first or next value
|
9833
|
+
** on the RHS of the IN constraint. ^If there are no more values on the
|
9834
|
+
** right hand side of the IN constraint, then *P is set to NULL and these
|
9835
|
+
** routines return [SQLITE_DONE]. ^The return value might be
|
9836
|
+
** some other value, such as SQLITE_NOMEM, in the event of a malfunction.
|
9837
|
+
**
|
9838
|
+
** The *ppOut values returned by these routines are only valid until the
|
9839
|
+
** next call to either of these routines or until the end of the xFilter
|
9840
|
+
** method from which these routines were called. If the virtual table
|
9841
|
+
** implementation needs to retain the *ppOut values for longer, it must make
|
9842
|
+
** copies. The *ppOut values are [protected sqlite3_value|protected].
|
9843
|
+
*/
|
9844
|
+
SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
|
9845
|
+
SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);
|
9846
|
+
|
9847
|
+
/*
|
9848
|
+
** CAPI3REF: Constraint values in xBestIndex()
|
9849
|
+
** METHOD: sqlite3_index_info
|
9850
|
+
**
|
9851
|
+
** This API may only be used from within the [xBestIndex|xBestIndex method]
|
9852
|
+
** of a [virtual table] implementation. The result of calling this interface
|
9853
|
+
** from outside of an xBestIndex method are undefined and probably harmful.
|
9854
|
+
**
|
9855
|
+
** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
|
9856
|
+
** the [xBestIndex] method of a [virtual table] implementation, with P being
|
9857
|
+
** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and
|
9858
|
+
** J being a 0-based index into P->aConstraint[], then this routine
|
9859
|
+
** attempts to set *V to the value of the right-hand operand of
|
9860
|
+
** that constraint if the right-hand operand is known. ^If the
|
9861
|
+
** right-hand operand is not known, then *V is set to a NULL pointer.
|
9862
|
+
** ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if
|
9863
|
+
** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
|
9864
|
+
** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
|
9865
|
+
** constraint is not available. ^The sqlite3_vtab_rhs_value() interface
|
9866
|
+
** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if
|
9867
|
+
** something goes wrong.
|
9868
|
+
**
|
9869
|
+
** The sqlite3_vtab_rhs_value() interface is usually only successful if
|
9870
|
+
** the right-hand operand of a constraint is a literal value in the original
|
9871
|
+
** SQL statement. If the right-hand operand is an expression or a reference
|
9872
|
+
** to some other column or a [host parameter], then sqlite3_vtab_rhs_value()
|
9873
|
+
** will probably return [SQLITE_NOTFOUND].
|
9874
|
+
**
|
9875
|
+
** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and
|
9876
|
+
** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such
|
9877
|
+
** constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^
|
9878
|
+
**
|
9879
|
+
** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value
|
9880
|
+
** and remains valid for the duration of the xBestIndex method call.
|
9881
|
+
** ^When xBestIndex returns, the sqlite3_value object returned by
|
9882
|
+
** sqlite3_vtab_rhs_value() is automatically deallocated.
|
9883
|
+
**
|
9884
|
+
** The "_rhs_" in the name of this routine is an abbreviation for
|
9885
|
+
** "Right-Hand Side".
|
9886
|
+
*/
|
9887
|
+
SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
|
9284
9888
|
|
9285
9889
|
/*
|
9286
9890
|
** CAPI3REF: Conflict resolution modes
|
@@ -9312,6 +9916,10 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_
|
|
9312
9916
|
** managed by the prepared statement S and will be automatically freed when
|
9313
9917
|
** S is finalized.
|
9314
9918
|
**
|
9919
|
+
** Not all values are available for all query elements. When a value is
|
9920
|
+
** not available, the output variable is set to -1 if the value is numeric,
|
9921
|
+
** or to NULL if it is a string (SQLITE_SCANSTAT_NAME).
|
9922
|
+
**
|
9315
9923
|
** <dl>
|
9316
9924
|
** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
|
9317
9925
|
** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be
|
@@ -9339,12 +9947,24 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_
|
|
9339
9947
|
** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
|
9340
9948
|
** description for the X-th loop.
|
9341
9949
|
**
|
9342
|
-
** [[SQLITE_SCANSTAT_SELECTID]] <dt>
|
9950
|
+
** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECTID</dt>
|
9343
9951
|
** <dd>^The "int" variable pointed to by the V parameter will be set to the
|
9344
|
-
**
|
9345
|
-
**
|
9346
|
-
**
|
9347
|
-
**
|
9952
|
+
** id for the X-th query plan element. The id value is unique within the
|
9953
|
+
** statement. The select-id is the same value as is output in the first
|
9954
|
+
** column of an [EXPLAIN QUERY PLAN] query.
|
9955
|
+
**
|
9956
|
+
** [[SQLITE_SCANSTAT_PARENTID]] <dt>SQLITE_SCANSTAT_PARENTID</dt>
|
9957
|
+
** <dd>The "int" variable pointed to by the V parameter will be set to the
|
9958
|
+
** the id of the parent of the current query element, if applicable, or
|
9959
|
+
** to zero if the query element has no parent. This is the same value as
|
9960
|
+
** returned in the second column of an [EXPLAIN QUERY PLAN] query.
|
9961
|
+
**
|
9962
|
+
** [[SQLITE_SCANSTAT_NCYCLE]] <dt>SQLITE_SCANSTAT_NCYCLE</dt>
|
9963
|
+
** <dd>The sqlite3_int64 output value is set to the number of cycles,
|
9964
|
+
** according to the processor time-stamp counter, that elapsed while the
|
9965
|
+
** query element was being processed. This value is not available for
|
9966
|
+
** all query elements - if it is unavailable the output variable is
|
9967
|
+
** set to -1.
|
9348
9968
|
** </dl>
|
9349
9969
|
*/
|
9350
9970
|
#define SQLITE_SCANSTAT_NLOOP 0
|
@@ -9353,12 +9973,14 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_
|
|
9353
9973
|
#define SQLITE_SCANSTAT_NAME 3
|
9354
9974
|
#define SQLITE_SCANSTAT_EXPLAIN 4
|
9355
9975
|
#define SQLITE_SCANSTAT_SELECTID 5
|
9976
|
+
#define SQLITE_SCANSTAT_PARENTID 6
|
9977
|
+
#define SQLITE_SCANSTAT_NCYCLE 7
|
9356
9978
|
|
9357
9979
|
/*
|
9358
9980
|
** CAPI3REF: Prepared Statement Scan Status
|
9359
9981
|
** METHOD: sqlite3_stmt
|
9360
9982
|
**
|
9361
|
-
**
|
9983
|
+
** These interfaces return information about the predicted and measured
|
9362
9984
|
** performance for pStmt. Advanced applications can use this
|
9363
9985
|
** interface to compare the predicted and the measured performance and
|
9364
9986
|
** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
|
@@ -9369,19 +9991,25 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_
|
|
9369
9991
|
**
|
9370
9992
|
** The "iScanStatusOp" parameter determines which status information to return.
|
9371
9993
|
** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
|
9372
|
-
** of this interface is undefined.
|
9373
|
-
**
|
9374
|
-
**
|
9375
|
-
**
|
9376
|
-
**
|
9377
|
-
**
|
9378
|
-
**
|
9379
|
-
**
|
9380
|
-
**
|
9381
|
-
**
|
9382
|
-
**
|
9383
|
-
**
|
9384
|
-
**
|
9994
|
+
** of this interface is undefined. ^The requested measurement is written into
|
9995
|
+
** a variable pointed to by the "pOut" parameter.
|
9996
|
+
**
|
9997
|
+
** The "flags" parameter must be passed a mask of flags. At present only
|
9998
|
+
** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX
|
9999
|
+
** is specified, then status information is available for all elements
|
10000
|
+
** of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If
|
10001
|
+
** SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements
|
10002
|
+
** that correspond to query loops (the "SCAN..." and "SEARCH..." elements of
|
10003
|
+
** the EXPLAIN QUERY PLAN output) are available. Invoking API
|
10004
|
+
** sqlite3_stmt_scanstatus() is equivalent to calling
|
10005
|
+
** sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.
|
10006
|
+
**
|
10007
|
+
** Parameter "idx" identifies the specific query element to retrieve statistics
|
10008
|
+
** for. Query elements are numbered starting from zero. A value of -1 may be
|
10009
|
+
** to query for statistics regarding the entire query. ^If idx is out of range
|
10010
|
+
** - less than -1 or greater than or equal to the total number of query
|
10011
|
+
** elements used to implement the statement - a non-zero value is returned and
|
10012
|
+
** the variable that pOut points to is unchanged.
|
9385
10013
|
**
|
9386
10014
|
** See also: [sqlite3_stmt_scanstatus_reset()]
|
9387
10015
|
*/
|
@@ -9391,6 +10019,19 @@ SQLITE_API int sqlite3_stmt_scanstatus(
|
|
9391
10019
|
int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
|
9392
10020
|
void *pOut /* Result written here */
|
9393
10021
|
);
|
10022
|
+
SQLITE_API int sqlite3_stmt_scanstatus_v2(
|
10023
|
+
sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
|
10024
|
+
int idx, /* Index of loop to report on */
|
10025
|
+
int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
|
10026
|
+
int flags, /* Mask of flags defined below */
|
10027
|
+
void *pOut /* Result written here */
|
10028
|
+
);
|
10029
|
+
|
10030
|
+
/*
|
10031
|
+
** CAPI3REF: Prepared Statement Scan Status
|
10032
|
+
** KEYWORDS: {scan status flags}
|
10033
|
+
*/
|
10034
|
+
#define SQLITE_SCANSTAT_COMPLEX 0x0001
|
9394
10035
|
|
9395
10036
|
/*
|
9396
10037
|
** CAPI3REF: Zero Scan-Status Counters
|
@@ -9481,6 +10122,10 @@ SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
|
|
9481
10122
|
** function is not defined for operations on WITHOUT ROWID tables, or for
|
9482
10123
|
** DELETE operations on rowid tables.
|
9483
10124
|
**
|
10125
|
+
** ^The sqlite3_preupdate_hook(D,C,P) function returns the P argument from
|
10126
|
+
** the previous call on the same [database connection] D, or NULL for
|
10127
|
+
** the first call on D.
|
10128
|
+
**
|
9484
10129
|
** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
|
9485
10130
|
** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
|
9486
10131
|
** provide additional information about a preupdate event. These routines
|
@@ -9517,6 +10162,15 @@ SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
|
|
9517
10162
|
** triggers; or 2 for changes resulting from triggers called by top-level
|
9518
10163
|
** triggers; and so forth.
|
9519
10164
|
**
|
10165
|
+
** When the [sqlite3_blob_write()] API is used to update a blob column,
|
10166
|
+
** the pre-update hook is invoked with SQLITE_DELETE. This is because the
|
10167
|
+
** in this case the new values are not available. In this case, when a
|
10168
|
+
** callback made with op==SQLITE_DELETE is actuall a write using the
|
10169
|
+
** sqlite3_blob_write() API, the [sqlite3_preupdate_blobwrite()] returns
|
10170
|
+
** the index of the column being written. In other cases, where the
|
10171
|
+
** pre-update hook is being invoked for some other reason, including a
|
10172
|
+
** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.
|
10173
|
+
**
|
9520
10174
|
** See also: [sqlite3_update_hook()]
|
9521
10175
|
*/
|
9522
10176
|
#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
|
@@ -9537,6 +10191,7 @@ SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
|
|
9537
10191
|
SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
|
9538
10192
|
SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
|
9539
10193
|
SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
|
10194
|
+
SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *);
|
9540
10195
|
#endif
|
9541
10196
|
|
9542
10197
|
/*
|
@@ -9775,8 +10430,8 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const c
|
|
9775
10430
|
** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
|
9776
10431
|
** allocation error occurs.
|
9777
10432
|
**
|
9778
|
-
** This interface is
|
9779
|
-
** [
|
10433
|
+
** This interface is omitted if SQLite is compiled with the
|
10434
|
+
** [SQLITE_OMIT_DESERIALIZE] option.
|
9780
10435
|
*/
|
9781
10436
|
SQLITE_API unsigned char *sqlite3_serialize(
|
9782
10437
|
sqlite3 *db, /* The database connection */
|
@@ -9823,12 +10478,16 @@ SQLITE_API unsigned char *sqlite3_serialize(
|
|
9823
10478
|
** database is currently in a read transaction or is involved in a backup
|
9824
10479
|
** operation.
|
9825
10480
|
**
|
10481
|
+
** It is not possible to deserialized into the TEMP database. If the
|
10482
|
+
** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
|
10483
|
+
** function returns SQLITE_ERROR.
|
10484
|
+
**
|
9826
10485
|
** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
|
9827
10486
|
** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
|
9828
10487
|
** [sqlite3_free()] is invoked on argument P prior to returning.
|
9829
10488
|
**
|
9830
|
-
** This interface is
|
9831
|
-
** [
|
10489
|
+
** This interface is omitted if SQLite is compiled with the
|
10490
|
+
** [SQLITE_OMIT_DESERIALIZE] option.
|
9832
10491
|
*/
|
9833
10492
|
SQLITE_API int sqlite3_deserialize(
|
9834
10493
|
sqlite3 *db, /* The database connection */
|
@@ -9872,6 +10531,19 @@ SQLITE_API int sqlite3_deserialize(
|
|
9872
10531
|
# undef double
|
9873
10532
|
#endif
|
9874
10533
|
|
10534
|
+
#if defined(__wasi__)
|
10535
|
+
# undef SQLITE_WASI
|
10536
|
+
# define SQLITE_WASI 1
|
10537
|
+
# undef SQLITE_OMIT_WAL
|
10538
|
+
# define SQLITE_OMIT_WAL 1/* because it requires shared memory APIs */
|
10539
|
+
# ifndef SQLITE_OMIT_LOAD_EXTENSION
|
10540
|
+
# define SQLITE_OMIT_LOAD_EXTENSION
|
10541
|
+
# endif
|
10542
|
+
# ifndef SQLITE_THREADSAFE
|
10543
|
+
# define SQLITE_THREADSAFE 0
|
10544
|
+
# endif
|
10545
|
+
#endif
|
10546
|
+
|
9875
10547
|
#ifdef __cplusplus
|
9876
10548
|
} /* End of the 'extern "C"' block */
|
9877
10549
|
#endif
|
@@ -10077,6 +10749,38 @@ SQLITE_API int sqlite3session_create(
|
|
10077
10749
|
*/
|
10078
10750
|
SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
|
10079
10751
|
|
10752
|
+
/*
|
10753
|
+
** CAPIREF: Conigure a Session Object
|
10754
|
+
** METHOD: sqlite3_session
|
10755
|
+
**
|
10756
|
+
** This method is used to configure a session object after it has been
|
10757
|
+
** created. At present the only valid value for the second parameter is
|
10758
|
+
** [SQLITE_SESSION_OBJCONFIG_SIZE].
|
10759
|
+
**
|
10760
|
+
** Arguments for sqlite3session_object_config()
|
10761
|
+
**
|
10762
|
+
** The following values may passed as the the 4th parameter to
|
10763
|
+
** sqlite3session_object_config().
|
10764
|
+
**
|
10765
|
+
** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>
|
10766
|
+
** This option is used to set, clear or query the flag that enables
|
10767
|
+
** the [sqlite3session_changeset_size()] API. Because it imposes some
|
10768
|
+
** computational overhead, this API is disabled by default. Argument
|
10769
|
+
** pArg must point to a value of type (int). If the value is initially
|
10770
|
+
** 0, then the sqlite3session_changeset_size() API is disabled. If it
|
10771
|
+
** is greater than 0, then the same API is enabled. Or, if the initial
|
10772
|
+
** value is less than zero, no change is made. In all cases the (int)
|
10773
|
+
** variable is set to 1 if the sqlite3session_changeset_size() API is
|
10774
|
+
** enabled following the current call, or 0 otherwise.
|
10775
|
+
**
|
10776
|
+
** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
|
10777
|
+
** the first table has been attached to the session object.
|
10778
|
+
*/
|
10779
|
+
SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
|
10780
|
+
|
10781
|
+
/*
|
10782
|
+
*/
|
10783
|
+
#define SQLITE_SESSION_OBJCONFIG_SIZE 1
|
10080
10784
|
|
10081
10785
|
/*
|
10082
10786
|
** CAPI3REF: Enable Or Disable A Session Object
|
@@ -10321,6 +11025,22 @@ SQLITE_API int sqlite3session_changeset(
|
|
10321
11025
|
void **ppChangeset /* OUT: Buffer containing changeset */
|
10322
11026
|
);
|
10323
11027
|
|
11028
|
+
/*
|
11029
|
+
** CAPI3REF: Return An Upper-limit For The Size Of The Changeset
|
11030
|
+
** METHOD: sqlite3_session
|
11031
|
+
**
|
11032
|
+
** By default, this function always returns 0. For it to return
|
11033
|
+
** a useful result, the sqlite3_session object must have been configured
|
11034
|
+
** to enable this API using sqlite3session_object_config() with the
|
11035
|
+
** SQLITE_SESSION_OBJCONFIG_SIZE verb.
|
11036
|
+
**
|
11037
|
+
** When enabled, this function returns an upper limit, in bytes, for the size
|
11038
|
+
** of the changeset that might be produced if sqlite3session_changeset() were
|
11039
|
+
** called. The final changeset size might be equal to or smaller than the
|
11040
|
+
** size in bytes returned by this function.
|
11041
|
+
*/
|
11042
|
+
SQLITE_API sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);
|
11043
|
+
|
10324
11044
|
/*
|
10325
11045
|
** CAPI3REF: Load The Difference Between Tables Into A Session
|
10326
11046
|
** METHOD: sqlite3_session
|
@@ -10438,6 +11158,14 @@ SQLITE_API int sqlite3session_patchset(
|
|
10438
11158
|
*/
|
10439
11159
|
SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
|
10440
11160
|
|
11161
|
+
/*
|
11162
|
+
** CAPI3REF: Query for the amount of heap memory used by a session object.
|
11163
|
+
**
|
11164
|
+
** This API returns the total amount of heap memory in bytes currently
|
11165
|
+
** used by the session object passed as the only argument.
|
11166
|
+
*/
|
11167
|
+
SQLITE_API sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);
|
11168
|
+
|
10441
11169
|
/*
|
10442
11170
|
** CAPI3REF: Create An Iterator To Traverse A Changeset
|
10443
11171
|
** CONSTRUCTOR: sqlite3_changeset_iter
|
@@ -10540,18 +11268,23 @@ SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
|
|
10540
11268
|
** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
|
10541
11269
|
** is not the case, this function returns [SQLITE_MISUSE].
|
10542
11270
|
**
|
10543
|
-
**
|
10544
|
-
**
|
10545
|
-
**
|
10546
|
-
**
|
10547
|
-
**
|
10548
|
-
**
|
10549
|
-
**
|
11271
|
+
** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three
|
11272
|
+
** outputs are set through these pointers:
|
11273
|
+
**
|
11274
|
+
** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
|
11275
|
+
** depending on the type of change that the iterator currently points to;
|
11276
|
+
**
|
11277
|
+
** *pnCol is set to the number of columns in the table affected by the change; and
|
11278
|
+
**
|
11279
|
+
** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
|
11280
|
+
** the name of the table affected by the current change. The buffer remains
|
11281
|
+
** valid until either sqlite3changeset_next() is called on the iterator
|
11282
|
+
** or until the conflict-handler function returns.
|
11283
|
+
**
|
11284
|
+
** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
|
10550
11285
|
** is an indirect change, or false (0) otherwise. See the documentation for
|
10551
11286
|
** [sqlite3session_indirect()] for a description of direct and indirect
|
10552
|
-
** changes.
|
10553
|
-
** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
|
10554
|
-
** type of change that the iterator currently points to.
|
11287
|
+
** changes.
|
10555
11288
|
**
|
10556
11289
|
** If no error occurs, SQLITE_OK is returned. If an error does occur, an
|
10557
11290
|
** SQLite error code is returned. The values of the output variables may not
|