# page_content

c0: sqlite3_snapshot_cmp()
c2: C API: Compare the ages of two snapshot handles.
c5: c3ref/snapshot_cmp.html
c4:
The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
of two valid snapshot handles.

If the two snapshot handles are not associated with the same database
file, the result of the comparison is undefined.

Additionally, the result of the comparison is only valid if both of the
snapshot handles were obtained by calling sqlite3_snapshot_get() since the
last time the wal file was deleted. The wal file is deleted when the
database is changed back to rollback mode or when the number of database
clients drops to zero. If either snapshot handle was obtained before the
wal file was last deleted, the value returned by this function
is undefined.

Otherwise, this API returns a negative value if P1 refers to an older
snapshot than P2, zero if the two handles refer to the same database
snapshot, and a positive value if P1 is a newer snapshot than P2.

This interface is only available if SQLite is compiled with the
SQLITE_ENABLE_SNAPSHOT option.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_blob_close()
c2: C API: Close A BLOB Handle
c5: c3ref/blob_close.html
c4:
This function closes an open BLOB handle. The BLOB handle is closed
unconditionally.  Even if this routine returns an error code, the
handle is still closed.

If the blob handle being closed was opened for read-write access, and if
the database is in auto-commit mode and there are no other open read-write
blob handles or active write statements, the current transaction is
committed. If an error occurs while committing the transaction, an error
code is returned and the transaction rolled back.

Calling this function with an argument that is not a NULL pointer or an
open blob handle results in undefined behavior. Calling this routine
with a null pointer (such as would be returned by a failed call to
sqlite3_blob_open()) is a harmless no-op. Otherwise, if this function
is passed a valid open blob handle, the values returned by the
sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_limit()
c2: C API: Run-time Limits
c5: c3ref/limit.html
c4:
This interface allows the size of various constructs to be limited
on a connection by connection basis.  The first parameter is the
database connection whose limit is to be set or queried.  The
second parameter is one of the limit categories that define a
class of constructs to be size limited.  The third parameter is the
new limit for that construct.

If the new limit is a negative number, the limit is unchanged.
For each limit category SQLITE_LIMIT_NAME there is a
hard upper bound
set at compile-time by a C preprocessor macro called
SQLITE_MAX_NAME.
(The "_LIMIT_" in the name is changed to "_MAX_".)
Attempts to increase a limit above its hard upper bound are
silently truncated to the hard upper bound.

Regardless of whether or not the limit was changed, the
sqlite3_limit() interface returns the prior value of the limit.
Hence, to find the current value of a limit without changing it,
simply invoke this interface with the third parameter set to -1.

Run-time limits are intended for use in applications that manage
both their own internal database and also databases that are controlled
by untrusted external sources.  An example application might be a
web browser that has its own databases for storing history and
separate databases controlled by JavaScript applications downloaded
off the Internet.  The internal databases can be given the
large, default limits.  Databases managed by external sources can
be given much smaller limits designed to prevent a denial of service
attack.  Developers might also want to use the sqlite3_set_authorizer()
interface to further control untrusted SQL.  The size of the database
created by an untrusted script can be contained using the
max_page_count PRAGMA.

New run-time limit categories may be added in future releases.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_stmt
c2: C API: Prepared Statement Object
c5: c3ref/stmt.html
c4:
An instance of this object represents a single SQL statement that
has been compiled into binary form and is ready to be evaluated.

Think of each SQL statement as a separate computer program.  The
original SQL text is source code.  A prepared statement object
is the compiled object code.  All SQL must be converted into a
prepared statement before it can be run.

The life-cycle of a prepared statement object usually goes like this:


 Create the prepared statement object using sqlite3_prepare_v2().
 Bind values to parameters using the sqlite3_bind_*()
interfaces.
 Run the SQL by calling sqlite3_step() one or more times.
 Reset the prepared statement using sqlite3_reset() then go back
to step 2.  Do this zero or more times.
 Destroy the object using sqlite3_finalize().

6 Constructors using this object:


sqlite3_prepare
sqlite3_prepare16
sqlite3_prepare16_v2
sqlite3_prepare16_v3
sqlite3_prepare_v2
sqlite3_prepare_v3



1 Destructor using this object: sqlite3_finalize()
53 Methods using this object:


sqlite3_bind_blob
sqlite3_bind_blob64
sqlite3_bind_double
sqlite3_bind_int
sqlite3_bind_int64
sqlite3_bind_null
sqlite3_bind_parameter_count
sqlite3_bind_parameter_index
sqlite3_bind_parameter_name
sqlite3_bind_pointer
sqlite3_bind_text
sqlite3_bind_text16
sqlite3_bind_text64
sqlite3_bind_value
sqlite3_bind_zeroblob
sqlite3_bind_zeroblob64
sqlite3_clear_bindings
sqlite3_column_blob
sqlite3_column_bytes
sqlite3_column_bytes16
sqlite3_column_count
sqlite3_column_database_name
sqlite3_column_database_name16
sqlite3_column_decltype
sqlite3_column_decltype16
sqlite3_column_double
sqlite3_column_int
sqlite3_column_int64
sqlite3_column_name
sqlite3_column_name16
sqlite3_column_origin_name
sqlite3_column_origin_name16
sqlite3_column_table_name
sqlite3_column_table_name16
sqlite3_column_text
sqlite3_column_text16
sqlite3_column_type
sqlite3_column_value
sqlite3_data_count
sqlite3_db_handle
sqlite3_expanded_sql
sqlite3_normalized_sql
sqlite3_reset
sqlite3_sql
sqlite3_step
sqlite3_stmt_busy
sqlite3_stmt_explain
sqlite3_stmt_isexplain
sqlite3_stmt_readonly
sqlite3_stmt_scanstatus
sqlite3_stmt_scanstatus_reset
sqlite3_stmt_scanstatus_v2
sqlite3_stmt_status



See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stricmp(), sqlite3_strnicmp()
c2: C API: String Comparison
c5: c3ref/stricmp.html
c4:
The sqlite3_stricmp() and sqlite3_strnicmp() APIs allow applications
and extensions to compare the contents of two buffers containing UTF-8
strings in a case-independent fashion, using the same definition of "case
independence" that SQLite uses internally when comparing identifiers.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_get_auxdata(), sqlite3_set_auxdata()
c2: C API: Function Auxiliary Data
c5: c3ref/get_auxdata.html
c4:
These functions may be used by (non-aggregate) SQL functions to
associate auxiliary data with argument values. If the same argument
value is passed to multiple invocations of the same SQL function during
query execution, under some circumstances the associated auxiliary data
might be preserved.  An example of where this might be useful is in a
regular-expression matching function. The compiled version of the regular
expression can be stored as auxiliary data associated with the pattern string.
Then as long as the pattern string remains the same,
the compiled regular expression can be reused on multiple
invocations of the same function.

The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary data
associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
value to the application-defined function.  N is zero for the left-most
function argument.  If there is no auxiliary data
associated with the function argument, the sqlite3_get_auxdata(C,N) interface
returns a NULL pointer.

The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the
N-th argument of the application-defined function.  Subsequent
calls to sqlite3_get_auxdata(C,N) return P from the most recent
sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
NULL if the auxiliary data has been discarded.
After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
SQLite will invoke the destructor function X with parameter P exactly
once, when the auxiliary data is discarded.
SQLite is free to discard the auxiliary data at any time, including: 
 when the corresponding function parameter changes, or
 when sqlite3_reset() or sqlite3_finalize() is called for the
SQL statement, or
 when sqlite3_set_auxdata() is invoked again on the same
parameter, or
 during the original sqlite3_set_auxdata() call when a memory
allocation error occurs.
 during the original sqlite3_set_auxdata() call if the function
is evaluated during query planning instead of during query execution,
as sometimes happens with SQLITE_ENABLE_STAT4. 

Note the last two bullets in particular.  The destructor X in
sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
should be called near the end of the function implementation and the
function implementation should not make any use of P after
sqlite3_set_auxdata() has been called.  Furthermore, a call to
sqlite3_get_auxdata() that occurs immediately after a corresponding call
to sqlite3_set_auxdata() might still return NULL if an out-of-memory
condition occurred during the sqlite3_set_auxdata() call or if the
function is being evaluated during query planning rather than during
query execution.

In practice, auxiliary data is preserved between function calls for
function parameters that are compile-time constants, including literal
values and parameters and expressions composed from the same.

The value of the N parameter to these interfaces should be non-negative.
Future enhancements may make use of negative N values to define new
kinds of function caching behavior.

These routines must be called from the same thread in which
the SQL function is running.

See also: sqlite3_get_clientdata() and sqlite3_set_clientdata().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_create_filename(), sqlite3_free_filename()
c2: C API: Create and Destroy VFS Filenames
c5: c3ref/create_filename.html
c4:
These interfaces are provided for use by VFS shim implementations and
are not useful outside of that context.

The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
database filename D with corresponding journal file J and WAL file W and
with N URI parameters key/values pairs in the array P.  The result from
sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
is safe to pass to routines like:

 sqlite3_uri_parameter(),
 sqlite3_uri_boolean(),
 sqlite3_uri_int64(),
 sqlite3_uri_key(),
 sqlite3_filename_database(),
 sqlite3_filename_journal(), or
 sqlite3_filename_wal().

If a memory allocation error occurs, sqlite3_create_filename() might
return a NULL pointer.  The memory obtained from sqlite3_create_filename(X)
must be released by a corresponding call to sqlite3_free_filename(Y).

The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
of 2*N pointers to strings.  Each pair of pointers in this array corresponds
to a key and value for a query parameter.  The P parameter may be a NULL
pointer if N is zero.  None of the 2*N pointers in the P array may be
NULL pointers and key pointers should not be empty strings.
None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
be NULL pointers, though they can be empty strings.

The sqlite3_free_filename(Y) routine releases a memory allocation
previously obtained from sqlite3_create_filename().  Invoking
sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.

If the Y parameter to sqlite3_free_filename(Y) is anything other
than a NULL pointer or a pointer previously acquired from
sqlite3_create_filename(), then bad things such as heap
corruption or segfaults may occur. The value Y should not be
used again after sqlite3_free_filename(Y) has been called.  This means
that if the sqlite3_vfs.xOpen() method of a VFS has been called using Y,
then the corresponding [sqlite3_module.xClose() method should also be
invoked prior to calling sqlite3_free_filename(Y).
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_serialize()
c2: C API: Serialize a database
c5: c3ref/serialize.html
c4:
The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
that is a serialization of the S database on database connection D.
If P is not a NULL pointer, then the size of the database in bytes
is written into *P.

For an ordinary on-disk database file, the serialization is just a
copy of the disk file.  For an in-memory database or a "TEMP" database,
the serialization is the same sequence of bytes which would be written
to disk if that database where backed up to disk.

The usual case is that sqlite3_serialize() copies the serialization of
the database into memory obtained from sqlite3_malloc64() and returns
a pointer to that memory.  The caller is responsible for freeing the
returned value to avoid a memory leak.  However, if the F argument
contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
are made, and the sqlite3_serialize() function will return a pointer
to the contiguous memory representation of the database that SQLite
is currently using for that database, or NULL if the no such contiguous
memory representation of the database exists.  A contiguous memory
representation of the database will usually only exist if there has
been a prior call to sqlite3_deserialize(D,S,...) with the same
values of D and S.
The size of the database is written into *P even if the
SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
of the database exists.

After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set,
the returned buffer content will remain accessible and unchanged
until either the next write operation on the connection or when
the connection is closed, and applications must not modify the
buffer. If the bit had been clear, the returned buffer will not
be accessed by SQLite after the call.

A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
allocation error occurs.

This interface is omitted if SQLite is compiled with the
SQLITE_OMIT_DESERIALIZE option.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_randomness()
c2: C API: Pseudo-Random Number Generator
c5: c3ref/randomness.html
c4:
SQLite contains a high-quality pseudo-random number generator (PRNG) used to
select random ROWIDs when inserting new records into a table that
already uses the largest possible ROWID.  The PRNG is also used for
the built-in random() and randomblob() SQL functions.  This interface allows
applications to access the same PRNG for other purposes.

A call to this routine stores N bytes of randomness into buffer P.
The P parameter can be a NULL pointer.

If this routine has not been previously called or if the previous
call had N less than one or a NULL pointer for P, then the PRNG is
seeded using randomness obtained from the xRandomness method of
the default sqlite3_vfs object.
If the previous call to this routine had an N of 1 or more and a
non-NULL P then the pseudo-randomness is generated
internally and without recourse to the sqlite3_vfs xRandomness
method.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Error Codes And Messages
c5: c3ref/errcode.html
c0:
sqlite3_errcode(), sqlite3_extended_errcode(), sqlite3_errmsg(), sqlite3_errmsg16(), sqlite3_errstr(), sqlite3_error_offset()

c4:
If the most recent sqlite3_* API call associated with
database connection D failed, then the sqlite3_errcode(D) interface
returns the numeric result code or extended result code for that
API call.
The sqlite3_extended_errcode()
interface is the same except that it always returns the
extended result code even when extended result codes are
disabled.

The values returned by sqlite3_errcode() and/or
sqlite3_extended_errcode() might change with each API call.
Except, there are some interfaces that are guaranteed to never
change the value of the error code.  The error-code preserving
interfaces include the following:


 sqlite3_errcode()
 sqlite3_extended_errcode()
 sqlite3_errmsg()
 sqlite3_errmsg16()
 sqlite3_error_offset()


The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
text that describes the error, as either UTF-8 or UTF-16 respectively,
or NULL if no error message is available.
(See how SQLite handles invalid UTF for exceptions to this rule.)
Memory to hold the error message string is managed internally.
The application does not need to worry about freeing the result.
However, the error string might be overwritten or deallocated by
subsequent calls to other SQLite interface functions.

The sqlite3_errstr(E) interface returns the English-language text
that describes the result code E, as UTF-8, or NULL if E is not an
result code for which a text error message is available.
Memory to hold the error message string is managed internally
and must not be freed by the application.

If the most recent error references a specific token in the input
SQL, the sqlite3_error_offset() interface returns the byte offset
of the start of that token.  The byte offset returned by
sqlite3_error_offset() assumes that the input SQL is UTF8.
If the most recent error does not reference a specific token in the input
SQL, then the sqlite3_error_offset() function returns -1.

When the serialized threading mode is in use, it might be the
case that a second error occurs on a separate thread in between
the time of the first error and the call to these interfaces.
When that happens, the second error will be reported since these
interfaces always report the most recent result.  To avoid
this, each thread can obtain exclusive use of the database connection D
by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) before beginning
to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) after
all calls to the interfaces listed here are completed.

If an interface fails with SQLITE_MISUSE, that means the interface
was invoked incorrectly by the application.  In that case, the
error code and message may or may not be set.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Binding Values To Prepared Statements
c5: c3ref/bind_blob.html
c0:
sqlite3_bind_blob(), sqlite3_bind_blob64(), sqlite3_bind_double(), sqlite3_bind_int(), sqlite3_bind_int64(), sqlite3_bind_null(), sqlite3_bind_text(), sqlite3_bind_text16(), sqlite3_bind_text64(), sqlite3_bind_value(), sqlite3_bind_pointer(), sqlite3_bind_zeroblob(), sqlite3_bind_zeroblob64()

c4:
In the SQL statement text input to sqlite3_prepare_v2() and its variants,
literals may be replaced by a parameter that matches one of following
templates:


  ?
  ?NNN
  :VVV
  @VVV
  $VVV


In the templates above, NNN represents an integer literal,
and VVV represents an alphanumeric identifier.  The values of these
parameters (also called "host parameter names" or "SQL parameters")
can be set using the sqlite3_bind_*() routines defined here.

The first argument to the sqlite3_bind_*() routines is always
a pointer to the sqlite3_stmt object returned from
sqlite3_prepare_v2() or its variants.

The second argument is the index of the SQL parameter to be set.
The leftmost SQL parameter has an index of 1.  When the same named
SQL parameter is used more than once, second and subsequent
occurrences have the same index as the first occurrence.
The index for named parameters can be looked up using the
sqlite3_bind_parameter_index() API if desired.  The index
for "?NNN" parameters is the value of NNN.
The NNN value must be between 1 and the sqlite3_limit()
parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value: 32766).

The third argument is the value to bind to the parameter.
If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
is ignored and the end result is the same as sqlite3_bind_null().
If the third parameter to sqlite3_bind_text() is not NULL, then
it should be a pointer to well-formed UTF8 text.
If the third parameter to sqlite3_bind_text16() is not NULL, then
it should be a pointer to well-formed UTF16 text.
If the third parameter to sqlite3_bind_text64() is not NULL, then
it should be a pointer to a well-formed unicode string that is
either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
otherwise.


 The byte-order of
UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
found in first character, which is removed, or in the absence of a BOM
the byte order is the native byte order of the host
machine for sqlite3_bind_text16() or the byte order specified in
the 6th parameter for sqlite3_bind_text64().
If UTF16 input text contains invalid unicode
characters, then SQLite might change those invalid characters
into the unicode replacement character: U+FFFD.

In those routines that have a fourth argument, its value is the
number of bytes in the parameter.  To be clear: the value is the
number of bytes in the value, not the number of characters.
If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
is negative, then the length of the string is
the number of bytes up to the first zero terminator.
If the fourth parameter to sqlite3_bind_blob() is negative, then
the behavior is undefined.
If a non-negative fourth parameter is provided to sqlite3_bind_text()
or sqlite3_bind_text16() or sqlite3_bind_text64() then
that parameter must be the byte offset
where the NUL terminator would occur assuming the string were NUL
terminated.  If any NUL characters occurs at byte offsets less than
the value of the fourth parameter then the resulting string value will
contain embedded NULs.  The result of expressions involving strings
with embedded NULs is undefined.

The fifth argument to the BLOB and string binding interfaces controls
or indicates the lifetime of the object referenced by the third parameter.
These three options exist:
 (1) A destructor to dispose of the BLOB or string after SQLite has finished
with it may be passed. It is called to dispose of the BLOB or string even
if the call to the bind API fails, except the destructor is not called if
the third parameter is a NULL pointer or the fourth parameter is negative.
 (2) The special constant, SQLITE_STATIC, may be passed to indicate that
the application remains responsible for disposing of the object. In this
case, the object and the provided pointer to it must remain valid until
either the prepared statement is finalized or the same SQL parameter is
bound to something else, whichever occurs sooner.
 (3) The constant, SQLITE_TRANSIENT, may be passed to indicate that the
object is to be copied prior to the return from sqlite3_bind_*(). The
object and pointer to it must remain valid until then. SQLite will then
manage the lifetime of its private copy.

The sixth argument to sqlite3_bind_text64() must be one of
SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE
to specify the encoding of the text in the third parameter.  If
the sixth argument to sqlite3_bind_text64() is not one of the
allowed values shown above, or if the text encoding is different
from the encoding specified by the sixth parameter, then the behavior
is undefined.

The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
is filled with zeroes.  A zeroblob uses a fixed amount of memory
(just an integer to hold its size) while it is being processed.
Zeroblobs are intended to serve as placeholders for BLOBs whose
content is later written using
incremental BLOB I/O routines.
A negative value for the zeroblob results in a zero-length BLOB.

The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
prepared statement S to have an SQL value of NULL, but to also be
associated with the pointer P of type T.  D is either a NULL pointer or
a pointer to a destructor function for P. SQLite will invoke the
destructor D with a single argument of P when it is finished using
P.  The T parameter should be a static string, preferably a string
literal. The sqlite3_bind_pointer() routine is part of the
pointer passing interface added for SQLite 3.20.0.

If any of the sqlite3_bind_*() routines are called with a NULL pointer
for the prepared statement or with a prepared statement for which
sqlite3_step() has been called more recently than sqlite3_reset(),
then the call will return SQLITE_MISUSE.  If any sqlite3_bind_()
routine is passed a prepared statement that has been finalized, the
result is undefined and probably harmful.

Bindings are not cleared by the sqlite3_reset() routine.
Unbound parameters are interpreted as NULL.

The sqlite3_bind_* routines return SQLITE_OK on success or an
error code if anything goes wrong.
SQLITE_TOOBIG might be returned if the size of a string or BLOB
exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) or
SQLITE_MAX_LENGTH.
SQLITE_RANGE is returned if the parameter
index is out of range.  SQLITE_NOMEM is returned if malloc() fails.

See also: sqlite3_bind_parameter_count(),
sqlite3_bind_parameter_name(), and sqlite3_bind_parameter_index().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_snapshot_open()
c2: C API: Start a read transaction on an historical snapshot
c5: c3ref/snapshot_open.html
c4:
The sqlite3_snapshot_open(D,S,P) interface either starts a new read
transaction or upgrades an existing one for schema S of
database connection D such that the read transaction refers to
historical snapshot P, rather than the most recent change to the
database. The sqlite3_snapshot_open() interface returns SQLITE_OK
on success or an appropriate error code if it fails.

In order to succeed, the database connection must not be in
autocommit mode when sqlite3_snapshot_open(D,S,P) is called. If there
is already a read transaction open on schema S, then the database handle
must have no active statements (SELECT statements that have been passed
to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
SQLITE_ERROR is returned if either of these conditions is violated, or
if schema S does not exist, or if the snapshot object is invalid.

A call to sqlite3_snapshot_open() will fail to open if the specified
snapshot has been overwritten by a checkpoint. In this case
SQLITE_ERROR_SNAPSHOT is returned.

If there is already a read transaction open when this function is
invoked, then the same read transaction remains open (on the same
database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT
is returned. If another error code - for example SQLITE_PROTOCOL or an
SQLITE_IOERR error code - is returned, then the final state of the
read transaction is undefined. If SQLITE_OK is returned, then the
read transaction is now open on database snapshot P.

A call to sqlite3_snapshot_open(D,S,P) will fail if the
database connection D does not know that the database file for
schema S is in WAL mode.  A database connection might not know
that the database file is in WAL mode if there has been no prior
I/O on that database connection, or if the database entered WAL mode
after the most recent I/O on the database connection.
(Hint: Run "PRAGMA application_id" against a newly opened
database connection in order to make it ready to use snapshots.)

The sqlite3_snapshot_open() interface is only available when the
SQLITE_ENABLE_SNAPSHOT compile-time option is used.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_SHM_NLOCK
c2: C API: Maximum xShmLock index
c5: c3ref/c_shm_nlock.html
c4:
The xShmLock method on sqlite3_io_methods may use values
between 0 and this upper bound as its "offset" argument.
The SQLite core will never attempt to acquire or release a
lock outside of this range
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_busy_handler()
c2: C API: Register A Callback To Handle SQLITE_BUSY Errors
c5: c3ref/busy_handler.html
c4:
The sqlite3_busy_handler(D,X,P) routine sets a callback function X
that might be invoked with argument P whenever
an attempt is made to access a database table associated with
database connection D when another thread
or process has the table locked.
The sqlite3_busy_handler() interface is used to implement
sqlite3_busy_timeout() and PRAGMA busy_timeout.

If the busy callback is NULL, then SQLITE_BUSY
is returned immediately upon encountering the lock.  If the busy callback
is not NULL, then the callback might be invoked with two arguments.

The first argument to the busy handler is a copy of the void* pointer which
is the third argument to sqlite3_busy_handler().  The second argument to
the busy handler callback is the number of times that the busy handler has
been invoked previously for the same locking event.  If the
busy callback returns 0, then no additional attempts are made to
access the database and SQLITE_BUSY is returned
to the application.
If the callback returns non-zero, then another attempt
is made to access the database and the cycle repeats.

The presence of a busy handler does not guarantee that it will be invoked
when there is lock contention. If SQLite determines that invoking the busy
handler could result in a deadlock, it will go ahead and return SQLITE_BUSY
to the application instead of invoking the
busy handler.
Consider a scenario where one process is holding a read lock that
it is trying to promote to a reserved lock and
a second process is holding a reserved lock that it is trying
to promote to an exclusive lock.  The first process cannot proceed
because it is blocked by the second and the second process cannot
proceed because it is blocked by the first.  If both processes
invoke the busy handlers, neither will make any progress.  Therefore,
SQLite returns SQLITE_BUSY for the first process, hoping that this
will induce the first process to release its read lock and allow
the second process to proceed.

The default busy callback is NULL.

There can only be a single busy handler defined for each
database connection.  Setting a new busy handler clears any
previously set handler.  Note that calling sqlite3_busy_timeout()
or evaluating PRAGMA busy_timeout=N will change the
busy handler and thus clear any previously set busy handler.

The busy callback should not take any actions which modify the
database connection that invoked the busy handler.  In other words,
the busy handler is not reentrant.  Any such actions
result in undefined behavior.

A busy handler must not close the database connection
or prepared statement that invoked the busy handler.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_mutex
c2: C API: Mutex Handle
c5: c3ref/mutex.html
c4:
The mutex module within SQLite defines sqlite3_mutex to be an
abstract type for a mutex object.  The SQLite core never looks
at the internal representation of an sqlite3_mutex.  It only
deals with pointers to the sqlite3_mutex object.

Mutexes are created using sqlite3_mutex_alloc().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_reset_auto_extension()
c2: C API: Reset Automatic Extension Loading
c5: c3ref/reset_auto_extension.html
c4:
This interface disables all automatic extensions previously
registered using sqlite3_auto_extension().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_auto_extension(), struct sqlite3_api_routines
c2: C API: Automatically Load Statically Linked Extensions
c5: c3ref/auto_extension.html
c4:
This interface causes the xEntryPoint() function to be invoked for
each new database connection that is created.  The idea here is that
xEntryPoint() is the entry point for a statically linked SQLite extension
that is to be automatically loaded into all new database connections.

Even though the function prototype shows that xEntryPoint() takes
no arguments and returns void, SQLite invokes xEntryPoint() with three
arguments and expects an integer result as if the signature of the
entry point where as follows:



If the xEntryPoint routine encounters an error, it should make *pzErrMsg
point to an appropriate error message (obtained from sqlite3_mprintf())
and return an appropriate error code.  SQLite ensures that *pzErrMsg
is NULL before calling the xEntryPoint().  SQLite will invoke
sqlite3_free() on *pzErrMsg after xEntryPoint() returns.  If any
xEntryPoint() returns an error, the sqlite3_open(), sqlite3_open16(),
or sqlite3_open_v2() call that provoked the xEntryPoint() will fail.

Calling sqlite3_auto_extension(X) with an entry point X that is already
on the list of automatic extensions is a harmless no-op. No entry point
will be called more than once for each database connection that is opened.

See also: sqlite3_reset_auto_extension()
and sqlite3_cancel_auto_extension()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_mutex_held(), sqlite3_mutex_notheld()
c2: C API: Mutex Verification Routines
c5: c3ref/mutex_held.html
c4:
The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
are intended for use inside assert() statements.  The SQLite core
never uses these routines except inside an assert() and applications
are advised to follow the lead of the core.  The SQLite core only
provides implementations for these routines when it is compiled
with the SQLITE_DEBUG flag.  External mutex implementations
are only required to provide these routines if SQLITE_DEBUG is
defined and if NDEBUG is not defined.

These routines should return true if the mutex in their argument
is held or not held, respectively, by the calling thread.

The implementation is not required to provide versions of these
routines that actually work. If the implementation does not provide working
versions of these routines, it should at least provide stubs that always
return true so that one does not get spurious assertion failures.

If the argument to sqlite3_mutex_held() is a NULL pointer then
the routine should return 1.   This seems counter-intuitive since
clearly the mutex cannot be held if it does not exist.  But
the reason the mutex does not exist is because the build is not
using mutexes.  And we do not want the assert() containing the
call to sqlite3_mutex_held() to fail, so a non-zero return is
the appropriate thing to do.  The sqlite3_mutex_notheld()
interface should also return 1 when given a NULL pointer.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_wal_checkpoint()
c2: C API: Checkpoint a database
c5: c3ref/wal_checkpoint.html
c4:
The sqlite3_wal_checkpoint(D,X) is equivalent to
sqlite3_wal_checkpoint_v2(D,X,SQLITE_CHECKPOINT_PASSIVE,0,0).

In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
write-ahead log for database X on database connection D to be
transferred into the database file and for the write-ahead log to
be reset.  See the checkpointing documentation for addition
information.

This interface used to be the only way to cause a checkpoint to
occur.  But then the newer and more powerful sqlite3_wal_checkpoint_v2()
interface was added.  This interface is retained for backwards
compatibility and as a convenience for applications that need to manually
start a callback but which do not need the full power (and corresponding
complication) of sqlite3_wal_checkpoint_v2().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_unlock_notify()
c2: C API: Unlock Notification
c5: c3ref/unlock_notify.html
c4:
When running in shared-cache mode, a database operation may fail with
an SQLITE_LOCKED error if the required locks on the shared-cache or
individual tables within the shared-cache cannot be obtained. See
SQLite Shared-Cache Mode for a description of shared-cache locking.
This API may be used to register a callback that SQLite will invoke
when the connection currently holding the required lock relinquishes it.
This API is only available if the library was compiled with the
SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor symbol defined.

See Also: Using the SQLite Unlock Notification Feature.

Shared-cache locks are released when a database connection concludes
its current transaction, either by committing it or rolling it back.

When a connection (known as the blocked connection) fails to obtain a
shared-cache lock and SQLITE_LOCKED is returned to the caller, the
identity of the database connection (the blocking connection) that
has locked the required resource is stored internally. After an
application receives an SQLITE_LOCKED error, it may call the
sqlite3_unlock_notify() method with the blocked connection handle as
the first argument to register for a callback that will be invoked
when the blocking connections current transaction is concluded. The
callback is invoked from within the sqlite3_step or sqlite3_close
call that concludes the blocking connection's transaction.

If sqlite3_unlock_notify() is called in a multi-threaded application,
there is a chance that the blocking connection will have already
concluded its transaction by the time sqlite3_unlock_notify() is invoked.
If this happens, then the specified callback is invoked immediately,
from within the call to sqlite3_unlock_notify().

If the blocked connection is attempting to obtain a write-lock on a
shared-cache table, and more than one other connection currently holds
a read-lock on the same table, then SQLite arbitrarily selects one of
the other connections to use as the blocking connection.

There may be at most one unlock-notify callback registered by a
blocked connection. If sqlite3_unlock_notify() is called when the
blocked connection already has a registered unlock-notify callback,
then the new callback replaces the old. If sqlite3_unlock_notify() is
called with a NULL pointer as its second argument, then any existing
unlock-notify callback is canceled. The blocked connections
unlock-notify callback may also be canceled by closing the blocked
connection using sqlite3_close().

The unlock-notify callback is not reentrant. If an application invokes
any sqlite3_xxx API functions from within an unlock-notify callback, a
crash or deadlock may be the result.

Unless deadlock is detected (see below), sqlite3_unlock_notify() always
returns SQLITE_OK.

Callback Invocation Details

When an unlock-notify callback is registered, the application provides a
single void* pointer that is passed to the callback when it is invoked.
However, the signature of the callback function allows SQLite to pass
it an array of void* context pointers. The first argument passed to
an unlock-notify callback is a pointer to an array of void* pointers,
and the second is the number of entries in the array.

When a blocking connection's transaction is concluded, there may be
more than one blocked connection that has registered for an unlock-notify
callback. If two or more such blocked connections have specified the
same callback function, then instead of invoking the callback function
multiple times, it is invoked once with the set of void* context pointers
specified by the blocked connections bundled together into an array.
This gives the application an opportunity to prioritize any actions
related to the set of unblocked database connections.

Deadlock Detection

Assuming that after registering for an unlock-notify callback a
database waits for the callback to be issued before taking any further
action (a reasonable assumption), then using this API may cause the
application to deadlock. For example, if connection X is waiting for
connection Y's transaction to be concluded, and similarly connection
Y is waiting on connection X's transaction, then neither connection
will proceed and the system may remain deadlocked indefinitely.

To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
detection. If a given call to sqlite3_unlock_notify() would put the
system in a deadlocked state, then SQLITE_LOCKED is returned and no
unlock-notify callback is registered. The system is said to be in
a deadlocked state if connection A has registered for an unlock-notify
callback on the conclusion of connection B's transaction, and connection
B has itself registered for an unlock-notify callback when connection
A's transaction is concluded. Indirect deadlock is also detected, so
the system is also considered to be deadlocked if connection B has
registered for an unlock-notify callback on the conclusion of connection
C's transaction, where connection C is waiting on connection A. Any
number of levels of indirection are allowed.

The "DROP TABLE" Exception

When a call to sqlite3_step() returns SQLITE_LOCKED, it is almost
always appropriate to call sqlite3_unlock_notify(). There is however,
one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
SQLite checks if there are any currently executing SELECT statements
that belong to the same connection. If there are, SQLITE_LOCKED is
returned. In this case there is no "blocking connection", so invoking
sqlite3_unlock_notify() results in the unlock-notify callback being
invoked immediately. If the application then re-attempts the "DROP TABLE"
or "DROP INDEX" query, an infinite loop might be the result.

One way around this problem is to check the extended error code returned
by an sqlite3_step() call. If there is a blocking connection, then the
extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
the special "DROP TABLE/INDEX" case, the extended error code is just
SQLITE_LOCKED.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_blob
c2: C API: A Handle To An Open BLOB
c5: c3ref/blob.html
c4:
An instance of this object represents an open BLOB on which
incremental BLOB I/O can be performed.
Objects of this type are created by sqlite3_blob_open()
and destroyed by sqlite3_blob_close().
The sqlite3_blob_read() and sqlite3_blob_write() interfaces
can be used to read or write small subsections of the BLOB.
The sqlite3_blob_bytes() interface returns the size of the BLOB in bytes.
1 Constructor using this object: sqlite3_blob_open()
1 Destructor using this object: sqlite3_blob_close()
4 Methods using this object:
 sqlite3_blob_bytes(),
sqlite3_blob_read(),
sqlite3_blob_reopen(),
sqlite3_blob_write()
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Mutex Types
c5: c3ref/c_mutex_fast.html
c0:
SQLITE_MUTEX_FAST, SQLITE_MUTEX_RECURSIVE, SQLITE_MUTEX_STATIC_MAIN, SQLITE_MUTEX_STATIC_MEM, SQLITE_MUTEX_STATIC_MEM2, SQLITE_MUTEX_STATIC_OPEN, SQLITE_MUTEX_STATIC_PRNG, SQLITE_MUTEX_STATIC_LRU, SQLITE_MUTEX_STATIC_LRU2, SQLITE_MUTEX_STATIC_PMEM, SQLITE_MUTEX_STATIC_APP1, SQLITE_MUTEX_STATIC_APP2, SQLITE_MUTEX_STATIC_APP3, SQLITE_MUTEX_STATIC_VFS1, SQLITE_MUTEX_STATIC_VFS2, SQLITE_MUTEX_STATIC_VFS3

c4:
The sqlite3_mutex_alloc() interface takes a single argument
which is one of these integer constants.

The set of static mutexes may change from one SQLite release to the
next.  Applications that override the built-in mutex logic must be
prepared to accommodate additional static mutexes.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_collation_needed(), sqlite3_collation_needed16()
c2: C API: Collation Needed Callbacks
c5: c3ref/collation_needed.html
c4:
To avoid having to register all collation sequences before a database
can be used, a single callback function may be registered with the
database connection to be invoked whenever an undefined collation
sequence is required.

If the function is registered using the sqlite3_collation_needed() API,
then it is passed the names of undefined collation sequences as strings
encoded in UTF-8. If sqlite3_collation_needed16() is used,
the names are passed as UTF-16 in machine native byte order.
A call to either function replaces the existing collation-needed callback.

When the callback is invoked, the first argument passed is a copy
of the second argument to sqlite3_collation_needed() or
sqlite3_collation_needed16().  The second argument is the database
connection.  The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE,
or SQLITE_UTF16LE, indicating the most desirable form of the collation
sequence function required.  The fourth parameter is the name of the
required collation sequence.

The callback function should register the desired collation using
sqlite3_create_collation(), sqlite3_create_collation16(), or
sqlite3_create_collation_v2().
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: 64-Bit Integer Types
c5: c3ref/int64.html
c4:
Because there is no cross-platform way to specify 64-bit integer types
SQLite includes typedefs for 64-bit signed and unsigned integers.

The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
The sqlite_int64 and sqlite_uint64 types are supported for backwards
compatibility only.

The sqlite3_int64 and sqlite_int64 types can store integer values
between -9223372036854775808 and +9223372036854775807 inclusive.  The
sqlite3_uint64 and sqlite_uint64 types can store integer values
between 0 and +18446744073709551615 inclusive.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Run-Time Limit Categories
c5: c3ref/c_limit_attached.html
c0:
SQLITE_LIMIT_LENGTH, SQLITE_LIMIT_SQL_LENGTH, SQLITE_LIMIT_COLUMN, SQLITE_LIMIT_EXPR_DEPTH, SQLITE_LIMIT_COMPOUND_SELECT, SQLITE_LIMIT_VDBE_OP, SQLITE_LIMIT_FUNCTION_ARG, SQLITE_LIMIT_ATTACHED, SQLITE_LIMIT_LIKE_PATTERN_LENGTH, SQLITE_LIMIT_VARIABLE_NUMBER, SQLITE_LIMIT_TRIGGER_DEPTH, SQLITE_LIMIT_WORKER_THREADS

c4:
These constants define various performance limits
that can be lowered at run-time using sqlite3_limit().
The synopsis of the meanings of the various limits is shown below.
Additional information is available at Limits in SQLite.



 SQLITE_LIMIT_LENGTH
The maximum size of any string or BLOB or table row, in bytes.


 SQLITE_LIMIT_SQL_LENGTH
The maximum length of an SQL statement, in bytes.


 SQLITE_LIMIT_COLUMN
The maximum number of columns in a table definition or in the
result set of a SELECT or the maximum number of columns in an index
or in an ORDER BY or GROUP BY clause.


 SQLITE_LIMIT_EXPR_DEPTH
The maximum depth of the parse tree on any expression.


 SQLITE_LIMIT_COMPOUND_SELECT
The maximum number of terms in a compound SELECT statement.


 SQLITE_LIMIT_VDBE_OP
The maximum number of instructions in a virtual machine program
used to implement an SQL statement.  If sqlite3_prepare_v2() or
the equivalent tries to allocate space for more than this many opcodes
in a single prepared statement, an SQLITE_NOMEM error is returned.


 SQLITE_LIMIT_FUNCTION_ARG
The maximum number of arguments on a function.


 SQLITE_LIMIT_ATTACHED
The maximum number of attached databases.



SQLITE_LIMIT_LIKE_PATTERN_LENGTH
The maximum length of the pattern argument to the LIKE or
GLOB operators.



SQLITE_LIMIT_VARIABLE_NUMBER
The maximum index number of any parameter in an SQL statement.


 SQLITE_LIMIT_TRIGGER_DEPTH
The maximum depth of recursion for triggers.


 SQLITE_LIMIT_WORKER_THREADS
The maximum number of auxiliary worker threads that a single
prepared statement may start.

See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_wal_hook()
c2: C API: Write-Ahead Log Commit Hook
c5: c3ref/wal_hook.html
c4:
The sqlite3_wal_hook() function is used to register a callback that
is invoked each time data is committed to a database in wal mode.

The callback is invoked by SQLite after the commit has taken place and
the associated write-lock on the database released, so the implementation
may read, write or checkpoint the database as required.

The first parameter passed to the callback function when it is invoked
is a copy of the third parameter passed to sqlite3_wal_hook() when
registering the callback. The second is a copy of the database handle.
The third parameter is the name of the database that was written to -
either "main" or the name of an ATTACH-ed database. The fourth parameter
is the number of pages currently in the write-ahead log file,
including those that were just committed.

The callback function should normally return SQLITE_OK.  If an error
code is returned, that error will propagate back up through the
SQLite code base to cause the statement that provoked the callback
to report an error, though the commit will have still occurred. If the
callback returns SQLITE_ROW or SQLITE_DONE, or if it returns a value
that does not correspond to any valid SQLite error code, the results
are undefined.

A single database handle may have at most a single write-ahead log callback
registered at one time. Calling sqlite3_wal_hook() replaces any
previously registered write-ahead log callback. The return value is
a copy of the third parameter from the previous call, if any, or 0.
Note that the sqlite3_wal_autocheckpoint() interface and the
wal_autocheckpoint pragma both invoke sqlite3_wal_hook() and will
overwrite any prior sqlite3_wal_hook() settings.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stmt_explain()
c2: C API: Change The EXPLAIN Setting For A Prepared Statement
c5: c3ref/stmt_explain.html
c4:
The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN
setting for prepared statement S.  If E is zero, then S becomes
a normal prepared statement.  If E is 1, then S behaves as if
its SQL text began with "EXPLAIN".  If E is 2, then S behaves as if
its SQL text began with "EXPLAIN QUERY PLAN".

Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.
SQLite tries to avoid a reprepare, but a reprepare might be necessary
on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.

Because of the potential need to reprepare, a call to
sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be
reprepared because it was created using sqlite3_prepare() instead of
the newer sqlite3_prepare_v2() or sqlite3_prepare_v3() interfaces and
hence has no saved SQL text with which to reprepare.

Changing the explain setting for a prepared statement does not change
the original SQL text for the statement.  Hence, if the SQL text originally
began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0)
is called to convert the statement into an ordinary statement, the EXPLAIN
or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S)
output, even though the statement now acts like a normal SQL statement.

This routine returns SQLITE_OK if the explain mode is successfully
changed, or an error code if the explain mode could not be changed.
The explain mode cannot be changed while a statement is active.
Hence, it is good practice to call sqlite3_reset(S)
immediately prior to calling sqlite3_stmt_explain(S,E).
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_total_changes(), sqlite3_total_changes64()
c2: C API: Total Number Of Rows Modified
c5: c3ref/total_changes.html
c4:
These functions return the total number of rows inserted, modified or
deleted by all INSERT, UPDATE or DELETE statements completed
since the database connection was opened, including those executed as
part of trigger programs. The two functions are identical except for the
type of the return value and that if the number of rows modified by the
connection exceeds the maximum value supported by type "int", then
the return value of sqlite3_total_changes() is undefined. Executing
any other type of SQL statement does not affect the value returned by
sqlite3_total_changes().

Changes made as part of foreign key actions are included in the
count, but those made as part of REPLACE constraint resolution are
not. Changes to a view that are intercepted by INSTEAD OF triggers
are not counted.

The sqlite3_total_changes(D) interface only reports the number
of rows that changed due to SQL statement run against database
connection D.  Any changes by other database connections are ignored.
To detect changes against a database file from other database
connections use the PRAGMA data_version command or the
SQLITE_FCNTL_DATA_VERSION file control.

If a separate thread makes changes on the same database connection
while sqlite3_total_changes() is running then the value
returned is unpredictable and not meaningful.

See also:

 the sqlite3_changes() interface
 the count_changes pragma
 the changes() SQL function
 the data_version pragma
 the SQLITE_FCNTL_DATA_VERSION file control

See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Create Or Redefine SQL Functions
c5: c3ref/create_function.html
c0:
sqlite3_create_function(), sqlite3_create_function16(), sqlite3_create_function_v2(), sqlite3_create_window_function()

c4:
These functions (collectively known as "function creation routines")
are used to add SQL functions or aggregates or to redefine the behavior
of existing SQL functions or aggregates. The only differences between
the three "sqlite3_create_function*" routines are the text encoding
expected for the second parameter (the name of the function being
created) and the presence or absence of a destructor callback for
the application data pointer. Function sqlite3_create_window_function()
is similar, but allows the user to supply the extra callback functions
needed by aggregate window functions.

The first parameter is the database connection to which the SQL
function is to be added.  If an application uses more than one database
connection then application-defined SQL functions must be added
to each database connection separately.

The second parameter is the name of the SQL function to be created or
redefined.  The length of the name is limited to 255 bytes in a UTF-8
representation, exclusive of the zero-terminator.  Note that the name
length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
Any attempt to create a function with a longer name
will result in SQLITE_MISUSE being returned.

The third parameter (nArg)
is the number of arguments that the SQL function or
aggregate takes. If this parameter is -1, then the SQL function or
aggregate may take any number of arguments between 0 and the limit
set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG).  If the third
parameter is less than -1 or greater than 127 then the behavior is
undefined.

The fourth parameter, eTextRep, specifies what
text encoding this SQL function prefers for
its parameters.  The application should set this parameter to
SQLITE_UTF16LE if the function implementation invokes
sqlite3_value_text16le() on an input, or SQLITE_UTF16BE if the
implementation invokes sqlite3_value_text16be() on an input, or
SQLITE_UTF16 if sqlite3_value_text16() is used, or SQLITE_UTF8
otherwise.  The same SQL function may be registered multiple times using
different preferred text encodings, with different implementations for
each encoding.
When multiple implementations of the same function are available, SQLite
will pick the one that involves the least amount of data conversion.

The fourth parameter may optionally be ORed with SQLITE_DETERMINISTIC
to signal that the function will always return the same result given
the same inputs within a single SQL statement.  Most SQL functions are
deterministic.  The built-in random() SQL function is an example of a
function that is not deterministic.  The SQLite query planner is able to
perform additional optimizations on deterministic functions, so use
of the SQLITE_DETERMINISTIC flag is recommended where possible.

The fourth parameter may also optionally include the SQLITE_DIRECTONLY
flag, which if present prevents the function from being invoked from
within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
index expressions, or the WHERE clause of partial indexes.

For best security, the SQLITE_DIRECTONLY flag is recommended for
all application-defined SQL functions that do not need to be
used inside of triggers, view, CHECK constraints, or other elements of
the database schema.  This flags is especially recommended for SQL
functions that have side effects or reveal internal application state.
Without this flag, an attacker might be able to modify the schema of
a database file to include invocations of the function with parameters
chosen by the attacker, which the application will then execute when
the database file is opened and read.

The fifth parameter is an arbitrary pointer.  The implementation of the
function can gain access to this pointer using sqlite3_user_data().

The sixth, seventh and eighth parameters passed to the three
"sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
pointers to C-language functions that implement the SQL function or
aggregate. A scalar SQL function requires an implementation of the xFunc
callback only; NULL pointers must be passed as the xStep and xFinal
parameters. An aggregate SQL function requires an implementation of xStep
and xFinal and NULL pointer must be passed for xFunc. To delete an existing
SQL function or aggregate, pass NULL pointers for all three function
callbacks.

The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
and xInverse) passed to sqlite3_create_window_function are pointers to
C-language callbacks that implement the new function. xStep and xFinal
must both be non-NULL. xValue and xInverse may either both be NULL, in
which case a regular aggregate function is created, or must both be
non-NULL, in which case the new function may be used as either an aggregate
or aggregate window function. More details regarding the implementation
of aggregate window functions are
available here.

If the final parameter to sqlite3_create_function_v2() or
sqlite3_create_window_function() is not NULL, then it is destructor for
the application data pointer. The destructor is invoked when the function
is deleted, either by being overloaded or when the database connection
closes. The destructor is also invoked if the call to
sqlite3_create_function_v2() fails.  When the destructor callback is
invoked, it is passed a single argument which is a copy of the application
data pointer which was the fifth parameter to sqlite3_create_function_v2().

It is permitted to register multiple implementations of the same
functions with the same name but with either differing numbers of
arguments or differing preferred text encodings.  SQLite will use
the implementation that most closely matches the way in which the
SQL function is used.  A function implementation with a non-negative
nArg parameter is a better match than a function implementation with
a negative nArg.  A function where the preferred text encoding
matches the database encoding is a better
match than a function where the encoding is different.
A function where the encoding difference is between UTF16le and UTF16be
is a closer match than a function where the encoding difference is
between UTF8 and UTF16.

Built-in functions may be overloaded by new application-defined functions.

An application-defined function is permitted to call other
SQLite interfaces.  However, such calls must not
close the database connection nor finalize or reset the prepared
statement in which the function is running.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_set_authorizer()
c2: C API: Compile-Time Authorization Callbacks
c5: c3ref/set_authorizer.html
c4:
This routine registers an authorizer callback with a particular
database connection, supplied in the first argument.
The authorizer callback is invoked as SQL statements are being compiled
by sqlite3_prepare() or its variants sqlite3_prepare_v2(),
sqlite3_prepare_v3(), sqlite3_prepare16(), sqlite3_prepare16_v2(),
and sqlite3_prepare16_v3().  At various
points during the compilation process, as logic is being created
to perform various actions, the authorizer callback is invoked to
see if those actions are allowed.  The authorizer callback should
return SQLITE_OK to allow the action, SQLITE_IGNORE to disallow the
specific action but allow the SQL statement to continue to be
compiled, or SQLITE_DENY to cause the entire SQL statement to be
rejected with an error.  If the authorizer callback returns
any value other than SQLITE_IGNORE, SQLITE_OK, or SQLITE_DENY
then the sqlite3_prepare_v2() or equivalent call that triggered
the authorizer will fail with an error message.

When the callback returns SQLITE_OK, that means the operation
requested is ok.  When the callback returns SQLITE_DENY, the
sqlite3_prepare_v2() or equivalent call that triggered the
authorizer will fail with an error message explaining that
access is denied.

The first parameter to the authorizer callback is a copy of the third
parameter to the sqlite3_set_authorizer() interface. The second parameter
to the callback is an integer action code that specifies
the particular action to be authorized. The third through sixth parameters
to the callback are either NULL pointers or zero-terminated strings
that contain additional details about the action to be authorized.
Applications must always be prepared to encounter a NULL pointer in any
of the third through the sixth parameters of the authorization callback.

If the action code is SQLITE_READ
and the callback returns SQLITE_IGNORE then the
prepared statement statement is constructed to substitute
a NULL value in place of the table column that would have
been read if SQLITE_OK had been returned.  The SQLITE_IGNORE
return can be used to deny an untrusted user access to individual
columns of a table.
When a table is referenced by a SELECT but no column values are
extracted from that table (for example in a query like
"SELECT count(*) FROM tab") then the SQLITE_READ authorizer callback
is invoked once for that table with a column name that is an empty string.
If the action code is SQLITE_DELETE and the callback returns
SQLITE_IGNORE then the DELETE operation proceeds but the
truncate optimization is disabled and all rows are deleted individually.

An authorizer is used when preparing
SQL statements from an untrusted source, to ensure that the SQL statements
do not try to access data they are not allowed to see, or that they do not
try to execute malicious statements that damage the database.  For
example, an application may allow a user to enter arbitrary
SQL queries for evaluation by a database.  But the application does
not want the user to be able to make arbitrary changes to the
database.  An authorizer could then be put in place while the
user-entered SQL is being prepared that
disallows everything except SELECT statements.

Applications that need to process SQL from untrusted sources
might also consider lowering resource limits using sqlite3_limit()
and limiting database size using the max_page_count PRAGMA
in addition to using an authorizer.

Only a single authorizer can be in place on a database connection
at a time.  Each call to sqlite3_set_authorizer overrides the
previous call.  Disable the authorizer by installing a NULL callback.
The authorizer is disabled by default.

The authorizer callback must not do anything that will modify
the database connection that invoked the authorizer callback.
Note that sqlite3_prepare_v2() and sqlite3_step() both modify their
database connections for the meaning of "modify" in this paragraph.

When sqlite3_prepare_v2() is used to prepare a statement, the
statement might be re-prepared during sqlite3_step() due to a
schema change.  Hence, the application should ensure that the
correct authorizer callback remains in place during the sqlite3_step().

Note that the authorizer callback is invoked only during
sqlite3_prepare() or its variants.  Authorization is not
performed during statement evaluation in sqlite3_step(), unless
as stated in the previous paragraph, sqlite3_step() invokes
sqlite3_prepare_v2() to reprepare a statement after a schema change.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_deserialize()
c2: C API: Deserialize a database
c5: c3ref/deserialize.html
c4:
The sqlite3_deserialize(D,S,P,N,M,F) interface causes the
database connection D to disconnect from database S and then
reopen S as an in-memory database based on the serialization contained
in P.  The serialized database P is N bytes in size.  M is the size of
the buffer P, which might be larger than N.  If M is larger than N, and
the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
permitted to add content to the in-memory database as long as the total
size does not exceed M bytes.

If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
invoke sqlite3_free() on the serialization buffer when the database
connection closes.  If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
SQLite will try to increase the buffer size using sqlite3_realloc64()
if writes on the database cause it to grow larger than M bytes.

Applications must not modify the buffer P or invalidate it before
the database connection D is closed.

The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
database is currently in a read transaction or is involved in a backup
operation.

It is not possible to deserialized into the TEMP database.  If the
S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
function returns SQLITE_ERROR.

The deserialized database should not be in WAL mode.  If the database
is in WAL mode, then any attempt to use the database file will result
in an SQLITE_CANTOPEN error.  The application can set the
file format version numbers (bytes 18 and 19) of the input database P
to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the
database file into rollback mode and work around this limitation.

If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
sqlite3_free() is invoked on argument P prior to returning.

This interface is omitted if SQLite is compiled with the
SQLITE_OMIT_DESERIALIZE option.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: The pre-update hook.
c5: c3ref/preupdate_blobwrite.html
c0:
sqlite3_preupdate_hook(), sqlite3_preupdate_old(), sqlite3_preupdate_count(), sqlite3_preupdate_depth(), sqlite3_preupdate_new(), sqlite3_preupdate_blobwrite()

c4:
These interfaces are only available if SQLite is compiled using the
SQLITE_ENABLE_PREUPDATE_HOOK compile-time option.

The sqlite3_preupdate_hook() interface registers a callback function
that is invoked prior to each INSERT, UPDATE, and DELETE operation
on a database table.
At most one preupdate hook may be registered at a time on a single
database connection; each call to sqlite3_preupdate_hook() overrides
the previous setting.
The preupdate hook is disabled by invoking sqlite3_preupdate_hook()
with a NULL pointer as the second parameter.
The third parameter to sqlite3_preupdate_hook() is passed through as
the first parameter to callbacks.

The preupdate hook only fires for changes to real database tables; the
preupdate hook is not invoked for changes to virtual tables or to
system tables like sqlite_sequence or sqlite_stat1.

The second parameter to the preupdate callback is a pointer to
the database connection that registered the preupdate hook.
The third parameter to the preupdate callback is one of the constants
SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE to identify the
kind of update operation that is about to occur.
The fourth parameter to the preupdate callback is the name of the
database within the database connection that is being modified.  This
will be "main" for the main database or "temp" for TEMP tables or
the name given after the AS keyword in the ATTACH statement for attached
databases.
The fifth parameter to the preupdate callback is the name of the
table that is being modified.

For an UPDATE or DELETE operation on a rowid table, the sixth
parameter passed to the preupdate callback is the initial rowid of the
row being modified or deleted. For an INSERT operation on a rowid table,
or any operation on a WITHOUT ROWID table, the value of the sixth
parameter is undefined. For an INSERT or UPDATE on a rowid table the
seventh parameter is the final rowid value of the row being inserted
or updated. The value of the seventh parameter passed to the callback
function is not defined for operations on WITHOUT ROWID tables, or for
DELETE operations on rowid tables.

The sqlite3_preupdate_hook(D,C,P) function returns the P argument from
the previous call on the same database connection D, or NULL for
the first call on D.

The sqlite3_preupdate_old(), sqlite3_preupdate_new(),
sqlite3_preupdate_count(), and sqlite3_preupdate_depth() interfaces
provide additional information about a preupdate event. These routines
may only be called from within a preupdate callback.  Invoking any of
these routines from outside of a preupdate callback or with a
database connection pointer that is different from the one supplied
to the preupdate callback results in undefined and probably undesirable
behavior.

The sqlite3_preupdate_count(D) interface returns the number of columns
in the row that is being inserted, updated, or deleted.

The sqlite3_preupdate_old(D,N,P) interface writes into P a pointer to
a protected sqlite3_value that contains the value of the Nth column of
the table row before it is updated.  The N parameter must be between 0
and one less than the number of columns or the behavior will be
undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
behavior is undefined.  The sqlite3_value that P points to
will be destroyed when the preupdate callback returns.

The sqlite3_preupdate_new(D,N,P) interface writes into P a pointer to
a protected sqlite3_value that contains the value of the Nth column of
the table row after it is updated.  The N parameter must be between 0
and one less than the number of columns or the behavior will be
undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
behavior is undefined.  The sqlite3_value that P points to
will be destroyed when the preupdate callback returns.

The sqlite3_preupdate_depth(D) interface returns 0 if the preupdate
callback was invoked as a result of a direct insert, update, or delete
operation; or 1 for inserts, updates, or deletes invoked by top-level
triggers; or 2 for changes resulting from triggers called by top-level
triggers; and so forth.

When the sqlite3_blob_write() API is used to update a blob column,
the pre-update hook is invoked with SQLITE_DELETE. This is because the
in this case the new values are not available. In this case, when a
callback made with op==SQLITE_DELETE is actually a write using the
sqlite3_blob_write() API, the sqlite3_preupdate_blobwrite() returns
the index of the column being written. In other cases, where the
pre-update hook is being invoked for some other reason, including a
regular DELETE, sqlite3_preupdate_blobwrite() returns -1.

See also:  sqlite3_update_hook()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_TRACE_STMT, SQLITE_TRACE_PROFILE, SQLITE_TRACE_ROW, SQLITE_TRACE_CLOSE
c2: C API: SQL Trace Event Codes
c5: c3ref/c_trace.html
c4:
These constants identify classes of events that can be monitored
using the sqlite3_trace_v2() tracing logic.  The M argument
to sqlite3_trace_v2(D,M,X,P) is an OR-ed combination of one or more of
the following constants.  The first argument to the trace callback
is one of the following constants.

New tracing constants may be added in future releases.

A trace callback has four arguments: xCallback(T,C,P,X).
The T argument is one of the integer type codes above.
The C argument is a copy of the context pointer passed in as the
fourth argument to sqlite3_trace_v2().
The P and X arguments are pointers whose meanings depend on T.



 SQLITE_TRACE_STMT
An SQLITE_TRACE_STMT callback is invoked when a prepared statement
first begins running and possibly at other times during the
execution of the prepared statement, such as at the start of each
trigger subprogram. The P argument is a pointer to the
prepared statement. The X argument is a pointer to a string which
is the unexpanded SQL text of the prepared statement or an SQL comment
that indicates the invocation of a trigger.  The callback can compute
the same text that would have been returned by the legacy sqlite3_trace()
interface by using the X argument when X begins with "--" and invoking
sqlite3_expanded_sql(P) otherwise.


 SQLITE_TRACE_PROFILE
An SQLITE_TRACE_PROFILE callback provides approximately the same
information as is provided by the sqlite3_profile() callback.
The P argument is a pointer to the prepared statement and the
X argument points to a 64-bit integer which is approximately
the number of nanoseconds that the prepared statement took to run.
The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.


 SQLITE_TRACE_ROW
An SQLITE_TRACE_ROW callback is invoked whenever a prepared
statement generates a single row of result.
The P argument is a pointer to the prepared statement and the
X argument is unused.


 SQLITE_TRACE_CLOSE
An SQLITE_TRACE_CLOSE callback is invoked when a database
connection closes.
The P argument is a pointer to the database connection object
and the X argument is unused.

See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Name Of The Folder Holding Temporary Files
c5: c3ref/temp_directory.html
c4:
If this global variable is made to point to a string which is
the name of a folder (a.k.a. directory), then all temporary files
created by SQLite when using a built-in VFS
will be placed in that directory.  If this variable
is a NULL pointer, then SQLite performs a search for an appropriate
temporary file directory.

Applications are strongly discouraged from using this global variable.
It is required to set a temporary folder on Windows Runtime (WinRT).
But for all other platforms, it is highly recommended that applications
neither read nor write this variable.  This global variable is a relic
that exists for backwards compatibility of legacy applications and should
be avoided in new projects.

It is not safe to read or modify this variable in more than one
thread at a time.  It is not safe to read or modify this variable
if a database connection is being used at the same time in a separate
thread.
It is intended that this variable be set once
as part of process initialization and before any SQLite interface
routines have been called and that this variable remain unchanged
thereafter.

The temp_store_directory pragma may modify this variable and cause
it to point to memory obtained from sqlite3_malloc.  Furthermore,
the temp_store_directory pragma always assumes that any string
that this variable points to is held in memory obtained from
sqlite3_malloc and the pragma may attempt to free that memory
using sqlite3_free.
Hence, if this variable is modified directly, either it should be
made NULL or made to point to memory obtained from sqlite3_malloc
or else the use of the temp_store_directory pragma should be avoided.
Except when requested by the temp_store_directory pragma, SQLite
does not free the memory that sqlite3_temp_directory points to.  If
the application wants that memory to be freed, it must do
so itself, taking care to only do so after all database connection
objects have been destroyed.

Note to Windows Runtime users:  The temporary directory must be set
prior to calling sqlite3_open or sqlite3_open_v2.  Otherwise, various
features that require the use of temporary files may fail.  Here is an
example of how to do this using C++ with the Windows Runtime:


See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_soft_heap_limit()
c2: C API: Deprecated Soft Heap Limit Interface
c5: c3ref/soft_heap_limit.html
c4:
This is a deprecated version of the sqlite3_soft_heap_limit64()
interface.  This routine is provided for historical compatibility
only.  All new applications should use the
sqlite3_soft_heap_limit64() interface rather than this one.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_trace_v2()
c2: C API: SQL Trace Hook
c5: c3ref/trace_v2.html
c4:
The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
function X against database connection D, using property mask M
and context pointer P.  If the X callback is
NULL or if the M mask is zero, then tracing is disabled.  The
M argument should be the bitwise OR-ed combination of
zero or more SQLITE_TRACE constants.

Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P)
overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or
sqlite3_trace_v2(D,M,X,P) for the database connection D.  Each
database connection may have at most one trace callback.

The X callback is invoked whenever any of the events identified by
mask M occur.  The integer return value from the callback is currently
ignored, though this may change in future releases.  Callback
implementations should return zero to ensure future compatibility.

A trace callback is invoked with four arguments: callback(T,C,P,X).
The T argument is one of the SQLITE_TRACE
constants to indicate why the callback was invoked.
The C argument is a copy of the context pointer.
The P and X arguments are pointers whose meanings depend on T.

The sqlite3_trace_v2() interface is intended to replace the legacy
interfaces sqlite3_trace() and sqlite3_profile(), both of which
are deprecated.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stmt_readonly()
c2: C API: Determine If An SQL Statement Writes The Database
c5: c3ref/stmt_readonly.html
c4:
The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
and only if the prepared statement X makes no direct changes to
the content of the database file.

Note that application-defined SQL functions or
virtual tables might change the database indirectly as a side effect.
For example, if an application defines a function "eval()" that
calls sqlite3_exec(), then the following SQL statement would
change the database file through side-effects:



But because the SELECT statement does not change the database file
directly, sqlite3_stmt_readonly() would still return true.

Transaction control statements such as BEGIN, COMMIT, ROLLBACK,
SAVEPOINT, and RELEASE cause sqlite3_stmt_readonly() to return true,
since the statements themselves do not actually modify the database but
rather they control the timing of when other statements modify the
database.  The ATTACH and DETACH statements also cause
sqlite3_stmt_readonly() to return true since, while those statements
change the configuration of a database connection, they do not make
changes to the content of the database files on disk.
The sqlite3_stmt_readonly() interface returns true for BEGIN since
BEGIN merely sets internal flags, but the BEGIN IMMEDIATE and
BEGIN EXCLUSIVE commands do touch the database and so
sqlite3_stmt_readonly() returns false for those commands.

This routine returns false if there is any possibility that the
statement might change the database file.  A false return does
not guarantee that the statement will change the database file.
For example, an UPDATE statement might have a WHERE clause that
makes it a no-op, but the sqlite3_stmt_readonly() result would still
be false.  Similarly, a CREATE TABLE IF NOT EXISTS statement is a
read-only no-op if the table already exists, but
sqlite3_stmt_readonly() still returns false for such a statement.

If prepared statement X is an EXPLAIN or EXPLAIN QUERY PLAN
statement, then sqlite3_stmt_readonly(X) returns the same value as
if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_release_memory()
c2: C API: Attempt To Free Heap Memory
c5: c3ref/release_memory.html
c4:
The sqlite3_release_memory() interface attempts to free N bytes
of heap memory by deallocating non-essential memory allocations
held by the database library.   Memory used to cache database
pages to improve performance is an example of non-essential memory.
sqlite3_release_memory() returns the number of bytes actually freed,
which might be more or less than the amount requested.
The sqlite3_release_memory() routine is a no-op returning zero
if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.

See also: sqlite3_db_release_memory()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stmt_scanstatus_reset()
c2: C API: Zero Scan-Status Counters
c5: c3ref/stmt_scanstatus_reset.html
c4:
Zero all sqlite3_stmt_scanstatus() related event counters.

This API is only available if the library is built with pre-processor
symbol SQLITE_ENABLE_STMT_SCANSTATUS defined.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_value
c2: C API: Dynamically Typed Value Object
c5: c3ref/value.html
c4:
SQLite uses the sqlite3_value object to represent all values
that can be stored in a database table. SQLite uses dynamic typing
for the values it stores.  Values stored in sqlite3_value objects
can be integers, floating point values, strings, BLOBs, or NULL.

An sqlite3_value object may be either "protected" or "unprotected".
Some interfaces require a protected sqlite3_value.  Other interfaces
will accept either a protected or an unprotected sqlite3_value.
Every interface that accepts sqlite3_value arguments specifies
whether or not it requires a protected sqlite3_value.  The
sqlite3_value_dup() interface can be used to construct a new
protected sqlite3_value from an unprotected sqlite3_value.

The terms "protected" and "unprotected" refer to whether or not
a mutex is held.  An internal mutex is held for a protected
sqlite3_value object but no mutex is held for an unprotected
sqlite3_value object.  If SQLite is compiled to be single-threaded
(with SQLITE_THREADSAFE=0 and with sqlite3_threadsafe() returning 0)
or if SQLite is run in one of reduced mutex modes
SQLITE_CONFIG_SINGLETHREAD or SQLITE_CONFIG_MULTITHREAD
then there is no distinction between protected and unprotected
sqlite3_value objects and they can be used interchangeably.  However,
for maximum code portability it is recommended that applications
still make the distinction between protected and unprotected
sqlite3_value objects even when not strictly required.

The sqlite3_value objects that are passed as parameters into the
implementation of application-defined SQL functions are protected.
The sqlite3_value objects returned by sqlite3_vtab_rhs_value()
are protected.
The sqlite3_value object returned by
sqlite3_column_value() is unprotected.
Unprotected sqlite3_value objects may only be used as arguments
to sqlite3_result_value(), sqlite3_bind_value(), and
sqlite3_value_dup().
The sqlite3_value_type() family of
interfaces require protected sqlite3_value objects.
19 Methods using this object:


sqlite3_value_blob
sqlite3_value_bytes
sqlite3_value_bytes16
sqlite3_value_double
sqlite3_value_dup
sqlite3_value_encoding
sqlite3_value_free
sqlite3_value_frombind
sqlite3_value_int
sqlite3_value_int64
sqlite3_value_nochange
sqlite3_value_numeric_type
sqlite3_value_pointer
sqlite3_value_subtype
sqlite3_value_text
sqlite3_value_text16
sqlite3_value_text16be
sqlite3_value_text16le
sqlite3_value_type



See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_uri_parameter(), sqlite3_uri_boolean(), sqlite3_uri_int64(), sqlite3_uri_key()
c2: C API: Obtain Values For URI Parameters
c5: c3ref/uri_boolean.html
c4:
These are utility routines, useful to custom VFS implementations,
that check if a database file was a URI that contained a specific query
parameter, and if so obtains the value of that query parameter.

The first parameter to these interfaces (hereafter referred to
as F) must be one of:

 A database filename pointer created by the SQLite core and
passed into the xOpen() method of a VFS implementation, or
 A filename obtained from sqlite3_db_filename(), or
 A new filename constructed using sqlite3_create_filename().

If the F parameter is not one of the above, then the behavior is
undefined and probably undesirable.  Older versions of SQLite were
more tolerant of invalid F parameters than newer versions.

If F is a suitable filename (as described in the previous paragraph)
and if P is the name of the query parameter, then
sqlite3_uri_parameter(F,P) returns the value of the P
parameter if it exists or a NULL pointer if P does not appear as a
query parameter on F.  If P is a query parameter of F and it
has no explicit value, then sqlite3_uri_parameter(F,P) returns
a pointer to an empty string.

The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
parameter and returns true (1) or false (0) according to the value
of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
value of query parameter P is one of "yes", "true", or "on" in any
case or if the value begins with a non-zero number.  The
sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
query parameter P is one of "no", "false", or "off" in any case or
if the value begins with a numeric zero.  If P is not a query
parameter on F or if the value of P does not match any of the
above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).

The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
64-bit signed integer and returns that integer, or D if P does not
exist.  If the value of P is something other than an integer, then
zero is returned.

The sqlite3_uri_key(F,N) returns a pointer to the name (not
the value) of the N-th query parameter for filename F, or a NULL
pointer if N is less than zero or greater than the number of query
parameters minus 1.  The N value is zero-based so N should be 0 to obtain
the name of the first query parameter, 1 for the second parameter, and
so forth.

If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
is not a database file pathname pointer that the SQLite core passed
into the xOpen VFS method, then the behavior of this routine is undefined
and probably undesirable.

Beginning with SQLite version 3.31.0 (2020-01-22) the input F
parameter can also be the name of a rollback journal file or WAL file
in addition to the main database file.  Prior to version 3.31.0, these
routines would only work if F was the name of the main database file.
When the F parameter is the name of the rollback journal or WAL file,
it has access to all the same query parameters as were found on the
main database file.

See the URI filename documentation for additional information.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Add Content To A Dynamic String
c5: c3ref/str_append.html
c0:
sqlite3_str_appendf(), sqlite3_str_vappendf(), sqlite3_str_append(), sqlite3_str_appendall(), sqlite3_str_appendchar(), sqlite3_str_reset()

c4:
These interfaces add content to an sqlite3_str object previously obtained
from sqlite3_str_new().

The sqlite3_str_appendf(X,F,...) and
sqlite3_str_vappendf(X,F,V) interfaces uses the built-in printf
functionality of SQLite to append formatted text onto the end of
sqlite3_str object X.

The sqlite3_str_append(X,S,N) method appends exactly N bytes from string S
onto the end of the sqlite3_str object X.  N must be non-negative.
S must contain at least N non-zero bytes of content.  To append a
zero-terminated string in its entirety, use the sqlite3_str_appendall()
method instead.

The sqlite3_str_appendall(X,S) method appends the complete content of
zero-terminated string S onto the end of sqlite3_str object X.

The sqlite3_str_appendchar(X,N,C) method appends N copies of the
single-byte character C onto the end of sqlite3_str object X.
This method can be used, for example, to add whitespace indentation.

The sqlite3_str_reset(X) method resets the string under construction
inside sqlite3_str object X back to zero bytes in length.

These methods do not return a result code.  If an error occurs, that fact
is recorded in the sqlite3_str object and can be recovered by a
subsequent call to sqlite3_str_errcode(X).
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Virtual Table Configuration Options
c5: c3ref/c_vtab_constraint_support.html
c0:
SQLITE_VTAB_CONSTRAINT_SUPPORT, SQLITE_VTAB_INNOCUOUS, SQLITE_VTAB_DIRECTONLY, SQLITE_VTAB_USES_ALL_SCHEMAS

c4:
These macros define the various options to the
sqlite3_vtab_config() interface that virtual table implementations
can use to customize and optimize their behavior.




SQLITE_VTAB_CONSTRAINT_SUPPORT
Calls of the form
sqlite3_vtab_config(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
where X is an integer.  If X is zero, then the virtual table whose
xCreate or xConnect method invoked sqlite3_vtab_config() does not
support constraints.  In this configuration (which is the default) if
a call to the xUpdate method returns SQLITE_CONSTRAINT, then the entire
statement is rolled back as if OR ABORT had been
specified as part of the users SQL statement, regardless of the actual
ON CONFLICT mode specified.

If X is non-zero, then the virtual table implementation guarantees
that if xUpdate returns SQLITE_CONSTRAINT, it will do so before
any modifications to internal or persistent data structures have been made.
If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
is able to roll back a statement or database transaction, and abandon
or continue processing the current SQL statement as appropriate.
If the ON CONFLICT mode is REPLACE and the xUpdate method returns
SQLITE_CONSTRAINT, SQLite handles this as if the ON CONFLICT mode
had been ABORT.

Virtual table implementations that are required to handle OR REPLACE
must do so within the xUpdate method. If a call to the
sqlite3_vtab_on_conflict() function indicates that the current ON
CONFLICT policy is REPLACE, the virtual table implementation should
silently replace the appropriate rows within the xUpdate callback and
return SQLITE_OK. Or, if this is not possible, it may return
SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
constraint handling.



SQLITE_VTAB_DIRECTONLY
Calls of the form
sqlite3_vtab_config(db,SQLITE_VTAB_DIRECTONLY) from within the
the xConnect or xCreate methods of a virtual table implementation
prohibits that virtual table from being used from within triggers and
views.



SQLITE_VTAB_INNOCUOUS
Calls of the form
sqlite3_vtab_config(db,SQLITE_VTAB_INNOCUOUS) from within the
the xConnect or xCreate methods of a virtual table implementation
identify that virtual table as being safe to use from within triggers
and views.  Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the
virtual table can do no serious harm even if it is controlled by a
malicious hacker.  Developers should avoid setting the SQLITE_VTAB_INNOCUOUS
flag unless absolutely necessary.



SQLITE_VTAB_USES_ALL_SCHEMAS
Calls of the form
sqlite3_vtab_config(db,SQLITE_VTAB_USES_ALL_SCHEMA) from within the
the xConnect or xCreate methods of a virtual table implementation
instruct the query planner to begin at least a read transaction on
all schemas ("main", "temp", and any ATTACH-ed databases) whenever the
virtual table is used.


See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_libversion(), sqlite3_sourceid(), sqlite3_libversion_number()
c2: C API: Run-Time Library Version Numbers
c5: c3ref/libversion.html
c4:
These interfaces provide the same information as the SQLITE_VERSION,
SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros
but are associated with the library instead of the header file.  Cautious
programmers might include assert() statements in their application to
verify that values returned by these interfaces match the macros in
the header, and thus ensure that the application is
compiled with matching library and header files.



The sqlite3_version[] string constant contains the text of SQLITE_VERSION
macro.  The sqlite3_libversion() function returns a pointer to the
to the sqlite3_version[] string constant.  The sqlite3_libversion()
function is provided for use in DLLs since DLL users usually do not have
direct access to string constants within the DLL.  The
sqlite3_libversion_number() function returns an integer equal to
SQLITE_VERSION_NUMBER.  The sqlite3_sourceid() function returns
a pointer to a string constant whose value is the same as the
SQLITE_SOURCE_ID C preprocessor macro.  Except if SQLite is built
using an edited copy of the amalgamation, then the last four characters
of the hash might be different from SQLITE_SOURCE_ID.

See also: sqlite_version() and sqlite_source_id().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_win32_set_directory(), sqlite3_win32_set_directory8(), sqlite3_win32_set_directory16()
c2: C API: Win32 Specific Interface
c5: c3ref/win32_set_directory.html
c4:
These interfaces are available only on Windows.  The
sqlite3_win32_set_directory interface is used to set the value associated
with the sqlite3_temp_directory or sqlite3_data_directory variable, to
zValue, depending on the value of the type parameter.  The zValue parameter
should be NULL to cause the previous value to be freed via sqlite3_free;
a non-NULL value will be copied into memory obtained from sqlite3_malloc
prior to being used.  The sqlite3_win32_set_directory interface returns
SQLITE_OK to indicate success, SQLITE_ERROR if the type is unsupported,
or SQLITE_NOMEM if memory could not be allocated.  The value of the
sqlite3_data_directory variable is intended to act as a replacement for
the current directory on the sub-platforms of Win32 where that concept is
not present, e.g. WinRT and UWP.  The sqlite3_win32_set_directory8 and
sqlite3_win32_set_directory16 interfaces behave exactly the same as the
sqlite3_win32_set_directory interface except the string parameter must be
UTF-8 or UTF-16, respectively.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Status Parameters for database connections
c5: c3ref/c_dbstatus_options.html
c0:
SQLITE_DBSTATUS_LOOKASIDE_USED, SQLITE_DBSTATUS_CACHE_USED, SQLITE_DBSTATUS_SCHEMA_USED, SQLITE_DBSTATUS_STMT_USED, SQLITE_DBSTATUS_LOOKASIDE_HIT, SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE, SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL, SQLITE_DBSTATUS_CACHE_HIT, SQLITE_DBSTATUS_CACHE_MISS, SQLITE_DBSTATUS_CACHE_WRITE, SQLITE_DBSTATUS_DEFERRED_FKS, SQLITE_DBSTATUS_CACHE_USED_SHARED, SQLITE_DBSTATUS_CACHE_SPILL, SQLITE_DBSTATUS_MAX

c4:
These constants are the available integer "verbs" that can be passed as
the second argument to the sqlite3_db_status() interface.

New verbs may be added in future releases of SQLite. Existing verbs
might be discontinued. Applications should check the return code from
sqlite3_db_status() to make sure that the call worked.
The sqlite3_db_status() interface will return a non-zero error code
if a discontinued or unsupported verb is invoked.



 SQLITE_DBSTATUS_LOOKASIDE_USED
This parameter returns the number of lookaside memory slots currently
checked out.


 SQLITE_DBSTATUS_LOOKASIDE_HIT
This parameter returns the number of malloc attempts that were
satisfied using lookaside memory. Only the high-water value is meaningful;
the current value is always zero.



SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
This parameter returns the number malloc attempts that might have
been satisfied using lookaside memory but failed due to the amount of
memory requested being larger than the lookaside slot size.
Only the high-water value is meaningful;
the current value is always zero.



SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
This parameter returns the number malloc attempts that might have
been satisfied using lookaside memory but failed due to all lookaside
memory already being in use.
Only the high-water value is meaningful;
the current value is always zero.


 SQLITE_DBSTATUS_CACHE_USED
This parameter returns the approximate number of bytes of heap
memory used by all pager caches associated with the database connection.
The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.



SQLITE_DBSTATUS_CACHE_USED_SHARED
This parameter is similar to DBSTATUS_CACHE_USED, except that if a
pager cache is shared between two or more connections the bytes of heap
memory used by that pager cache is divided evenly between the attached
connections.  In other words, if none of the pager caches associated
with the database connection are shared, this request returns the same
value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
shared, the value returned by this call will be smaller than that returned
by DBSTATUS_CACHE_USED. The highwater mark associated with
SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.


 SQLITE_DBSTATUS_SCHEMA_USED
This parameter returns the approximate number of bytes of heap
memory used to store the schema for all databases associated
with the connection - main, temp, and any ATTACH-ed databases.
The full amount of memory used by the schemas is reported, even if the
schema memory is shared with other database connections due to
shared cache mode being enabled.
The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.


 SQLITE_DBSTATUS_STMT_USED
This parameter returns the approximate number of bytes of heap
and lookaside memory used by all prepared statements associated with
the database connection.
The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.



 SQLITE_DBSTATUS_CACHE_HIT
This parameter returns the number of pager cache hits that have
occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
is always 0.



 SQLITE_DBSTATUS_CACHE_MISS
This parameter returns the number of pager cache misses that have
occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
is always 0.



 SQLITE_DBSTATUS_CACHE_WRITE
This parameter returns the number of dirty cache entries that have
been written to disk. Specifically, the number of pages written to the
wal file in wal mode databases, or the number of pages written to the
database file in rollback mode databases. Any pages written as part of
transaction rollback or database recovery operations are not included.
If an IO or other error occurs while writing a page to disk, the effect
on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. The
highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.



 SQLITE_DBSTATUS_CACHE_SPILL
This parameter returns the number of dirty cache entries that have
been written to disk in the middle of a transaction due to the page
cache overflowing. Transactions are more efficient if they are written
to disk all at once. When pages spill mid-transaction, that introduces
additional overhead. This parameter can be used help identify
inefficiencies that can be resolved by increasing the cache size.



 SQLITE_DBSTATUS_DEFERRED_FKS
This parameter returns zero for the current value if and only if
all foreign key constraints (deferred or immediate) have been
resolved.  The highwater mark is always 0.


See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_DETERMINISTIC, SQLITE_DIRECTONLY, SQLITE_SUBTYPE, SQLITE_INNOCUOUS, SQLITE_RESULT_SUBTYPE
c2: C API: Function Flags
c5: c3ref/c_deterministic.html
c4:
These constants may be ORed together with the
preferred text encoding as the fourth argument
to sqlite3_create_function(), sqlite3_create_function16(), or
sqlite3_create_function_v2().



 SQLITE_DETERMINISTIC
The SQLITE_DETERMINISTIC flag means that the new function always gives
the same output when the input parameters are the same.
The abs() function is deterministic, for example, but
randomblob() is not.  Functions must
be deterministic in order to be used in certain contexts such as
with the WHERE clause of partial indexes or in generated columns.
SQLite might also optimize deterministic functions by factoring them
out of inner loops.



 SQLITE_DIRECTONLY
The SQLITE_DIRECTONLY flag means that the function may only be invoked
from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
schema structures such as CHECK constraints, DEFAULT clauses,
expression indexes, partial indexes, or generated columns.

The SQLITE_DIRECTONLY flag is recommended for any
application-defined SQL function
that has side-effects or that could potentially leak sensitive information.
This will prevent attacks in which an application is tricked
into using a database file that has had its schema surreptitiously
modified to invoke the application-defined function in ways that are
harmful.

Some people say it is good practice to set SQLITE_DIRECTONLY on all
application-defined SQL functions, regardless of whether or not they
are security sensitive, as doing so prevents those functions from being used
inside of the database schema, and thus ensures that the database
can be inspected and modified using generic tools (such as the CLI)
that do not have access to the application-defined functions.



 SQLITE_INNOCUOUS
The SQLITE_INNOCUOUS flag means that the function is unlikely
to cause problems even if misused.  An innocuous function should have
no side effects and should not depend on any values other than its
input parameters. The abs() function is an example of an
innocuous function.
The load_extension() SQL function is not innocuous because of its
side effects.
 SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
exactly the same.  The random() function is an example of a
function that is innocuous but not deterministic.
Some heightened security settings
(SQLITE_DBCONFIG_TRUSTED_SCHEMA and PRAGMA trusted_schema=OFF)
disable the use of SQL functions inside views and triggers and in
schema structures such as CHECK constraints, DEFAULT clauses,
expression indexes, partial indexes, and generated columns unless
the function is tagged with SQLITE_INNOCUOUS.  Most built-in functions
are innocuous.  Developers are advised to avoid using the
SQLITE_INNOCUOUS flag for application-defined functions unless the
function has been carefully audited and found to be free of potentially
security-adverse side-effects and information-leaks.



 SQLITE_SUBTYPE
The SQLITE_SUBTYPE flag indicates to SQLite that a function might call
sqlite3_value_subtype() to inspect the sub-types of its arguments.
This flag instructs SQLite to omit some corner-case optimizations that
might disrupt the operation of the sqlite3_value_subtype() function,
causing it to return zero rather than the correct subtype().
SQL functions that invokes sqlite3_value_subtype() should have this
property.  If the SQLITE_SUBTYPE property is omitted, then the return
value from sqlite3_value_subtype() might sometimes be zero even though
a non-zero subtype was specified by the function argument expression.


 SQLITE_RESULT_SUBTYPE
The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call
sqlite3_result_subtype() to cause a sub-type to be associated with its
result.
Every function that invokes sqlite3_result_subtype() should have this
property.  If it does not, then the call to sqlite3_result_subtype()
might become a no-op if the function is used as term in an
expression index.  On the other hand, SQL functions that never invoke
sqlite3_result_subtype() should avoid setting this property, as the
purpose of this property is to disable certain optimizations that are
incompatible with subtypes.


See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_mutex()
c2: C API: Retrieve the mutex for a database connection
c5: c3ref/db_mutex.html
c4:
This interface returns a pointer the sqlite3_mutex object that
serializes access to the database connection given in the argument
when the threading mode is Serialized.
If the threading mode is Single-thread or Multi-thread then this
routine returns a NULL pointer.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_vtab_in_first(), sqlite3_vtab_in_next()
c2: C API: Find all elements on the right-hand side of an IN constraint.
c5: c3ref/vtab_in_first.html
c4:
These interfaces are only useful from within the
xFilter() method of a virtual table implementation.
The result of invoking these interfaces from any other context
is undefined and probably harmful.

The X parameter in a call to sqlite3_vtab_in_first(X,P) or
sqlite3_vtab_in_next(X,P) should be one of the parameters to the
xFilter method which invokes these routines, and specifically
a parameter that was previously selected for all-at-once IN constraint
processing use the sqlite3_vtab_in() interface in the
xBestIndex method.  If the X parameter is not
an xFilter argument that was selected for all-at-once IN constraint
processing, then these routines return SQLITE_ERROR.

Use these routines to access all values on the right-hand side
of the IN constraint using code like the following:



On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
routines return SQLITE_OK and set *P to point to the first or next value
on the RHS of the IN constraint.  If there are no more values on the
right hand side of the IN constraint, then *P is set to NULL and these
routines return SQLITE_DONE.  The return value might be
some other value, such as SQLITE_NOMEM, in the event of a malfunction.

The *ppOut values returned by these routines are only valid until the
next call to either of these routines or until the end of the xFilter
method from which these routines were called.  If the virtual table
implementation needs to retain the *ppOut values for longer, it must make
copies.  The *ppOut values are protected.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Virtual Table Indexing Information
c5: c3ref/index_info.html
c0:
struct sqlite3_index_info, struct sqlite3_index_constraint, struct sqlite3_index_orderby, struct sqlite3_index_constraint_usage

c4:
The sqlite3_index_info structure and its substructures is used as part
of the virtual table interface to
pass information into and receive the reply from the xBestIndex
method of a virtual table module.  The fields under **Inputs** are the
inputs to xBestIndex and are read-only.  xBestIndex inserts its
results into the **Outputs** fields.

The aConstraint[] array records WHERE clause constraints of the form:



where OP is =, &lt;, &lt;=, &gt;, or &gt;=.  The particular operator is
stored in aConstraint[].op using one of the
SQLITE_INDEX_CONSTRAINT_ values.
The index of the column is stored in
aConstraint[].iColumn.  aConstraint[].usable is TRUE if the
expr on the right-hand side can be evaluated (and thus the constraint
is usable) and false if it cannot.

The optimizer automatically inverts terms of the form "expr OP column"
and makes other simplifications to the WHERE clause in an attempt to
get as many WHERE clause terms into the form shown above as possible.
The aConstraint[] array only reports WHERE clause terms that are
relevant to the particular virtual table being queried.

Information about the ORDER BY clause is stored in aOrderBy[].
Each term of aOrderBy records a column of the ORDER BY clause.

The colUsed field indicates which columns of the virtual table may be
required by the current scan. Virtual table columns are numbered from
zero in the order in which they appear within the CREATE TABLE statement
passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
the corresponding bit is set within the colUsed mask if the column may be
required by SQLite. If the table has at least 64 columns and any column
to the right of the first 63 is required, then bit 63 of colUsed is also
set. In other words, column iCol may be required if the expression
(colUsed & ((sqlite3_uint64)1 =63 ? 63 : iCol))) evaluates to
non-zero.

The xBestIndex method must fill aConstraintUsage[] with information
about what parameters to pass to xFilter.  If argvIndex>0 then
the right-hand side of the corresponding aConstraint[] is evaluated
and becomes the argvIndex-th entry in argv.  If aConstraintUsage[].omit
is true, then the constraint is assumed to be fully handled by the
virtual table and might not be checked again by the byte code. The
aConstraintUsage[].omit flag is an optimization hint. When the omit flag
is left in its default setting of false, the constraint will always be
checked separately in byte code.  If the omit flag is change to true, then
the constraint may or may not be checked in byte code.  In other words,
when the omit flag is true there is no guarantee that the constraint will
not be checked again using byte code.

The idxNum and idxStr values are recorded and passed into the
xFilter method.
sqlite3_free() is used to free idxStr if and only if
needToFreeIdxStr is true.

The orderByConsumed means that output from xFilter/xNext will occur in
the correct order to satisfy the ORDER BY clause so that no separate
sorting step is required.

The estimatedCost value is an estimate of the cost of a particular
strategy. A cost of N indicates that the cost of the strategy is similar
to a linear scan of an SQLite table with N rows. A cost of log(N)
indicates that the expense of the operation is similar to that of a
binary search on a unique indexed field of an SQLite table with N rows.

The estimatedRows value is an estimate of the number of rows that
will be returned by the strategy.

The xBestIndex method may optionally populate the idxFlags field with a
mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
assumes that the strategy may visit at most one row.

Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
SQLite also assumes that if a call to the xUpdate() method is made as
part of the same statement to delete or update a virtual table row and the
implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
any database changes. In other words, if the xUpdate() returns
SQLITE_CONSTRAINT, the database contents must be exactly as they were
before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
the xUpdate method are automatically rolled back by SQLite.

IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
structure for SQLite version 3.8.2 (2013-12-06).
If a virtual table extension is
used with an SQLite version earlier than 3.8.2, the results of attempting
to read or write the estimatedRows field are undefined (but are likely
to include crashing the application). The estimatedRows field should
therefore only be used if sqlite3_libversion_number() returns a
value greater than or equal to 3008002. Similarly, the idxFlags field
was added for version 3.9.0 (2015-10-14).
It may therefore only be used if
sqlite3_libversion_number() returns a value greater than or equal to
3009000.
3 Methods using this object:
 sqlite3_vtab_collation(),
sqlite3_vtab_distinct(),
sqlite3_vtab_rhs_value()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_set_last_insert_rowid()
c2: C API: Set the Last Insert Rowid value.
c5: c3ref/set_last_insert_rowid.html
c4:
The sqlite3_set_last_insert_rowid(D, R) method allows the application to
set the value returned by calling sqlite3_last_insert_rowid(D) to R
without inserting a row into the database.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_str_new()
c2: C API: Create A New Dynamic String Object
c5: c3ref/str_new.html
c4:
The sqlite3_str_new(D) interface allocates and initializes
a new sqlite3_str object.  To avoid memory leaks, the object returned by
sqlite3_str_new() must be freed by a subsequent call to
sqlite3_str_finish(X).

The sqlite3_str_new(D) interface always returns a pointer to a
valid sqlite3_str object, though in the event of an out-of-memory
error the returned object might be a special singleton that will
silently reject new text, always return SQLITE_NOMEM from
sqlite3_str_errcode(), always return 0 for
sqlite3_str_length(), and always return NULL from
sqlite3_str_finish(X).  It is always safe to use the value
returned by sqlite3_str_new(D) as the sqlite3_str parameter
to any of the other sqlite3_str methods.

The D parameter to sqlite3_str_new(D) may be NULL.  If the
D parameter in sqlite3_str_new(D) is not NULL, then the maximum
length of the string contained in the sqlite3_str object will be
the value set for sqlite3_limit(D,SQLITE_LIMIT_LENGTH) instead
of SQLITE_MAX_LENGTH.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_PREPARE_PERSISTENT, SQLITE_PREPARE_NORMALIZE, SQLITE_PREPARE_NO_VTAB
c2: C API: Prepare Flags
c5: c3ref/c_prepare_normalize.html
c4:
These constants define various flags that can be passed into
"prepFlags" parameter of the sqlite3_prepare_v3() and
sqlite3_prepare16_v3() interfaces.

New flags may be added in future releases of SQLite.



 SQLITE_PREPARE_PERSISTENT
The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
that the prepared statement will be retained for a long time and
probably reused many times. Without this flag, sqlite3_prepare_v3()
and sqlite3_prepare16_v3() assume that the prepared statement will
be used just once or at most a few times and then destroyed using
sqlite3_finalize() relatively soon. The current implementation acts
on this hint by avoiding the use of lookaside memory so as not to
deplete the limited store of lookaside memory. Future versions of
SQLite may act on this hint differently.


 SQLITE_PREPARE_NORMALIZE
The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
to be required for any prepared statement that wanted to use the
sqlite3_normalized_sql() interface.  However, the
sqlite3_normalized_sql() interface is now available to all
prepared statements, regardless of whether or not they use this
flag.


 SQLITE_PREPARE_NO_VTAB
The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
to return an error (error code SQLITE_ERROR) if the statement uses
any virtual tables.

See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_column_decltype(), sqlite3_column_decltype16()
c2: C API: Declared Datatype Of A Query Result
c5: c3ref/column_decltype.html
c4:
The first parameter is a prepared statement.
If this statement is a SELECT statement and the Nth column of the
returned result set of that SELECT is a table column (not an
expression or subquery) then the declared type of the table
column is returned.  If the Nth column of the result set is an
expression or subquery, then a NULL pointer is returned.
The returned string is always UTF-8 encoded.

For example, given the database schema:

CREATE TABLE t1(c1 VARIANT);

and the following statement to be compiled:

SELECT c1 + 1, c1 FROM t1;

this routine would return the string "VARIANT" for the second result
column (i==1), and a NULL pointer for the first result column (i==0).

SQLite uses dynamic run-time typing.  So just because a column
is declared to contain a particular type does not mean that the
data stored in that column is of the declared type.  SQLite is
strongly typed, but the typing is dynamic not static.  Type
is associated with individual values, not with the containers
used to hold those values.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_SHM_UNLOCK, SQLITE_SHM_LOCK, SQLITE_SHM_SHARED, SQLITE_SHM_EXCLUSIVE
c2: C API: Flags for the xShmLock VFS method
c5: c3ref/c_shm_exclusive.html
c4:
These integer constants define the various locking operations
allowed by the xShmLock method of sqlite3_io_methods.  The
following are the only legal combinations of flags to the
xShmLock method:


  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE


When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
was given on the corresponding lock.

The xShmLock method can transition between unlocked and SHARED or
between unlocked and EXCLUSIVE.  It cannot transition between SHARED
and EXCLUSIVE.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_blob_reopen()
c2: C API: Move a BLOB Handle to a New Row
c5: c3ref/blob_reopen.html
c4:
This function is used to move an existing BLOB handle so that it points
to a different row of the same database table. The new row is identified
by the rowid value passed as the second argument. Only the row can be
changed. The database, table and column on which the blob handle is open
remain the same. Moving an existing BLOB handle to a new row is
faster than closing the existing handle and opening a new one.

The new row must meet the same criteria as for sqlite3_blob_open() -
it must exist and there must be either a blob or text value stored in
the nominated column. If the new row is not present in the table, or if
it does not contain a blob or text value, or if another error occurs, an
SQLite error code is returned and the blob handle is considered aborted.
All subsequent calls to sqlite3_blob_read(), sqlite3_blob_write() or
sqlite3_blob_reopen() on an aborted blob handle immediately return
SQLITE_ABORT. Calling sqlite3_blob_bytes() on an aborted blob handle
always returns zero.

This function sets the database handle error code and message.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_extended_result_codes()
c2: C API: Enable Or Disable Extended Result Codes
c5: c3ref/extended_result_codes.html
c4:
The sqlite3_extended_result_codes() routine enables or disables the
extended result codes feature of SQLite. The extended result
codes are disabled by default for historical compatibility.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_progress_handler()
c2: C API: Query Progress Callbacks
c5: c3ref/progress_handler.html
c4:
The sqlite3_progress_handler(D,N,X,P) interface causes the callback
function X to be invoked periodically during long running calls to
sqlite3_step() and sqlite3_prepare() and similar for
database connection D.  An example use for this
interface is to keep a GUI updated during a large query.

The parameter P is passed through as the only parameter to the
callback function X.  The parameter N is the approximate number of
virtual machine instructions that are evaluated between successive
invocations of the callback X.  If N is less than one then the progress
handler is disabled.

Only a single progress handler may be defined at one time per
database connection; setting a new progress handler cancels the
old one.  Setting parameter X to NULL disables the progress handler.
The progress handler is also disabled by setting N to a value less
than 1.

If the progress callback returns non-zero, the operation is
interrupted.  This feature can be used to implement a
"Cancel" button on a GUI progress dialog box.

The progress handler callback must not do anything that will modify
the database connection that invoked the progress handler.
Note that sqlite3_prepare_v2() and sqlite3_step() both modify their
database connections for the meaning of "modify" in this paragraph.

The progress handler callback would originally only be invoked from the
bytecode engine.  It still might be invoked during sqlite3_prepare()
and similar because those routines might force a reparse of the schema
which involves running the bytecode engine.  However, beginning with
SQLite version 3.41.0, the progress handler callback might also be
invoked directly from sqlite3_prepare() while analyzing and generating
code for complex queries.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stmt_scanstatus(), sqlite3_stmt_scanstatus_v2()
c2: C API: Prepared Statement Scan Status
c5: c3ref/stmt_scanstatus.html
c4:
These interfaces return information about the predicted and measured
performance for pStmt.  Advanced applications can use this
interface to compare the predicted and the measured performance and
issue warnings and/or rerun ANALYZE if discrepancies are found.

Since this interface is expected to be rarely used, it is only
available if SQLite is compiled using the SQLITE_ENABLE_STMT_SCANSTATUS
compile-time option.

The "iScanStatusOp" parameter determines which status information to return.
The "iScanStatusOp" must be one of the scanstatus options or the behavior
of this interface is undefined. The requested measurement is written into
a variable pointed to by the "pOut" parameter.

The "flags" parameter must be passed a mask of flags. At present only
one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX
is specified, then status information is available for all elements
of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If
SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements
that correspond to query loops (the "SCAN..." and "SEARCH..." elements of
the EXPLAIN QUERY PLAN output) are available. Invoking API
sqlite3_stmt_scanstatus() is equivalent to calling
sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.

Parameter "idx" identifies the specific query element to retrieve statistics
for. Query elements are numbered starting from zero. A value of -1 may be
to query for statistics regarding the entire query. If idx is out of range
- less than -1 or greater than or equal to the total number of query
elements used to implement the statement - a non-zero value is returned and
the variable that pOut points to is unchanged.

See also: sqlite3_stmt_scanstatus_reset()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_txn_state()
c2: C API: Determine the transaction state of a database
c5: c3ref/txn_state.html
c4:
The sqlite3_txn_state(D,S) interface returns the current
transaction state of schema S in database connection D.  If S is NULL,
then the highest transaction state of any schema on database connection D
is returned.  Transaction states are (in order of lowest to highest):

 SQLITE_TXN_NONE
 SQLITE_TXN_READ
 SQLITE_TXN_WRITE

If the S argument to sqlite3_txn_state(D,S) is not the name of
a valid schema, then -1 is returned.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_compileoption_used(), sqlite3_compileoption_get()
c2: C API: Run-Time Library Compilation Options Diagnostics
c5: c3ref/compileoption_get.html
c4:
The sqlite3_compileoption_used() function returns 0 or 1
indicating whether the specified option was defined at
compile time.  The SQLITE_ prefix may be omitted from the
option name passed to sqlite3_compileoption_used().

The sqlite3_compileoption_get() function allows iterating
over the list of options that were defined at compile time by
returning the N-th compile time option string.  If N is out of range,
sqlite3_compileoption_get() returns a NULL pointer.  The SQLITE_
prefix is omitted from any strings returned by
sqlite3_compileoption_get().

Support for the diagnostic functions sqlite3_compileoption_used()
and sqlite3_compileoption_get() may be omitted by specifying the
SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.

See also: SQL functions sqlite_compileoption_used() and
sqlite_compileoption_get() and the compile_options pragma.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_wal_checkpoint_v2()
c2: C API: Checkpoint a database
c5: c3ref/wal_checkpoint_v2.html
c4:
The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
operation on database X of database connection D in mode M.  Status
information is written back into integers pointed to by L and C.
The M parameter must be a valid checkpoint mode:


SQLITE_CHECKPOINT_PASSIVE
Checkpoint as many frames as possible without waiting for any database
readers or writers to finish, then sync the database file if all frames
in the log were checkpointed. The busy-handler callback
is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
On the other hand, passive mode might leave the checkpoint unfinished
if there are concurrent readers or writers.

SQLITE_CHECKPOINT_FULL
This mode blocks (it invokes the
busy-handler callback) until there is no
database writer and all readers are reading from the most recent database
snapshot. It then checkpoints all frames in the log file and syncs the
database file. This mode blocks new database writers while it is pending,
but new database readers are allowed to continue unimpeded.

SQLITE_CHECKPOINT_RESTART
This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
that after checkpointing the log file it blocks (calls the
busy-handler callback)
until all readers are reading from the database file only. This ensures
that the next writer will restart the log file from the beginning.
Like SQLITE_CHECKPOINT_FULL, this mode blocks new
database writer attempts while it is pending, but does not impede readers.

SQLITE_CHECKPOINT_TRUNCATE
This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
addition that it also truncates the log file to zero bytes just prior
to a successful return.


If pnLog is not NULL, then *pnLog is set to the total number of frames in
the log file or to -1 if the checkpoint could not run because
of an error or because the database is not in WAL mode. If pnCkpt is not
NULL,then *pnCkpt is set to the total number of checkpointed frames in the
log file (including any that were already checkpointed before the function
was called) or to -1 if the checkpoint could not run due to an error or
because the database is not in WAL mode. Note that upon successful
completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.

All calls obtain an exclusive "checkpoint" lock on the database file. If
any other process is running a checkpoint operation at the same time, the
lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
busy-handler configured, it will not be invoked in this case.

The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
exclusive "writer" lock on the database file. If the writer lock cannot be
obtained immediately, and a busy-handler is configured, it is invoked and
the writer lock retried until either the busy-handler returns 0 or the lock
is successfully obtained. The busy-handler is also invoked while waiting for
database readers as described above. If the busy-handler returns 0 before
the writer lock is obtained or while waiting for database readers, the
checkpoint operation proceeds from that point in the same way as
SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
without blocking any further. SQLITE_BUSY is returned in this case.

If parameter zDb is NULL or points to a zero length string, then the
specified operation is attempted on all WAL databases attached to
database connection db.  In this case the
values written to output parameters *pnLog and *pnCkpt are undefined. If
an SQLITE_BUSY error is encountered when processing one or more of the
attached WAL databases, the operation is still attempted on any remaining
attached databases and SQLITE_BUSY is returned at the end. If any other
error occurs while processing an attached database, processing is abandoned
and the error code is returned to the caller immediately. If no error
(SQLITE_BUSY or otherwise) is encountered while processing the attached
databases, SQLITE_OK is returned.

If database zDb is the name of an attached database that is not in WAL
mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
zDb is not NULL (or a zero length string) and is not the name of any
attached database, SQLITE_ERROR is returned to the caller.

Unless it returns SQLITE_MISUSE,
the sqlite3_wal_checkpoint_v2() interface
sets the error information that is queried by
sqlite3_errcode() and sqlite3_errmsg().

The PRAGMA wal_checkpoint command can be used to invoke this interface
from SQL.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Prepared Statement Scan Status Opcodes
c5: c3ref/c_scanstat_est.html
c0:
SQLITE_SCANSTAT_NLOOP, SQLITE_SCANSTAT_NVISIT, SQLITE_SCANSTAT_EST, SQLITE_SCANSTAT_NAME, SQLITE_SCANSTAT_EXPLAIN, SQLITE_SCANSTAT_SELECTID, SQLITE_SCANSTAT_PARENTID, SQLITE_SCANSTAT_NCYCLE

c4:
The following constants can be used for the T parameter to the
sqlite3_stmt_scanstatus(S,X,T,V) interface.  Each constant designates a
different metric for sqlite3_stmt_scanstatus() to return.

When the value returned to V is a string, space to hold that string is
managed by the prepared statement S and will be automatically freed when
S is finalized.

Not all values are available for all query elements. When a value is
not available, the output variable is set to -1 if the value is numeric,
or to NULL if it is a string (SQLITE_SCANSTAT_NAME).



 SQLITE_SCANSTAT_NLOOP
The sqlite3_int64 variable pointed to by the V parameter will be
set to the total number of times that the X-th loop has run.


 SQLITE_SCANSTAT_NVISIT
The sqlite3_int64 variable pointed to by the V parameter will be set
to the total number of rows examined by all iterations of the X-th loop.


 SQLITE_SCANSTAT_EST
The "double" variable pointed to by the V parameter will be set to the
query planner's estimate for the average number of rows output from each
iteration of the X-th loop.  If the query planner's estimates was accurate,
then this value will approximate the quotient NVISIT/NLOOP and the
product of this value for all prior loops with the same SELECTID will
be the NLOOP value for the current loop.


 SQLITE_SCANSTAT_NAME
The "const char *" variable pointed to by the V parameter will be set
to a zero-terminated UTF-8 string containing the name of the index or table
used for the X-th loop.


 SQLITE_SCANSTAT_EXPLAIN
The "const char *" variable pointed to by the V parameter will be set
to a zero-terminated UTF-8 string containing the EXPLAIN QUERY PLAN
description for the X-th loop.


 SQLITE_SCANSTAT_SELECTID
The "int" variable pointed to by the V parameter will be set to the
id for the X-th query plan element. The id value is unique within the
statement. The select-id is the same value as is output in the first
column of an EXPLAIN QUERY PLAN query.


 SQLITE_SCANSTAT_PARENTID
The "int" variable pointed to by the V parameter will be set to the
the id of the parent of the current query element, if applicable, or
to zero if the query element has no parent. This is the same value as
returned in the second column of an EXPLAIN QUERY PLAN query.


 SQLITE_SCANSTAT_NCYCLE
The sqlite3_int64 output value is set to the number of cycles,
according to the processor time-stamp counter, that elapsed while the
query element was being processed. This value is not available for
all query elements - if it is unavailable the output variable is
set to -1.

See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Obtaining SQL Values
c5: c3ref/value_blob.html
c0:
sqlite3_value_blob(), sqlite3_value_double(), sqlite3_value_int(), sqlite3_value_int64(), sqlite3_value_pointer(), sqlite3_value_text(), sqlite3_value_text16(), sqlite3_value_text16le(), sqlite3_value_text16be(), sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_type(), sqlite3_value_numeric_type(), sqlite3_value_nochange(), sqlite3_value_frombind()

c4:
Summary:


Details:

These routines extract type, size, and content information from
protected sqlite3_value objects.  Protected sqlite3_value objects
are used to pass parameter information into the functions that
implement application-defined SQL functions and virtual tables.

These routines work only with protected sqlite3_value objects.
Any attempt to use these routines on an unprotected sqlite3_value
is not threadsafe.

These routines work just like the corresponding column access functions
except that these routines take a single protected sqlite3_value object
pointer instead of a sqlite3_stmt* pointer and an integer column number.

The sqlite3_value_text16() interface extracts a UTF-16 string
in the native byte-order of the host machine.  The
sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
extract UTF-16 strings as big-endian and little-endian respectively.

If sqlite3_value object V was initialized
using sqlite3_bind_pointer(S,I,P,X,D) or sqlite3_result_pointer(C,P,X,D)
and if X and Y are strings that compare equal according to strcmp(X,Y),
then sqlite3_value_pointer(V,Y) will return the pointer P.  Otherwise,
sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
routine is part of the pointer passing interface added for SQLite 3.20.0.

The sqlite3_value_type(V) interface returns the
datatype code for the initial datatype of the
sqlite3_value object V. The returned value is one of SQLITE_INTEGER,
SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.
Other interfaces might change the datatype for an sqlite3_value object.
For example, if the datatype is initially SQLITE_INTEGER and
sqlite3_value_text(V) is called to extract a text value for that
integer, then subsequent calls to sqlite3_value_type(V) might return
SQLITE_TEXT.  Whether or not a persistent internal datatype conversion
occurs is undefined and may change from one release of SQLite to the next.

The sqlite3_value_numeric_type() interface attempts to apply
numeric affinity to the value.  This means that an attempt is
made to convert the value to an integer or floating point.  If
such a conversion is possible without loss of information (in other
words, if the value is a string that looks like a number)
then the conversion is performed.  Otherwise no conversion occurs.
The datatype after conversion is returned.

Within the xUpdate method of a virtual table, the
sqlite3_value_nochange(X) interface returns true if and only if
the column corresponding to X is unchanged by the UPDATE operation
that the xUpdate method call was invoked to implement and if
and the prior xColumn method call that was invoked to extracted
the value for that column returned without setting a result (probably
because it queried sqlite3_vtab_nochange() and found that the column
was unchanging).  Within an xUpdate method, any value for which
sqlite3_value_nochange(X) is true will in all other respects appear
to be a NULL value.  If sqlite3_value_nochange(X) is invoked anywhere other
than within an xUpdate method call for an UPDATE statement, then
the return value is arbitrary and meaningless.

The sqlite3_value_frombind(X) interface returns non-zero if the
value X originated from one of the sqlite3_bind()
interfaces.  If X comes from an SQL literal value, or a table column,
or an expression, then sqlite3_value_frombind(X) returns zero.

Please pay particular attention to the fact that the pointer returned
from sqlite3_value_blob(), sqlite3_value_text(), or
sqlite3_value_text16() can be invalidated by a subsequent call to
sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text(),
or sqlite3_value_text16().

These routines must be called from the same thread as
the SQL function that supplied the sqlite3_value* parameters.

As long as the input parameter is correct, these routines can only
fail if an out-of-memory error occurs during a format conversion.
Only the following subset of interfaces are subject to out-of-memory
errors:


 sqlite3_value_blob()
 sqlite3_value_text()
 sqlite3_value_text16()
 sqlite3_value_text16le()
 sqlite3_value_text16be()
 sqlite3_value_bytes()
 sqlite3_value_bytes16()


If an out-of-memory error occurs, then the return value from these
routines is the same as if the column had contained an SQL NULL value.
Valid SQL NULL returns can be distinguished from out-of-memory errors
by invoking the sqlite3_errcode() immediately after the suspect
return value is obtained and before any
other SQLite interface is called on the same database connection.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_name()
c2: C API: Return The Schema Name For A Database Connection
c5: c3ref/db_name.html
c4:
The sqlite3_db_name(D,N) interface returns a pointer to the schema name
for the N-th database on database connection D, or a NULL pointer of N is
out of range.  An N value of 0 means the main database file.  An N of 1 is
the "temp" schema.  Larger values of N correspond to various ATTACH-ed
databases.

Space to hold the string that is returned by sqlite3_db_name() is managed
by SQLite itself.  The string might be deallocated by any operation that
changes the schema, including ATTACH or DETACH or calls to
sqlite3_serialize() or sqlite3_deserialize(), even operations that
occur on a different thread.  Applications that need to
remember the string long-term should make their own copy.  Applications that
are accessing the same database connection simultaneously on multiple
threads should mutex-protect calls to this API and should make their own
private copy of the result prior to releasing the mutex.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_VERSION, SQLITE_VERSION_NUMBER, SQLITE_SOURCE_ID
c2: C API: Compile-Time Library Version Numbers
c5: c3ref/c_source_id.html
c4:
The SQLITE_VERSION C preprocessor macro in the sqlite3.h header
evaluates to a string literal that is the SQLite version in the
format "X.Y.Z" where X is the major version number (always 3 for
SQLite3) and Y is the minor version number and Z is the release number.
The SQLITE_VERSION_NUMBER C preprocessor macro resolves to an integer
with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
numbers used in SQLITE_VERSION.
The SQLITE_VERSION_NUMBER for any given release of SQLite will also
be larger than the release from which it is derived.  Either Y will
be held constant and Z will be incremented or else Y will be incremented
and Z will be reset to zero.

Since version 3.6.18 (2009-09-11),
SQLite source code has been stored in the
Fossil configuration management
system.  The SQLITE_SOURCE_ID macro evaluates to
a string which identifies a particular check-in of SQLite
within its configuration management system.  The SQLITE_SOURCE_ID
string contains the date and time of the check-in (UTC) and a SHA1
or SHA3-256 hash of the entire source tree.  If the source code has
been edited in any way since it was last checked in, then the last
four hexadecimal digits of the hash may be modified.

See also: sqlite3_libversion(),
sqlite3_libversion_number(), sqlite3_sourceid(),
sqlite_version() and sqlite_source_id().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_release_memory()
c2: C API: Free Memory Used By A Database Connection
c5: c3ref/db_release_memory.html
c4:
The sqlite3_db_release_memory(D) interface attempts to free as much heap
memory as possible from database connection D. Unlike the
sqlite3_release_memory() interface, this interface is in effect even
when the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option is
omitted.

See also: sqlite3_release_memory()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_WIN32_DATA_DIRECTORY_TYPE, SQLITE_WIN32_TEMP_DIRECTORY_TYPE
c2: C API: Win32 Directory Types
c5: c3ref/c_win32_data_directory_type.html
c4:
These macros are only available on Windows.  They define the allowed values
for the type argument to the sqlite3_win32_set_directory interface.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_context
c2: C API: SQL Function Context Object
c5: c3ref/context.html
c4:
The context in which an SQL function executes is stored in an
sqlite3_context object.  A pointer to an sqlite3_context object
is always first parameter to application-defined SQL functions.
The application-defined SQL function implementation will pass this
pointer through into calls to sqlite3_result(),
sqlite3_aggregate_context(), sqlite3_user_data(),
sqlite3_context_db_handle(), sqlite3_get_auxdata(),
and/or sqlite3_set_auxdata().
26 Methods using this object:


sqlite3_aggregate_context
sqlite3_context_db_handle
sqlite3_get_auxdata
sqlite3_result_blob
sqlite3_result_blob64
sqlite3_result_double
sqlite3_result_error
sqlite3_result_error16
sqlite3_result_error_code
sqlite3_result_error_nomem
sqlite3_result_error_toobig
sqlite3_result_int
sqlite3_result_int64
sqlite3_result_null
sqlite3_result_pointer
sqlite3_result_subtype
sqlite3_result_text
sqlite3_result_text16
sqlite3_result_text16be
sqlite3_result_text16le
sqlite3_result_text64
sqlite3_result_value
sqlite3_result_zeroblob
sqlite3_result_zeroblob64
sqlite3_set_auxdata
sqlite3_user_data



See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Virtual Table Constraint Operator Codes
c5: c3ref/c_index_constraint_eq.html
c0:
SQLITE_INDEX_CONSTRAINT_EQ, SQLITE_INDEX_CONSTRAINT_GT, SQLITE_INDEX_CONSTRAINT_LE, SQLITE_INDEX_CONSTRAINT_LT, SQLITE_INDEX_CONSTRAINT_GE, SQLITE_INDEX_CONSTRAINT_MATCH, SQLITE_INDEX_CONSTRAINT_LIKE, SQLITE_INDEX_CONSTRAINT_GLOB, SQLITE_INDEX_CONSTRAINT_REGEXP, SQLITE_INDEX_CONSTRAINT_NE, SQLITE_INDEX_CONSTRAINT_ISNOT, SQLITE_INDEX_CONSTRAINT_ISNOTNULL, SQLITE_INDEX_CONSTRAINT_ISNULL, SQLITE_INDEX_CONSTRAINT_IS, SQLITE_INDEX_CONSTRAINT_LIMIT, SQLITE_INDEX_CONSTRAINT_OFFSET, SQLITE_INDEX_CONSTRAINT_FUNCTION

c4:
These macros define the allowed values for the
sqlite3_index_info.aConstraint[].op field.  Each value represents
an operator that is part of a constraint term in the WHERE clause of
a query that uses a virtual table.

The left-hand operand of the operator is given by the corresponding
aConstraint[].iColumn field.  An iColumn of -1 indicates the left-hand
operand is the rowid.
The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
operators have no left-hand operand, and so for those operators the
corresponding aConstraint[].iColumn is meaningless and should not be
used.

All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
value 255 are reserved to represent functions that are overloaded
by the xFindFunction method of the virtual table
implementation.

The right-hand operands for each constraint might be accessible using
the sqlite3_vtab_rhs_value() interface.  Usually the right-hand
operand is only available if it appears as a single constant literal
in the input SQL.  If the right-hand operand is another column or an
expression (even a constant expression) or a parameter, then the
sqlite3_vtab_rhs_value() probably will not be able to extract it.
The SQLITE_INDEX_CONSTRAINT_ISNULL and
SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
and hence calls to sqlite3_vtab_rhs_value() for those operators will
always return SQLITE_NOTFOUND.

The collating sequence to be used for comparison can be found using
the sqlite3_vtab_collation() interface.  For most real-world virtual
tables, the collating sequence of constraints does not matter (for example
because the constraints are numeric) and so the sqlite3_vtab_collation()
interface is not commonly needed.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_stmt_busy()
c2: C API: Determine If A Prepared Statement Has Been Reset
c5: c3ref/stmt_busy.html
c4:
The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
prepared statement S has been stepped at least once using
sqlite3_step(S) but has neither run to completion (returned
SQLITE_DONE from sqlite3_step(S)) nor
been reset using sqlite3_reset(S).  The sqlite3_stmt_busy(S)
interface returns false if S is a NULL pointer.  If S is not a
NULL pointer and is not a pointer to a valid prepared statement
object, then the behavior is undefined and probably undesirable.

This interface can be used in combination sqlite3_next_stmt()
to locate all prepared statements associated with a database
connection that are in need of being reset.  This can be used,
for example, in diagnostic routines to search for prepared
statements that are holding a transaction open.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_update_hook()
c2: C API: Data Change Notification Callbacks
c5: c3ref/update_hook.html
c4:
The sqlite3_update_hook() interface registers a callback function
with the database connection identified by the first argument
to be invoked whenever a row is updated, inserted or deleted in
a rowid table.
Any callback set by a previous call to this function
for the same database connection is overridden.

The second argument is a pointer to the function to invoke when a
row is updated, inserted or deleted in a rowid table.
The first argument to the callback is a copy of the third argument
to sqlite3_update_hook().
The second callback argument is one of SQLITE_INSERT, SQLITE_DELETE,
or SQLITE_UPDATE, depending on the operation that caused the callback
to be invoked.
The third and fourth arguments to the callback contain pointers to the
database and table name containing the affected row.
The final callback parameter is the rowid of the row.
In the case of an update, this is the rowid after the update takes place.

The update hook is not invoked when internal system tables are
modified (i.e. sqlite_sequence).
The update hook is not invoked when WITHOUT ROWID tables are modified.

In the current implementation, the update hook
is not invoked when conflicting rows are deleted because of an
ON CONFLICT REPLACE clause.  Nor is the update hook
invoked when rows are deleted using the truncate optimization.
The exceptions defined in this paragraph might change in a future
release of SQLite.

Whether the update hook is invoked before or after the
corresponding change is currently unspecified and may differ
depending on the type of change. Do not rely on the order of the
hook call with regards to the final result of the operation which
triggers the hook.

The update hook implementation must not do anything that will modify
the database connection that invoked the update hook.  Any actions
to modify the database connection must be deferred until after the
completion of the sqlite3_step() call that triggered the update hook.
Note that sqlite3_prepare_v2() and sqlite3_step() both modify their
database connections for the meaning of "modify" in this paragraph.

The sqlite3_update_hook(D,C,P) function
returns the P argument from the previous call
on the same database connection D, or NULL for
the first call on D.

See also the sqlite3_commit_hook(), sqlite3_rollback_hook(),
and sqlite3_preupdate_hook() interfaces.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Standard File Control Opcodes
c5: c3ref/c_fcntl_begin_atomic_write.html
c0:
SQLITE_FCNTL_LOCKSTATE, SQLITE_FCNTL_GET_LOCKPROXYFILE, SQLITE_FCNTL_SET_LOCKPROXYFILE, SQLITE_FCNTL_LAST_ERRNO, SQLITE_FCNTL_SIZE_HINT, SQLITE_FCNTL_CHUNK_SIZE, SQLITE_FCNTL_FILE_POINTER, SQLITE_FCNTL_SYNC_OMITTED, SQLITE_FCNTL_WIN32_AV_RETRY, SQLITE_FCNTL_PERSIST_WAL, SQLITE_FCNTL_OVERWRITE, SQLITE_FCNTL_VFSNAME, SQLITE_FCNTL_POWERSAFE_OVERWRITE, SQLITE_FCNTL_PRAGMA, SQLITE_FCNTL_BUSYHANDLER, SQLITE_FCNTL_TEMPFILENAME, SQLITE_FCNTL_MMAP_SIZE, SQLITE_FCNTL_TRACE, SQLITE_FCNTL_HAS_MOVED, SQLITE_FCNTL_SYNC, SQLITE_FCNTL_COMMIT_PHASETWO, SQLITE_FCNTL_WIN32_SET_HANDLE, SQLITE_FCNTL_WAL_BLOCK, SQLITE_FCNTL_ZIPVFS, SQLITE_FCNTL_RBU, SQLITE_FCNTL_VFS_POINTER, SQLITE_FCNTL_JOURNAL_POINTER, SQLITE_FCNTL_WIN32_GET_HANDLE, SQLITE_FCNTL_PDB, SQLITE_FCNTL_BEGIN_ATOMIC_WRITE, SQLITE_FCNTL_COMMIT_ATOMIC_WRITE, SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE, SQLITE_FCNTL_LOCK_TIMEOUT, SQLITE_FCNTL_DATA_VERSION, SQLITE_FCNTL_SIZE_LIMIT, SQLITE_FCNTL_CKPT_DONE, SQLITE_FCNTL_RESERVE_BYTES, SQLITE_FCNTL_CKPT_START, SQLITE_FCNTL_EXTERNAL_READER, SQLITE_FCNTL_CKSM_FILE, SQLITE_FCNTL_RESET_CACHE

c4:
These integer constants are opcodes for the xFileControl method
of the sqlite3_io_methods object and for the sqlite3_file_control()
interface.




The SQLITE_FCNTL_LOCKSTATE opcode is used for debugging.  This
opcode causes the xFileControl method to write the current state of
the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED,
SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE)
into an integer that the pArg argument points to.
This capability is only available if SQLite is compiled with SQLITE_DEBUG.



The SQLITE_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS
layer a hint of how large the database file will grow to be during the
current transaction.  This hint is not guaranteed to be accurate but it
is often close.  The underlying VFS might choose to preallocate database
file space based on this hint in order to help writes to the database
file run faster.



The SQLITE_FCNTL_SIZE_LIMIT opcode is used by in-memory VFS that
implements sqlite3_deserialize() to set an upper bound on the size
of the in-memory database.  The argument is a pointer to a sqlite3_int64.
If the integer pointed to is negative, then it is filled in with the
current limit.  Otherwise the limit is set to the larger of the value
of the integer pointed to and the current database size.  The integer
pointed to is set to the new limit.



The SQLITE_FCNTL_CHUNK_SIZE opcode is used to request that the VFS
extends and truncates the database file in chunks of a size specified
by the user. The fourth argument to sqlite3_file_control() should
point to an integer (type int) containing the new chunk-size to use
for the nominated database. Allocating database file space in large
chunks (say 1MB at a time), may reduce file-system fragmentation and
improve performance on some systems.



The SQLITE_FCNTL_FILE_POINTER opcode is used to obtain a pointer
to the sqlite3_file object associated with a particular database
connection.  See also SQLITE_FCNTL_JOURNAL_POINTER.



The SQLITE_FCNTL_JOURNAL_POINTER opcode is used to obtain a pointer
to the sqlite3_file object associated with the journal file (either
the rollback journal or the write-ahead log) for a particular database
connection.  See also SQLITE_FCNTL_FILE_POINTER.



No longer in use.



The SQLITE_FCNTL_SYNC opcode is generated internally by SQLite and
sent to the VFS immediately before the xSync method is invoked on a
database file descriptor. Or, if the xSync method is not invoked
because the user has configured SQLite with
PRAGMA synchronous=OFF it is invoked in place
of the xSync method. In most cases, the pointer argument passed with
this file-control is NULL. However, if the database file is being synced
as part of a multi-database commit, the argument points to a nul-terminated
string containing the transactions super-journal file name. VFSes that
do not need this signal should silently ignore this opcode. Applications
should not call sqlite3_file_control() with this opcode as doing so may
disrupt the operation of the specialized VFSes that do require it.



The SQLITE_FCNTL_COMMIT_PHASETWO opcode is generated internally by SQLite
and sent to the VFS after a transaction has been committed immediately
but before the database is unlocked. VFSes that do not need this signal
should silently ignore this opcode. Applications should not call
sqlite3_file_control() with this opcode as doing so may disrupt the
operation of the specialized VFSes that do require it.



The SQLITE_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic
retry counts and intervals for certain disk I/O operations for the
windows VFS in order to provide robustness in the presence of
anti-virus programs.  By default, the windows VFS will retry file read,
file write, and file delete operations up to 10 times, with a delay
of 25 milliseconds before the first retry and with the delay increasing
by an additional 25 milliseconds with each subsequent retry.  This
opcode allows these two values (10 retries and 25 milliseconds of delay)
to be adjusted.  The values are changed for all database connections
within the same process.  The argument is a pointer to an array of two
integers where the first integer is the new retry count and the second
integer is the delay.  If either integer is negative, then the setting
is not changed but instead the prior value of that setting is written
into the array entry, allowing the current retry settings to be
interrogated.  The zDbName parameter is ignored.



The SQLITE_FCNTL_PERSIST_WAL opcode is used to set or query the
persistent Write Ahead Log setting.  By default, the auxiliary
write ahead log (WAL file) and shared memory
files used for transaction control
are automatically deleted when the latest connection to the database
closes.  Setting persistent WAL mode causes those files to persist after
close.  Persisting the files is useful when other processes that do not
have write permission on the directory containing the database file want
to read the database file, as the WAL and shared memory files must exist
in order for the database to be readable.  The fourth parameter to
sqlite3_file_control() for this opcode should be a pointer to an integer.
That integer is 0 to disable persistent WAL mode or 1 to enable persistent
WAL mode.  If the integer is -1, then it is overwritten with the current
WAL persistence setting.



The SQLITE_FCNTL_POWERSAFE_OVERWRITE opcode is used to set or query the
persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
determines the SQLITE_IOCAP_POWERSAFE_OVERWRITE bit of the
xDeviceCharacteristics methods. The fourth parameter to
sqlite3_file_control() for this opcode should be a pointer to an integer.
That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
mode.  If the integer is -1, then it is overwritten with the current
zero-damage mode setting.



The SQLITE_FCNTL_OVERWRITE opcode is invoked by SQLite after opening
a write transaction to indicate that, unless it is rolled back for some
reason, the entire database file will be overwritten by the current
transaction. This is used by VACUUM operations.



The SQLITE_FCNTL_VFSNAME opcode can be used to obtain the names of
all VFSes in the VFS stack.  The names are of all VFS shims and the
final bottom-level VFS are written into memory obtained from
sqlite3_malloc() and the result is stored in the char* variable
that the fourth parameter of sqlite3_file_control() points to.
The caller is responsible for freeing the memory when done.  As with
all file-control actions, there is no guarantee that this will actually
do anything.  Callers should initialize the char* variable to a NULL
pointer in case this file-control is not implemented.  This file-control
is intended for diagnostic use only.



The SQLITE_FCNTL_VFS_POINTER opcode finds a pointer to the top-level
VFSes currently in use.  The argument X in
sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
of type "sqlite3_vfs **".  This opcodes will set *X
to a pointer to the top-level VFS.
When there are multiple VFS shims in the stack, this opcode finds the
upper-most shim only.



Whenever a PRAGMA statement is parsed, an SQLITE_FCNTL_PRAGMA
file control is sent to the open sqlite3_file object corresponding
to the database file to which the pragma statement refers. The argument
to the SQLITE_FCNTL_PRAGMA file control is an array of
pointers to strings (char**) in which the second element of the array
is the name of the pragma and the third element is the argument to the
pragma or NULL if the pragma has no argument.  The handler for an
SQLITE_FCNTL_PRAGMA file control can optionally make the first element
of the char** argument point to a string obtained from sqlite3_mprintf()
or the equivalent and that string will become the result of the pragma or
the error message if the pragma fails. If the
SQLITE_FCNTL_PRAGMA file control returns SQLITE_NOTFOUND, then normal
PRAGMA processing continues.  If the SQLITE_FCNTL_PRAGMA
file control returns SQLITE_OK, then the parser assumes that the
VFS has handled the PRAGMA itself and the parser generates a no-op
prepared statement if result string is NULL, or that returns a copy
of the result string if the string is non-NULL.
If the SQLITE_FCNTL_PRAGMA file control returns
any result code other than SQLITE_OK or SQLITE_NOTFOUND, that means
that the VFS encountered an error while handling the PRAGMA and the
compilation of the PRAGMA fails with an error.  The SQLITE_FCNTL_PRAGMA
file control occurs at the beginning of pragma statement analysis and so
it is able to override built-in PRAGMA statements.



The SQLITE_FCNTL_BUSYHANDLER
file-control may be invoked by SQLite on the database file handle
shortly after it is opened in order to provide a custom VFS with access
to the connection's busy-handler callback. The argument is of type (void**)
- an array of two (void *) values. The first (void *) actually points
to a function of type (int (*)(void *)). In order to invoke the connection's
busy-handler, this function should be invoked with the second (void *) in
the array as the only argument. If it returns non-zero, then the operation
should be retried. If it returns zero, the custom VFS should abandon the
current operation.



Applications can invoke the SQLITE_FCNTL_TEMPFILENAME file-control
to have SQLite generate a
temporary filename using the same algorithm that is followed to generate
temporary filenames for TEMP tables and other internal uses.  The
argument should be a char** which will be filled with the filename
written into memory obtained from sqlite3_malloc().  The caller should
invoke sqlite3_free() on the result to avoid a memory leak.



The SQLITE_FCNTL_MMAP_SIZE file control is used to query or set the
maximum number of bytes that will be used for memory-mapped I/O.
The argument is a pointer to a value of type sqlite3_int64 that
is an advisory maximum number of bytes in the file to memory map.  The
pointer is overwritten with the old value.  The limit is not changed if
the value originally pointed to is negative, and so the current limit
can be queried by passing in a pointer to a negative number.  This
file-control is used internally to implement PRAGMA mmap_size.



The SQLITE_FCNTL_TRACE file control provides advisory information
to the VFS about what the higher layers of the SQLite stack are doing.
This file control is used by some VFS activity tracing shims.
The argument is a zero-terminated string.  Higher layers in the
SQLite stack may generate instances of this file control if
the SQLITE_USE_FCNTL_TRACE compile-time option is enabled.



The SQLITE_FCNTL_HAS_MOVED file control interprets its argument as a
pointer to an integer and it writes a boolean into that integer depending
on whether or not the file has been renamed, moved, or deleted since it
was first opened.



The SQLITE_FCNTL_WIN32_GET_HANDLE opcode can be used to obtain the
underlying native file handle associated with a file handle.  This file
control interprets its argument as a pointer to a native file handle and
writes the resulting value there.



The SQLITE_FCNTL_WIN32_SET_HANDLE opcode is used for debugging.  This
opcode causes the xFileControl method to swap the file handle with the one
pointed to by the pArg argument.  This capability is used during testing
and only needs to be supported when SQLITE_TEST is defined.



The SQLITE_FCNTL_WAL_BLOCK is a signal to the VFS layer that it might
be advantageous to block on the next WAL lock if the lock is not immediately
available.  The WAL subsystem issues this signal during rare
circumstances in order to fix a problem with priority inversion.
Applications should not use this file-control.



The SQLITE_FCNTL_ZIPVFS opcode is implemented by zipvfs only. All other
VFS should return SQLITE_NOTFOUND for this opcode.



The SQLITE_FCNTL_RBU opcode is implemented by the special VFS used by
the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
this opcode.



If the SQLITE_FCNTL_BEGIN_ATOMIC_WRITE opcode returns SQLITE_OK, then
the file descriptor is placed in "batch write mode", which
means all subsequent write operations will be deferred and done
atomically at the next SQLITE_FCNTL_COMMIT_ATOMIC_WRITE.  Systems
that do not support batch atomic writes will return SQLITE_NOTFOUND.
Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
the closing SQLITE_FCNTL_COMMIT_ATOMIC_WRITE or
SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE, SQLite will make
no VFS interface calls on the same sqlite3_file file descriptor
except for calls to the xWrite method and the xFileControl method
with SQLITE_FCNTL_SIZE_HINT.



The SQLITE_FCNTL_COMMIT_ATOMIC_WRITE opcode causes all write
operations since the previous successful call to
SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to be performed atomically.
This file control returns SQLITE_OK if and only if the writes were
all performed successfully and have been committed to persistent storage.
Regardless of whether or not it is successful, this file control takes
the file descriptor out of batch write mode so that all subsequent
write operations are independent.
SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
a prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.



The SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE opcode causes all write
operations since the previous successful call to
SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to be rolled back.
This file control takes the file descriptor out of batch write mode
so that all subsequent write operations are independent.
SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
a prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.



The SQLITE_FCNTL_LOCK_TIMEOUT opcode is used to configure a VFS
to block for up to M milliseconds before failing when attempting to
obtain a file lock using the xLock or xShmLock methods of the VFS.
The parameter is a pointer to a 32-bit signed integer that contains
the value that M is to be set to. Before returning, the 32-bit signed
integer is overwritten with the previous value of M.



The SQLITE_FCNTL_DATA_VERSION opcode is used to detect changes to
a database file.  The argument is a pointer to a 32-bit unsigned integer.
The "data version" for the pager is written into the pointer.  The
"data version" changes whenever any change occurs to the corresponding
database file, either through SQL statements on the same database
connection or through transactions committed by separate database
connections possibly in other processes. The sqlite3_total_changes()
interface can be used to find if any database on the connection has changed,
but that interface responds to changes on TEMP as well as MAIN and does
not provide a mechanism to detect changes to MAIN only.  Also, the
sqlite3_total_changes() interface responds to internal changes only and
omits changes made by other database connections.  The
PRAGMA data_version command provides a mechanism to detect changes to
a single attached database that occur due to other database connections,
but omits changes implemented by the database connection on which it is
called.  This file control is the only mechanism to detect changes that
happen either internally or externally and that are associated with
a particular attached database.



The SQLITE_FCNTL_CKPT_START opcode is invoked from within a checkpoint
in wal mode before the client starts to copy pages from the wal
file to the database file.



The SQLITE_FCNTL_CKPT_DONE opcode is invoked from within a checkpoint
in wal mode after the client has finished copying pages from the wal
file to the database file, but before the *-shm file is updated to
record the fact that the pages have been checkpointed.



The EXPERIMENTAL SQLITE_FCNTL_EXTERNAL_READER opcode is used to detect
whether or not there is a database client in another process with a wal-mode
transaction open on the database or not. It is only available on unix.The
(void*) argument passed with this file-control should be a pointer to a
value of type (int). The integer value is set to 1 if the database is a wal
mode database and there exists at least one client in another process that
currently has an SQL transaction open on the database. It is set to 0 if
the database is not a wal-mode db, or if there is no such connection in any
other process. This opcode cannot be used to detect transactions opened
by clients within the current process, only within other processes.



The SQLITE_FCNTL_CKSM_FILE opcode is for use internally by the
checksum VFS shim only.



If there is currently no transaction open on the database, and the
database is not a temp db, then the SQLITE_FCNTL_RESET_CACHE file-control
purges the contents of the in-memory page cache. If there is an open
transaction, or if the db is a temp-db, this opcode is a no-op, not an error.

See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_commit_hook(), sqlite3_rollback_hook()
c2: C API: Commit And Rollback Notification Callbacks
c5: c3ref/commit_hook.html
c4:
The sqlite3_commit_hook() interface registers a callback
function to be invoked whenever a transaction is committed.
Any callback set by a previous call to sqlite3_commit_hook()
for the same database connection is overridden.
The sqlite3_rollback_hook() interface registers a callback
function to be invoked whenever a transaction is rolled back.
Any callback set by a previous call to sqlite3_rollback_hook()
for the same database connection is overridden.
The pArg argument is passed through to the callback.
If the callback on a commit hook function returns non-zero,
then the commit is converted into a rollback.

The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
return the P argument from the previous call of the same function
on the same database connection D, or NULL for
the first call for each function on D.

The commit and rollback hook callbacks are not reentrant.
The callback implementation must not do anything that will modify
the database connection that invoked the callback.  Any actions
to modify the database connection must be deferred until after the
completion of the sqlite3_step() call that triggered the commit
or rollback hook in the first place.
Note that running any other SQL statements, including SELECT statements,
or merely calling sqlite3_prepare_v2() and sqlite3_step() will modify
the database connections for the meaning of "modify" in this paragraph.

Registering a NULL function disables the callback.

When the commit hook callback routine returns zero, the COMMIT
operation is allowed to continue normally.  If the commit hook
returns non-zero, then the COMMIT is converted into a ROLLBACK.
The rollback hook is invoked on a rollback that results from a commit
hook returning non-zero, just as it would be with any other rollback.

For the purposes of this API, a transaction is said to have been
rolled back if an explicit "ROLLBACK" statement is executed, or
an error or constraint causes an implicit rollback to occur.
The rollback callback is not invoked if a transaction is
automatically rolled back because the database connection is closed.

See also the sqlite3_update_hook() interface.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_syscall_ptr(), struct sqlite3_vfs
c2: C API: OS Interface Object
c5: c3ref/vfs.html
c4:
An instance of the sqlite3_vfs object defines the interface between
the SQLite core and the underlying operating system.  The "vfs"
in the name of the object stands for "virtual file system".  See
the VFS documentation for further information.

The VFS interface is sometimes extended by adding new methods onto
the end.  Each time such an extension occurs, the iVersion field
is incremented.  The iVersion value started out as 1 in
SQLite version 3.5.0 on 2007-09-04, then increased to 2
with SQLite version 3.7.0 on 2010-07-21, and then increased
to 3 with SQLite version 3.7.6 on 2011-04-12.  Additional fields
may be appended to the sqlite3_vfs object and the iVersion value
may increase again in future versions of SQLite.
Note that due to an oversight, the structure
of the sqlite3_vfs object changed in the transition from
SQLite version 3.5.9 to version 3.6.0 on 2008-07-16
and yet the iVersion field was not increased.

The szOsFile field is the size of the subclassed sqlite3_file
structure used by this VFS.  mxPathname is the maximum length of
a pathname in this VFS.

Registered sqlite3_vfs objects are kept on a linked list formed by
the pNext pointer.  The sqlite3_vfs_register()
and sqlite3_vfs_unregister() interfaces manage this list
in a thread-safe way.  The sqlite3_vfs_find() interface
searches the list.  Neither the application code nor the VFS
implementation should use the pNext pointer.

The pNext field is the only field in the sqlite3_vfs
structure that SQLite will ever modify.  SQLite will only access
or modify this field while holding a particular static mutex.
The application should never modify anything within the sqlite3_vfs
object once the object has been registered.

The zName field holds the name of the VFS module.  The name must
be unique across all VFS modules.



SQLite guarantees that the zFilename parameter to xOpen
is either a NULL pointer or string obtained
from xFullPathname() with an optional suffix added.
If a suffix is added to the zFilename parameter, it will
consist of a single "-" character followed by no more than
11 alphanumeric and/or "-" characters.
SQLite further guarantees that
the string will be valid and unchanged until xClose() is
called. Because of the previous sentence,
the sqlite3_file can safely store a pointer to the
filename if it needs to remember the filename for some reason.
If the zFilename parameter to xOpen is a NULL pointer then xOpen
must invent its own temporary name for the file.  Whenever the
xFilename parameter is NULL it will also be the case that the
flags parameter will include SQLITE_OPEN_DELETEONCLOSE.

The flags argument to xOpen() includes all bits set in
the flags argument to sqlite3_open_v2().  Or if sqlite3_open()
or sqlite3_open16() is used, then flags includes at least
SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
If xOpen() opens a file read-only then it sets *pOutFlags to
include SQLITE_OPEN_READONLY.  Other bits in *pOutFlags may be set.

SQLite will also add one of the following flags to the xOpen()
call, depending on the object being opened:


  SQLITE_OPEN_MAIN_DB
  SQLITE_OPEN_MAIN_JOURNAL
  SQLITE_OPEN_TEMP_DB
  SQLITE_OPEN_TEMP_JOURNAL
  SQLITE_OPEN_TRANSIENT_DB
  SQLITE_OPEN_SUBJOURNAL
  SQLITE_OPEN_SUPER_JOURNAL
  SQLITE_OPEN_WAL


The file I/O implementation can use the object type flags to
change the way it deals with files.  For example, an application
that does not care about crash recovery or rollback might make
the open of a journal file a no-op.  Writes to this journal would
also be no-ops, and any attempt to read the journal would return
SQLITE_IOERR.  Or the implementation might recognize that a database
file will be doing page-aligned sector reads and writes in a random
order and set up its I/O subsystem accordingly.

SQLite might also add one of the following flags to the xOpen method:


 SQLITE_OPEN_DELETEONCLOSE
 SQLITE_OPEN_EXCLUSIVE


The SQLITE_OPEN_DELETEONCLOSE flag means the file should be
deleted when it is closed.  The SQLITE_OPEN_DELETEONCLOSE
will be set for TEMP databases and their journals, transient
databases, and subjournals.

The SQLITE_OPEN_EXCLUSIVE flag is always used in conjunction
with the SQLITE_OPEN_CREATE flag, which are both directly
analogous to the O_EXCL and O_CREAT flags of the POSIX open()
API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
SQLITE_OPEN_CREATE, is used to indicate that file should always
be created, and that it is an error if it already exists.
It is not used to indicate the file should be opened
for exclusive access.

At least szOsFile bytes of memory are allocated by SQLite
to hold the sqlite3_file structure passed as the third
argument to xOpen.  The xOpen method does not have to
allocate the structure; it should just fill it in.  Note that
the xOpen method must set the sqlite3_file.pMethods to either
a valid sqlite3_io_methods object or to NULL.  xOpen must do
this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
element will be valid after xOpen returns regardless of the success
or failure of the xOpen call.



The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS
to test for the existence of a file, or SQLITE_ACCESS_READWRITE to
test whether a file is readable and writable, or SQLITE_ACCESS_READ
to test whether a file is at least readable.  The SQLITE_ACCESS_READ
flag is never actually used and is not implemented in the built-in
VFSes of SQLite.  The file is named by the second argument and can be a
directory. The xAccess method returns SQLITE_OK on success or some
non-zero error code if there is an I/O error or if the name of
the file given in the second argument is illegal.  If SQLITE_OK
is returned, then non-zero or zero is written into *pResOut to indicate
whether or not the file is accessible.

SQLite will always allocate at least mxPathname+1 bytes for the
output buffer xFullPathname.  The exact size of the output buffer
is also passed as a parameter to both  methods. If the output buffer
is not large enough, SQLITE_CANTOPEN should be returned. Since this is
handled as a fatal error by SQLite, vfs implementations should endeavor
to prevent this by setting mxPathname to a sufficiently large value.

The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
interfaces are not strictly a part of the filesystem, but they are
included in the VFS structure for completeness.
The xRandomness() function attempts to return nBytes bytes
of good-quality randomness into zOut.  The return value is
the actual number of bytes of randomness obtained.
The xSleep() method causes the calling thread to sleep for at
least the number of microseconds given.  The xCurrentTime()
method returns a Julian Day Number for the current date and time as
a floating point value.
The xCurrentTimeInt64() method returns, as an integer, the Julian
Day Number multiplied by 86400000 (the number of milliseconds in
a 24-hour day).
SQLite will use the xCurrentTimeInt64() method to get the current
date and time if that method is available (if iVersion is 2 or
greater and the function pointer is not NULL) and will fall back
to xCurrentTime() if xCurrentTimeInt64() is unavailable.

The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
are not used by the SQLite core.  These optional interfaces are provided
by some VFSes to facilitate testing of the VFS code. By overriding
system calls with functions under its control, a test program can
simulate faults and error conditions that would otherwise be difficult
or impossible to induce.  The set of system calls that can be overridden
varies from one VFS to another, and from one version of the same VFS to the
next.  Applications that use these interfaces must be prepared for any
or all of these interfaces to be NULL or for their behavior to change
from one release to the next.  Applications must not attempt to access
any of these methods if the iVersion of the VFS is less than 3.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_value_subtype()
c2: C API: Finding The Subtype Of SQL Values
c5: c3ref/value_subtype.html
c4:
The sqlite3_value_subtype(V) function returns the subtype for
an application-defined SQL function argument V.  The subtype
information can be used to pass a limited amount of context from
one SQL function to another.  Use the sqlite3_result_subtype()
routine to set the subtype for the return value of an SQL function.

Every application-defined SQL function that invoke this interface
should include the SQLITE_SUBTYPE property in the text
encoding argument when the function is registered.
If the SQLITE_SUBTYPE property is omitted, then sqlite3_value_subtype()
might return zero instead of the upstream subtype in some corner cases.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_last_insert_rowid()
c2: C API: Last Insert Rowid
c5: c3ref/last_insert_rowid.html
c4:
Each entry in most SQLite tables (except for WITHOUT ROWID tables)
has a unique 64-bit signed
integer key called the "rowid". The rowid is always available
as an undeclared column named ROWID, OID, or _ROWID_ as long as those
names are not also used by explicitly declared columns. If
the table has a column of type INTEGER PRIMARY KEY then that column
is another alias for the rowid.

The sqlite3_last_insert_rowid(D) interface usually returns the rowid of
the most recent successful INSERT into a rowid table or virtual table
on database connection D. Inserts into WITHOUT ROWID tables are not
recorded. If no successful INSERTs into rowid tables have ever occurred
on the database connection D, then sqlite3_last_insert_rowid(D) returns
zero.

As well as being set automatically as rows are inserted into database
tables, the value returned by this function may be set explicitly by
sqlite3_set_last_insert_rowid()

Some virtual table implementations may INSERT rows into rowid tables as
part of committing a transaction (e.g. to flush data accumulated in memory
to disk). In this case subsequent calls to this function return the rowid
associated with these internal INSERT operations, which leads to
unintuitive results. Virtual table implementations that do write to rowid
tables in this way can avoid this problem by restoring the original
rowid value using sqlite3_set_last_insert_rowid() before returning
control to the user.

If an INSERT occurs within a trigger then this routine will
return the rowid of the inserted row as long as the trigger is
running. Once the trigger program ends, the value returned
by this routine reverts to what it was before the trigger was fired.

An INSERT that fails due to a constraint violation is not a
successful INSERT and does not change the value returned by this
routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
and INSERT OR ABORT make no changes to the return value of this
routine when their insertion fails.  When INSERT OR REPLACE
encounters a constraint violation, it does not fail.  The
INSERT continues to completion after deleting rows that caused
the constraint problem so INSERT OR REPLACE will always change
the return value of this interface.

For the purposes of this routine, an INSERT is considered to
be successful even if it is subsequently rolled back.

This function is accessible to SQL statements via the
last_insert_rowid() SQL function.

If a separate thread performs a new INSERT on the same
database connection while the sqlite3_last_insert_rowid()
function is running and thus changes the last insert rowid,
then the value returned by sqlite3_last_insert_rowid() is
unpredictable and might not equal either the old or the new
last insert rowid.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Name Of The Folder Holding Database Files
c5: c3ref/data_directory.html
c4:
If this global variable is made to point to a string which is
the name of a folder (a.k.a. directory), then all database files
specified with a relative pathname and created or accessed by
SQLite when using a built-in windows VFS will be assumed
to be relative to that directory. If this variable is a NULL
pointer, then SQLite assumes that all database files specified
with a relative pathname are relative to the current directory
for the process.  Only the windows VFS makes use of this global
variable; it is ignored by the unix VFS.

Changing the value of this variable while a database connection is
open can result in a corrupt database.

It is not safe to read or modify this variable in more than one
thread at a time.  It is not safe to read or modify this variable
if a database connection is being used at the same time in a separate
thread.
It is intended that this variable be set once
as part of process initialization and before any SQLite interface
routines have been called and that this variable remain unchanged
thereafter.

The data_store_directory pragma may modify this variable and cause
it to point to memory obtained from sqlite3_malloc.  Furthermore,
the data_store_directory pragma always assumes that any string
that this variable points to is held in memory obtained from
sqlite3_malloc and the pragma may attempt to free that memory
using sqlite3_free.
Hence, if this variable is modified directly, either it should be
made NULL or made to point to memory obtained from sqlite3_malloc
or else the use of the data_store_directory pragma should be avoided.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_test_control()
c2: C API: Testing Interface
c5: c3ref/test_control.html
c4:
The sqlite3_test_control() interface is used to read out internal
state of SQLite and to inject faults into SQLite for testing
purposes.  The first parameter is an operation code that determines
the number, meaning, and operation of all subsequent parameters.

This interface is not for use by applications.  It exists solely
for verifying the correct operation of the SQLite library.  Depending
on how the SQLite library is compiled, this interface might not exist.

The details of the operation codes, their meanings, the parameters
they take, and what they do are all subject to change without notice.
Unlike most of the SQLite API, this function is not guaranteed to
operate consistently from one release to the next.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_initialize(), sqlite3_shutdown(), sqlite3_os_init(), sqlite3_os_end()
c2: C API: Initialize The SQLite Library
c5: c3ref/initialize.html
c4:
The sqlite3_initialize() routine initializes the
SQLite library.  The sqlite3_shutdown() routine
deallocates any resources that were allocated by sqlite3_initialize().
These routines are designed to aid in process initialization and
shutdown on embedded systems.  Workstation applications using
SQLite normally do not need to invoke either of these routines.

A call to sqlite3_initialize() is an "effective" call if it is
the first time sqlite3_initialize() is invoked during the lifetime of
the process, or if it is the first time sqlite3_initialize() is invoked
following a call to sqlite3_shutdown().  Only an effective call
of sqlite3_initialize() does any initialization.  All other calls
are harmless no-ops.

A call to sqlite3_shutdown() is an "effective" call if it is the first
call to sqlite3_shutdown() since the last sqlite3_initialize().  Only
an effective call to sqlite3_shutdown() does any deinitialization.
All other valid calls to sqlite3_shutdown() are harmless no-ops.

The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
is not.  The sqlite3_shutdown() interface must only be called from a
single thread.  All open database connections must be closed and all
other SQLite resources must be deallocated prior to invoking
sqlite3_shutdown().

Among other things, sqlite3_initialize() will invoke
sqlite3_os_init().  Similarly, sqlite3_shutdown()
will invoke sqlite3_os_end().

The sqlite3_initialize() routine returns SQLITE_OK on success.
If for some reason, sqlite3_initialize() is unable to initialize
the library (perhaps it is unable to allocate a needed resource such
as a mutex) it returns an error code other than SQLITE_OK.

The sqlite3_initialize() routine is called internally by many other
SQLite interfaces so that an application usually does not need to
invoke sqlite3_initialize() directly.  For example, sqlite3_open()
calls sqlite3_initialize() so the SQLite library will be automatically
initialized when sqlite3_open() is called if it has not be initialized
already.  However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT
compile-time option, then the automatic calls to sqlite3_initialize()
are omitted and the application must call sqlite3_initialize() directly
prior to using any other SQLite interface.  For maximum portability,
it is recommended that applications always invoke sqlite3_initialize()
directly prior to using any other SQLite interface.  Future releases
of SQLite may require this.  In other words, the behavior exhibited
when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the
default behavior in some future release of SQLite.

The sqlite3_os_init() routine does operating-system specific
initialization of the SQLite library.  The sqlite3_os_end()
routine undoes the effect of sqlite3_os_init().  Typical tasks
performed by these routines include allocation or deallocation
of static resources, initialization of global variables,
setting up a default sqlite3_vfs module, or setting up
a default configuration using sqlite3_config().

The application should never invoke either sqlite3_os_init()
or sqlite3_os_end() directly.  The application should only invoke
sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
interface is called automatically by sqlite3_initialize() and
sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
implementations for sqlite3_os_init() and sqlite3_os_end()
are built into SQLite when it is compiled for Unix, Windows, or OS/2.
When built for other platforms
(using the SQLITE_OS_OTHER=1 compile-time
option) the application must supply a suitable implementation for
sqlite3_os_init() and sqlite3_os_end().  An application-supplied
implementation of sqlite3_os_init() or sqlite3_os_end()
must return SQLITE_OK on success and some other error code upon
failure.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_memory_used(), sqlite3_memory_highwater()
c2: C API: Memory Allocator Statistics
c5: c3ref/memory_highwater.html
c4:
SQLite provides these two interfaces for reporting on the status
of the sqlite3_malloc(), sqlite3_free(), and sqlite3_realloc()
routines, which form the built-in memory allocation subsystem.

The sqlite3_memory_used() routine returns the number of bytes
of memory currently outstanding (malloced but not freed).
The sqlite3_memory_highwater() routine returns the maximum
value of sqlite3_memory_used() since the high-water mark
was last reset.  The values returned by sqlite3_memory_used() and
sqlite3_memory_highwater() include any overhead
added by SQLite in its implementation of sqlite3_malloc(),
but not overhead added by the any underlying system library
routines that sqlite3_malloc() may call.

The memory high-water mark is reset to the current value of
sqlite3_memory_used() if and only if the parameter to
sqlite3_memory_highwater() is true.  The value returned
by sqlite3_memory_highwater(1) is the high-water mark
prior to the reset.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_vtab_collation()
c2: C API: Determine The Collation For a Virtual Table Constraint
c5: c3ref/vtab_collation.html
c4:
This function may only be called from within a call to the xBestIndex
method of a virtual table.  This function returns a pointer to a string
that is the name of the appropriate collation sequence to use for text
comparisons on the constraint identified by its arguments.

The first argument must be the pointer to the sqlite3_index_info object
that is the first parameter to the xBestIndex() method. The second argument
must be an index into the aConstraint[] array belonging to the
sqlite3_index_info structure passed to xBestIndex.

Important:
The first parameter must be the same pointer that is passed into the
xBestMethod() method.  The first parameter may not be a pointer to a
different sqlite3_index_info object, even an exact copy.

The return value is computed as follows:


 If the constraint comes from a WHERE clause expression that contains
a COLLATE operator, then the name of the collation specified by
that COLLATE operator is returned.
 If there is no COLLATE operator, but the column that is the subject
of the constraint specifies an alternative collating sequence via
a COLLATE clause on the column definition within the CREATE TABLE
statement that was passed into sqlite3_declare_vtab(), then the
name of that alternative collating sequence is returned.
 Otherwise, "BINARY" is returned.

See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Deprecated Functions
c5: c3ref/aggregate_count.html
c0:
sqlite3_aggregate_count(), sqlite3_expired(), sqlite3_transfer_bindings(), sqlite3_global_recover(), sqlite3_thread_cleanup(), sqlite3_memory_alarm()

c4:
These functions are deprecated.  In order to maintain
backwards compatibility with older code, these functions continue
to be supported.  However, new applications should avoid
the use of these functions.  To encourage programmers to avoid
these functions, we will not explain what they do.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Setting The Result Of An SQL Function
c5: c3ref/result_blob.html
c0:
sqlite3_result_blob(), sqlite3_result_blob64(), sqlite3_result_double(), sqlite3_result_error(), sqlite3_result_error16(), sqlite3_result_error_toobig(), sqlite3_result_error_nomem(), sqlite3_result_error_code(), sqlite3_result_int(), sqlite3_result_int64(), sqlite3_result_null(), sqlite3_result_text(), sqlite3_result_text64(), sqlite3_result_text16(), sqlite3_result_text16le(), sqlite3_result_text16be(), sqlite3_result_value(), sqlite3_result_pointer(), sqlite3_result_zeroblob(), sqlite3_result_zeroblob64()

c4:
These routines are used by the xFunc or xFinal callbacks that
implement SQL functions and aggregates.  See
sqlite3_create_function() and sqlite3_create_function16()
for additional information.

These functions work very much like the parameter binding family of
functions used to bind values to host parameters in prepared statements.
Refer to the SQL parameter documentation for additional information.

The sqlite3_result_blob() interface sets the result from
an application-defined function to be the BLOB whose content is pointed
to by the second parameter and which is N bytes long where N is the
third parameter.

The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
interfaces set the result of the application-defined function to be
a BLOB containing all zero bytes and N bytes in size.

The sqlite3_result_double() interface sets the result from
an application-defined function to be a floating point value specified
by its 2nd argument.

The sqlite3_result_error() and sqlite3_result_error16() functions
cause the implemented SQL function to throw an exception.
SQLite uses the string pointed to by the
2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
as the text of an error message.  SQLite interprets the error
message string from sqlite3_result_error() as UTF-8. SQLite
interprets the string from sqlite3_result_error16() as UTF-16 using
the same byte-order determination rules as sqlite3_bind_text16().
If the third parameter to sqlite3_result_error()
or sqlite3_result_error16() is negative then SQLite takes as the error
message all text up through the first zero character.
If the third parameter to sqlite3_result_error() or
sqlite3_result_error16() is non-negative then SQLite takes that many
bytes (not characters) from the 2nd parameter as the error message.
The sqlite3_result_error() and sqlite3_result_error16()
routines make a private copy of the error message text before
they return.  Hence, the calling function can deallocate or
modify the text after they return without harm.
The sqlite3_result_error_code() function changes the error code
returned by SQLite as a result of an error in a function.  By default,
the error code is SQLITE_ERROR.  A subsequent call to sqlite3_result_error()
or sqlite3_result_error16() resets the error code to SQLITE_ERROR.

The sqlite3_result_error_toobig() interface causes SQLite to throw an
error indicating that a string or BLOB is too long to represent.

The sqlite3_result_error_nomem() interface causes SQLite to throw an
error indicating that a memory allocation failed.

The sqlite3_result_int() interface sets the return value
of the application-defined function to be the 32-bit signed integer
value given in the 2nd argument.
The sqlite3_result_int64() interface sets the return value
of the application-defined function to be the 64-bit signed integer
value given in the 2nd argument.

The sqlite3_result_null() interface sets the return value
of the application-defined function to be NULL.

The sqlite3_result_text(), sqlite3_result_text16(),
sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
set the return value of the application-defined function to be
a text string which is represented as UTF-8, UTF-16 native byte order,
UTF-16 little endian, or UTF-16 big endian, respectively.
The sqlite3_result_text64() interface sets the return value of an
application-defined function to be a text string in an encoding
specified by the fifth (and last) parameter, which must be one
of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE.
SQLite takes the text result from the application from
the 2nd parameter of the sqlite3_result_text* interfaces.
If the 3rd parameter to any of the sqlite3_result_text* interfaces
other than sqlite3_result_text64() is negative, then SQLite computes
the string length itself by searching the 2nd parameter for the first
zero character.
If the 3rd parameter to the sqlite3_result_text* interfaces
is non-negative, then as many bytes (not characters) of the text
pointed to by the 2nd parameter are taken as the application-defined
function result.  If the 3rd parameter is non-negative, then it
must be the byte offset into the string where the NUL terminator would
appear if the string where NUL terminated.  If any NUL characters occur
in the string at a byte offset that is less than the value of the 3rd
parameter, then the resulting string will contain embedded NULs and the
result of expressions operating on strings with embedded NULs is undefined.
If the 4th parameter to the sqlite3_result_text* interfaces
or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
function as the destructor on the text or BLOB result when it has
finished using that result.
If the 4th parameter to the sqlite3_result_text* interfaces or to
sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
assumes that the text or BLOB result is in constant space and does not
copy the content of the parameter nor call a destructor on the content
when it has finished using that result.
If the 4th parameter to the sqlite3_result_text* interfaces
or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
then SQLite makes a copy of the result into space obtained
from sqlite3_malloc() before it returns.

For the sqlite3_result_text16(), sqlite3_result_text16le(), and
sqlite3_result_text16be() routines, and for sqlite3_result_text64()
when the encoding is not UTF8, if the input UTF16 begins with a
byte-order mark (BOM, U+FEFF) then the BOM is removed from the
string and the rest of the string is interpreted according to the
byte-order specified by the BOM.  The byte-order specified by
the BOM at the beginning of the text overrides the byte-order
specified by the interface procedure.  So, for example, if
sqlite3_result_text16le() is invoked with text that begins
with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
first two bytes of input are skipped and the remaining input
is interpreted as UTF16BE text.

For UTF16 input text to the sqlite3_result_text16(),
sqlite3_result_text16be(), sqlite3_result_text16le(), and
sqlite3_result_text64() routines, if the text contains invalid
UTF16 characters, the invalid characters might be converted
into the unicode replacement character, U+FFFD.

The sqlite3_result_value() interface sets the result of
the application-defined function to be a copy of the
unprotected sqlite3_value object specified by the 2nd parameter.  The
sqlite3_result_value() interface makes a copy of the sqlite3_value
so that the sqlite3_value specified in the parameter may change or
be deallocated after sqlite3_result_value() returns without harm.
A protected sqlite3_value object may always be used where an
unprotected sqlite3_value object is required, so either
kind of sqlite3_value object can be used with this interface.

The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
SQL NULL value, just like sqlite3_result_null(C), except that it
also associates the host-language pointer P or type T with that
NULL value such that the pointer can be retrieved within an
application-defined SQL function using sqlite3_value_pointer().
If the D parameter is not NULL, then it is a pointer to a destructor
for the P parameter.  SQLite invokes D with P as its only argument
when SQLite is finished with P.  The T parameter should be a static
string and preferably a string literal. The sqlite3_result_pointer()
routine is part of the pointer passing interface added for SQLite 3.20.0.

If these routines are called from within the different thread
than the one containing the application-defined function that received
the sqlite3_context pointer, the results are undefined.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_str_finish()
c2: C API: Finalize A Dynamic String
c5: c3ref/str_finish.html
c4:
The sqlite3_str_finish(X) interface destroys the sqlite3_str object X
and returns a pointer to a memory buffer obtained from sqlite3_malloc64()
that contains the constructed string.  The calling application should
pass the returned value to sqlite3_free() to avoid a memory leak.
The sqlite3_str_finish(X) interface may return a NULL pointer if any
errors were encountered during construction of the string.  The
sqlite3_str_finish(X) interface will also return a NULL pointer if the
string in sqlite3_str object X is zero bytes long.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Low-Level Control Of Database Files
c5: c3ref/file_control.html
c4:
The sqlite3_file_control() interface makes a direct call to the
xFileControl method for the sqlite3_io_methods object associated
with a particular database identified by the second argument. The
name of the database is "main" for the main database or "temp" for the
TEMP database, or the name that appears after the AS keyword for
databases that are added using the ATTACH SQL command.
A NULL pointer can be used in place of "main" to refer to the
main database file.
The third and fourth parameters to this routine
are passed directly through to the second and third parameters of
the xFileControl method.  The return value of the xFileControl
method becomes the return value of this routine.

A few opcodes for sqlite3_file_control() are handled directly
by the SQLite core and never invoke the
sqlite3_io_methods.xFileControl method.
The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
a pointer to the underlying sqlite3_file object to be written into
the space pointed to by the 4th parameter.  The
SQLITE_FCNTL_JOURNAL_POINTER works similarly except that it returns
the sqlite3_file object associated with the journal file instead of
the main database.  The SQLITE_FCNTL_VFS_POINTER opcode returns
a pointer to the underlying sqlite3_vfs object for the file.
The SQLITE_FCNTL_DATA_VERSION returns the data version counter
from the pager.

If the second parameter (zDbName) does not match the name of any
open database file, then SQLITE_ERROR is returned.  This error
code is not remembered and will not be recalled by sqlite3_errcode()
or sqlite3_errmsg().  The underlying xFileControl method might
also return SQLITE_ERROR.  There is no way to distinguish between
an incorrect zDbName and an SQLITE_ERROR return from the underlying
xFileControl method.

See also: file control opcodes
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Loadable Extension Thunk
c5: c3ref/api_routines.html
c4:
A pointer to the opaque sqlite3_api_routines structure is passed as
the third parameter to entry points of loadable extensions.  This
structure must be typedefed in order to work around compiler warnings
on some platforms.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_vtab
c2: C API: Virtual Table Instance Object
c5: c3ref/vtab.html
c4:
Every virtual table module implementation uses a subclass
of this object to describe a particular instance
of the virtual table.  Each subclass will
be tailored to the specific needs of the module implementation.
The purpose of this superclass is to define certain fields that are
common to all module implementations.

Virtual tables methods can set an error message by assigning a
string obtained from sqlite3_mprintf() to zErrMsg.  The method should
take care that any prior string is freed by a call to sqlite3_free()
prior to assigning a new string to zErrMsg.  After the error message
is delivered up to the client application, the string will be automatically
freed by sqlite3_free() and the zErrMsg field will be zeroed.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_vtab_rhs_value()
c2: C API: Constraint values in xBestIndex()
c5: c3ref/vtab_rhs_value.html
c4:
This API may only be used from within the xBestIndex method
of a virtual table implementation. The result of calling this interface
from outside of an xBestIndex method are undefined and probably harmful.

When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
the xBestIndex method of a virtual table implementation, with P being
a copy of the sqlite3_index_info object pointer passed into xBestIndex and
J being a 0-based index into P->aConstraint[], then this routine
attempts to set *V to the value of the right-hand operand of
that constraint if the right-hand operand is known.  If the
right-hand operand is not known, then *V is set to a NULL pointer.
The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if
and only if *V is set to a value.  The sqlite3_vtab_rhs_value(P,J,V)
inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
constraint is not available.  The sqlite3_vtab_rhs_value() interface
can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if
something goes wrong.

The sqlite3_vtab_rhs_value() interface is usually only successful if
the right-hand operand of a constraint is a literal value in the original
SQL statement.  If the right-hand operand is an expression or a reference
to some other column or a host parameter, then sqlite3_vtab_rhs_value()
will probably return SQLITE_NOTFOUND.

Some constraints, such as SQLITE_INDEX_CONSTRAINT_ISNULL and
SQLITE_INDEX_CONSTRAINT_ISNOTNULL, have no right-hand operand.  For such
constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.

The sqlite3_value object returned in *V is a protected sqlite3_value
and remains valid for the duration of the xBestIndex method call.
When xBestIndex returns, the sqlite3_value object returned by
sqlite3_vtab_rhs_value() is automatically deallocated.

The "_rhs_" in the name of this routine is an abbreviation for
"Right-Hand Side".
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Configuration Options
c5: c3ref/c_config_covering_index_scan.html
c0:
SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_MALLOC, SQLITE_CONFIG_GETMALLOC, SQLITE_CONFIG_SCRATCH, SQLITE_CONFIG_PAGECACHE, SQLITE_CONFIG_HEAP, SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_MUTEX, SQLITE_CONFIG_GETMUTEX, SQLITE_CONFIG_LOOKASIDE, SQLITE_CONFIG_PCACHE, SQLITE_CONFIG_GETPCACHE, SQLITE_CONFIG_LOG, SQLITE_CONFIG_URI, SQLITE_CONFIG_PCACHE2, SQLITE_CONFIG_GETPCACHE2, SQLITE_CONFIG_COVERING_INDEX_SCAN, SQLITE_CONFIG_SQLLOG, SQLITE_CONFIG_MMAP_SIZE, SQLITE_CONFIG_WIN32_HEAPSIZE, SQLITE_CONFIG_PCACHE_HDRSZ, SQLITE_CONFIG_PMASZ, SQLITE_CONFIG_STMTJRNL_SPILL, SQLITE_CONFIG_SMALL_MALLOC, SQLITE_CONFIG_SORTERREF_SIZE, SQLITE_CONFIG_MEMDB_MAXSIZE, SQLITE_CONFIG_ROWID_IN_VIEW

c4:
These constants are the available integer configuration options that
can be passed as the first argument to the sqlite3_config() interface.

Most of the configuration options for sqlite3_config()
will only work if invoked prior to sqlite3_initialize() or after
sqlite3_shutdown().  The few exceptions to this rule are called
"anytime configuration options".
Calling sqlite3_config() with a first argument that is not an
anytime configuration option in between calls to sqlite3_initialize() and
sqlite3_shutdown() is a no-op that returns SQLITE_MISUSE.

The set of anytime configuration options can change (by insertions
and/or deletions) from one release of SQLite to the next.
As of SQLite version 3.42.0, the complete set of anytime configuration
options is:

 SQLITE_CONFIG_LOG
 SQLITE_CONFIG_PCACHE_HDRSZ


New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued.  Applications
should check the return code from sqlite3_config() to make sure that
the call worked.  The sqlite3_config() interface will return a
non-zero error code if a discontinued or unsupported configuration option
is invoked.



 SQLITE_CONFIG_SINGLETHREAD
There are no arguments to this option.  This option sets the
threading mode to Single-thread.  In other words, it disables
all mutexing and puts SQLite into a mode where it can only be used
by a single thread.   If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then
it is not possible to change the threading mode from its default
value of Single-thread and so sqlite3_config() will return
SQLITE_ERROR if called with the SQLITE_CONFIG_SINGLETHREAD
configuration option.


 SQLITE_CONFIG_MULTITHREAD
There are no arguments to this option.  This option sets the
threading mode to Multi-thread.  In other words, it disables
mutexing on database connection and prepared statement objects.
The application is responsible for serializing access to
database connections and prepared statements.  But other mutexes
are enabled so that SQLite will be safe to use in a multi-threaded
environment as long as no two threads attempt to use the same
database connection at the same time.  If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then
it is not possible to set the Multi-thread threading mode and
sqlite3_config() will return SQLITE_ERROR if called with the
SQLITE_CONFIG_MULTITHREAD configuration option.


 SQLITE_CONFIG_SERIALIZED
There are no arguments to this option.  This option sets the
threading mode to Serialized. In other words, this option enables
all mutexes including the recursive
mutexes on database connection and prepared statement objects.
In this mode (which is the default when SQLite is compiled with
SQLITE_THREADSAFE=1) the SQLite library will itself serialize access
to database connections and prepared statements so that the
application is free to use the same database connection or the
same prepared statement in different threads at the same time.
If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then
it is not possible to set the Serialized threading mode and
sqlite3_config() will return SQLITE_ERROR if called with the
SQLITE_CONFIG_SERIALIZED configuration option.


 SQLITE_CONFIG_MALLOC
 The SQLITE_CONFIG_MALLOC option takes a single argument which is
a pointer to an instance of the sqlite3_mem_methods structure.
The argument specifies
alternative low-level memory allocation routines to be used in place of
the memory allocation routines built into SQLite. SQLite makes
its own private copy of the content of the sqlite3_mem_methods structure
before the sqlite3_config() call returns.


 SQLITE_CONFIG_GETMALLOC
 The SQLITE_CONFIG_GETMALLOC option takes a single argument which
is a pointer to an instance of the sqlite3_mem_methods structure.
The sqlite3_mem_methods
structure is filled with the currently defined memory allocation routines.
This option can be used to overload the default memory allocation
routines with a wrapper that simulations memory allocation failure or
tracks memory usage, for example. 


 SQLITE_CONFIG_SMALL_MALLOC
 The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
type int, interpreted as a boolean, which if true provides a hint to
SQLite that it should avoid large memory allocations if possible.
SQLite will run faster if it is free to make large memory allocations,
but some application might prefer to run slower in exchange for
guarantees about memory fragmentation that are possible if large
allocations are avoided.  This hint is normally off.



 SQLITE_CONFIG_MEMSTATUS
 The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
interpreted as a boolean, which enables or disables the collection of
memory allocation statistics. When memory allocation statistics are
disabled, the following SQLite interfaces become non-operational:

 sqlite3_hard_heap_limit64()
 sqlite3_memory_used()
 sqlite3_memory_highwater()
 sqlite3_soft_heap_limit64()
 sqlite3_status64()

Memory allocation statistics are enabled by default unless SQLite is
compiled with SQLITE_DEFAULT_MEMSTATUS=0 in which case memory
allocation statistics are disabled by default.



 SQLITE_CONFIG_SCRATCH
 The SQLITE_CONFIG_SCRATCH option is no longer used.



 SQLITE_CONFIG_PAGECACHE
 The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
that SQLite can use for the database page cache with the default page
cache implementation.
This configuration option is a no-op if an application-defined page
cache implementation is loaded using the SQLITE_CONFIG_PCACHE2.
There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
8-byte aligned memory (pMem), the size of each page cache line (sz),
and the number of cache lines (N).
The sz argument should be the size of the largest database page
(a power of two between 512 and 65536) plus some extra bytes for each
page header.  The number of extra bytes needed by the page header
can be determined using SQLITE_CONFIG_PCACHE_HDRSZ.
It is harmless, apart from the wasted memory,
for the sz parameter to be larger than necessary.  The pMem
argument must be either a NULL pointer or a pointer to an 8-byte
aligned block of memory of at least sz*N bytes, otherwise
subsequent behavior is undefined.
When pMem is not NULL, SQLite will strive to use the memory provided
to satisfy page cache needs, falling back to sqlite3_malloc() if
a page cache line is larger than sz bytes or if all of the pMem buffer
is exhausted.
If pMem is NULL and N is non-zero, then each database connection
does an initial bulk allocation for page cache memory
from sqlite3_malloc() sufficient for N cache lines if N is positive or
of -1024*N bytes if N is negative, . If additional
page cache memory is needed beyond what is provided by the initial
allocation, then SQLite goes to sqlite3_malloc() separately for each
additional cache line. 


 SQLITE_CONFIG_HEAP
 The SQLITE_CONFIG_HEAP option specifies a static memory buffer
that SQLite will use for all of its dynamic memory allocation needs
beyond those provided for by SQLITE_CONFIG_PAGECACHE.
The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
with either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 and returns
SQLITE_ERROR if invoked otherwise.
There are three arguments to SQLITE_CONFIG_HEAP:
An 8-byte aligned pointer to the memory,
the number of bytes in the memory buffer, and the minimum allocation size.
If the first pointer (the memory pointer) is NULL, then SQLite reverts
to using its default memory allocator (the system malloc() implementation),
undoing any prior invocation of SQLITE_CONFIG_MALLOC.  If the
memory pointer is not NULL then the alternative memory
allocator is engaged to handle all of SQLites memory allocation needs.
The first pointer (the memory pointer) must be aligned to an 8-byte
boundary or subsequent behavior of SQLite will be undefined.
The minimum allocation size is capped at 2**12. Reasonable values
for the minimum allocation size are 2**5 through 2**8.


 SQLITE_CONFIG_MUTEX
 The SQLITE_CONFIG_MUTEX option takes a single argument which is a
pointer to an instance of the sqlite3_mutex_methods structure.
The argument specifies alternative low-level mutex routines to be used
in place the mutex routines built into SQLite.  SQLite makes a copy of
the content of the sqlite3_mutex_methods structure before the call to
sqlite3_config() returns. If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then
the entire mutexing subsystem is omitted from the build and hence calls to
sqlite3_config() with the SQLITE_CONFIG_MUTEX configuration option will
return SQLITE_ERROR.


 SQLITE_CONFIG_GETMUTEX
 The SQLITE_CONFIG_GETMUTEX option takes a single argument which
is a pointer to an instance of the sqlite3_mutex_methods structure.  The
sqlite3_mutex_methods
structure is filled with the currently defined mutex routines.
This option can be used to overload the default mutex allocation
routines with a wrapper used to track mutex usage for performance
profiling or testing, for example.   If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then
the entire mutexing subsystem is omitted from the build and hence calls to
sqlite3_config() with the SQLITE_CONFIG_GETMUTEX configuration option will
return SQLITE_ERROR.


 SQLITE_CONFIG_LOOKASIDE
 The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
the default size of lookaside memory on each database connection.
The first argument is the
size of each lookaside buffer slot and the second is the number of
slots allocated to each database connection.  SQLITE_CONFIG_LOOKASIDE
sets the default lookaside size. The SQLITE_DBCONFIG_LOOKASIDE
option to sqlite3_db_config() can be used to change the lookaside
configuration on individual connections. 


 SQLITE_CONFIG_PCACHE2
 The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
a pointer to an sqlite3_pcache_methods2 object.  This object specifies
the interface to a custom page cache implementation.
SQLite makes a copy of the sqlite3_pcache_methods2 object.


 SQLITE_CONFIG_GETPCACHE2
 The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
is a pointer to an sqlite3_pcache_methods2 object.  SQLite copies of
the current page cache implementation into that object. 


 SQLITE_CONFIG_LOG
 The SQLITE_CONFIG_LOG option is used to configure the SQLite
global error log.
(The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
function with a call signature of void(*)(void*,int,const char*),
and a pointer to void. If the function pointer is not NULL, it is
invoked by sqlite3_log() to process each logging event.  If the
function pointer is NULL, the sqlite3_log() interface becomes a no-op.
The void pointer that is the second argument to SQLITE_CONFIG_LOG is
passed through as the first parameter to the application-defined logger
function whenever that function is invoked.  The second parameter to
the logger function is a copy of the first parameter to the corresponding
sqlite3_log() call and is intended to be a result code or an
extended result code.  The third parameter passed to the logger is
log message after formatting via sqlite3_snprintf().
The SQLite logging interface is not reentrant; the logger function
supplied by the application must not invoke any SQLite interface.
In a multi-threaded application, the application-defined logger
function must be threadsafe. 


 SQLITE_CONFIG_URI
The SQLITE_CONFIG_URI option takes a single argument of type int.
If non-zero, then URI handling is globally enabled. If the parameter is zero,
then URI handling is globally disabled. If URI handling is globally
enabled, all filenames passed to sqlite3_open(), sqlite3_open_v2(),
sqlite3_open16() or
specified as part of ATTACH commands are interpreted as URIs, regardless
of whether or not the SQLITE_OPEN_URI flag is set when the database
connection is opened. If it is globally disabled, filenames are
only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
database connection is opened. By default, URI handling is globally
disabled. The default value may be changed by compiling with the
SQLITE_USE_URI symbol defined.


 SQLITE_CONFIG_COVERING_INDEX_SCAN
The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
argument which is interpreted as a boolean in order to enable or disable
the use of covering indices for full table scans in the query optimizer.
The default setting is determined
by the SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or is "on"
if that compile-time option is omitted.
The ability to disable the use of covering indices for full table scans
is because some incorrectly coded legacy applications might malfunction
when the optimization is enabled.  Providing the ability to
disable the optimization allows the older, buggy application code to work
without change even with newer versions of SQLite.


 

SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
 These options are obsolete and should not be used by new code.
They are retained for backwards compatibility but are now no-ops.




SQLITE_CONFIG_SQLLOG
This option is only available if sqlite is compiled with the
SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first argument should
be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
The second should be of type (void*). The callback is invoked by the library
in three separate circumstances, identified by the value passed as the
fourth parameter. If the fourth parameter is 0, then the database connection
passed as the second argument has just been opened. The third argument
points to a buffer containing the name of the main database file. If the
fourth parameter is 1, then the SQL statement that the third parameter
points to has just been executed. Or, if the fourth parameter is 2, then
the connection being passed as the second parameter is being closed. The
third parameter is passed NULL In this case.  An example of using this
configuration option can be seen in the "test_sqllog.c" source file in
the canonical SQLite source tree.



SQLITE_CONFIG_MMAP_SIZE
SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
that are the default mmap size limit (the default setting for
PRAGMA mmap_size) and the maximum allowed mmap size limit.
The default setting can be overridden by each database connection using
either the PRAGMA mmap_size command, or by using the
SQLITE_FCNTL_MMAP_SIZE file control.  The maximum allowed mmap size
will be silently truncated if necessary so that it does not exceed the
compile-time maximum mmap size set by the
SQLITE_MAX_MMAP_SIZE compile-time option.
If either argument to this option is negative, then that argument is
changed to its compile-time default.



SQLITE_CONFIG_WIN32_HEAPSIZE
The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
compiled for Windows with the SQLITE_WIN32_MALLOC pre-processor macro
defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
that specifies the maximum size of the created heap.



SQLITE_CONFIG_PCACHE_HDRSZ
The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
is a pointer to an integer and writes into that integer the number of extra
bytes per page required for each page in SQLITE_CONFIG_PAGECACHE.
The amount of extra space required can change depending on the compiler,
target platform, and SQLite version.



SQLITE_CONFIG_PMASZ
The SQLITE_CONFIG_PMASZ option takes a single parameter which
is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
sorter to that integer.  The default minimum PMA Size is set by the
SQLITE_SORTER_PMASZ compile-time option.  New threads are launched
to help with sort operations when multithreaded sorting
is enabled (using the PRAGMA threads command) and the amount of content
to be sorted exceeds the page size times the minimum of the
PRAGMA cache_size setting and this value.



SQLITE_CONFIG_STMTJRNL_SPILL
The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
becomes the statement journal spill-to-disk threshold.
Statement journals are held in memory until their size (in bytes)
exceeds this threshold, at which point they are written to disk.
Or if the threshold is -1, statement journals are always held
exclusively in memory.
Since many statement journals never become large, setting the spill
threshold to a value such as 64KiB can greatly reduce the amount of
I/O required to support statement rollback.
The default value for this setting is controlled by the
SQLITE_STMTJRNL_SPILL compile-time option.



SQLITE_CONFIG_SORTERREF_SIZE
The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
of type (int) - the new value of the sorter-reference size threshold.
Usually, when SQLite uses an external sort to order records according
to an ORDER BY clause, all fields required by the caller are present in the
sorted records. However, if SQLite determines based on the declared type
of a table column that its values are likely to be very large - larger
than the configured sorter-reference size threshold - then a reference
is stored in each sorted record and the required column values loaded
from the database as records are returned in sorted order. The default
value for this option is to never use this optimization. Specifying a
negative value for this option restores the default behavior.
This option is only available if SQLite is compiled with the
SQLITE_ENABLE_SORTER_REFERENCES compile-time option.



SQLITE_CONFIG_MEMDB_MAXSIZE
The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
sqlite3_int64 parameter which is the default maximum size for an in-memory
database created using sqlite3_deserialize().  This default maximum
size can be adjusted up or down for individual databases using the
SQLITE_FCNTL_SIZE_LIMIT file-control.  If this
configuration setting is never used, then the default maximum is determined
by the SQLITE_MEMDB_DEFAULT_MAXSIZE compile-time option.  If that
compile-time option is not set, then the default maximum is 1073741824.



SQLITE_CONFIG_ROWID_IN_VIEW
The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability
for VIEWs to have a ROWID.  The capability can only be enabled if SQLite is
compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
defaults to on.  This configuration option queries the current setting or
changes the setting to off or on.  The argument is a pointer to an integer.
If that integer initially holds a value of 1, then the ability for VIEWs to
have ROWIDs is activated.  If the integer initially holds zero, then the
ability is deactivated.  Any other initial value for the integer leaves the
setting unchanged.  After changes, if any, the integer is written with
a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off.  If SQLite
is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
recommended case) then the integer is always filled with zero, regardless
if its initial value.

See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_strlike()
c2: C API: String LIKE Matching
c5: c3ref/strlike.html
c4:
The sqlite3_strlike(P,X,E) interface returns zero if and only if
string X matches the LIKE pattern P with escape character E.
The definition of LIKE pattern matching used in
sqlite3_strlike(P,X,E) is the same as for the "X LIKE P ESCAPE E"
operator in the SQL dialect understood by SQLite.  For "X LIKE P" without
the ESCAPE clause, set the E parameter of sqlite3_strlike(P,X,E) to 0.
As with the LIKE operator, the sqlite3_strlike(P,X,E) function is case
insensitive - equivalent upper and lower case ASCII characters match
one another.

The sqlite3_strlike(P,X,E) function matches Unicode characters, though
only ASCII characters are case folded.

Note that this routine returns zero on a match and non-zero if the strings
do not match, the same as sqlite3_stricmp() and sqlite3_strnicmp().

See also: sqlite3_strglob().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_table_column_metadata()
c2: C API: Extract Metadata About A Column Of A Table
c5: c3ref/table_column_metadata.html
c4:
The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
information about column C of table T in database D
on database connection X.  The sqlite3_table_column_metadata()
interface returns SQLITE_OK and fills in the non-NULL pointers in
the final five arguments with appropriate values if the specified
column exists.  The sqlite3_table_column_metadata() interface returns
SQLITE_ERROR if the specified column does not exist.
If the column-name parameter to sqlite3_table_column_metadata() is a
NULL pointer, then this routine simply checks for the existence of the
table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
does not.  If the table name parameter T in a call to
sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
undefined behavior.

The column is identified by the second, third and fourth parameters to
this function. The second parameter is either the name of the database
(i.e. "main", "temp", or an attached database) containing the specified
table or NULL. If it is NULL, then all attached databases are searched
for the table using the same algorithm used by the database engine to
resolve unqualified table references.

The third and fourth parameters to this function are the table and column
name of the desired column, respectively.

Metadata is returned by writing to the memory locations passed as the 5th
and subsequent parameters to this function. Any of these arguments may be
NULL, in which case the corresponding element of metadata is omitted.



The memory pointed to by the character pointers returned for the
declaration type and collation sequence is valid until the next
call to any SQLite API function.

If the specified table is actually a view, an error code is returned.

If the specified column is "rowid", "oid" or "_rowid_" and the table
is not a WITHOUT ROWID table and an
INTEGER PRIMARY KEY column has been explicitly declared, then the output
parameters are set for the explicitly declared column. If there is no
INTEGER PRIMARY KEY column, then the outputs
for the rowid are set as follows:


data type: "INTEGER"
collation sequence: "BINARY"
not null: 0
primary key: 1
auto increment: 0


This function causes all database schemas to be read from disk and
parsed, if that has not already been done, and returns an error if
any errors are encountered while loading the schema.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Online Backup API.
c5: c3ref/backup_finish.html
c0:
sqlite3_backup_init(), sqlite3_backup_step(), sqlite3_backup_finish(), sqlite3_backup_remaining(), sqlite3_backup_pagecount()

c4:
The backup API copies the content of one database into another.
It is useful either for creating backups of databases or
for copying in-memory databases to or from persistent files.

See Also: Using the SQLite Online Backup API

SQLite holds a write transaction open on the destination database file
for the duration of the backup operation.
The source database is read-locked only while it is being read;
it is not locked continuously for the entire backup operation.
Thus, the backup may be performed on a live source database without
preventing other database connections from
reading or writing to the source database while the backup is underway.

To perform a backup operation:

sqlite3_backup_init() is called once to initialize the
backup,
sqlite3_backup_step() is called one or more times to transfer
the data between the two databases, and finally
sqlite3_backup_finish() is called to release all resources
associated with the backup operation.

There should be exactly one call to sqlite3_backup_finish() for each
successful call to sqlite3_backup_init().


 sqlite3_backup_init()

The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
database connection associated with the destination database
and the database name, respectively.
The database name is "main" for the main database, "temp" for the
temporary database, or the name specified after the AS keyword in
an ATTACH statement for an attached database.
The S and M arguments passed to
sqlite3_backup_init(D,N,S,M) identify the database connection
and database name of the source database, respectively.
The source and destination database connections (parameters S and D)
must be different or else sqlite3_backup_init(D,N,S,M) will fail with
an error.

A call to sqlite3_backup_init() will fail, returning NULL, if
there is already a read or read-write transaction open on the
destination database.

If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
returned and an error code and error message are stored in the
destination database connection D.
The error code and message for the failed call to sqlite3_backup_init()
can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), and/or
sqlite3_errmsg16() functions.
A successful call to sqlite3_backup_init() returns a pointer to an
sqlite3_backup object.
The sqlite3_backup object may be used with the sqlite3_backup_step() and
sqlite3_backup_finish() functions to perform the specified backup
operation.


 sqlite3_backup_step()

Function sqlite3_backup_step(B,N) will copy up to N pages between
the source and destination databases specified by sqlite3_backup object B.
If N is negative, all remaining source pages are copied.
If sqlite3_backup_step(B,N) successfully copies N pages and there
are still more pages to be copied, then the function returns SQLITE_OK.
If sqlite3_backup_step(B,N) successfully finishes copying all pages
from source to destination, then it returns SQLITE_DONE.
If an error occurs while running sqlite3_backup_step(B,N),
then an error code is returned. As well as SQLITE_OK and
SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY,
SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an
SQLITE_IOERR_XXX extended error code.

The sqlite3_backup_step() might return SQLITE_READONLY if

 the destination database was opened read-only, or
 the destination database is using write-ahead-log journaling
and the destination and source page sizes differ, or
 the destination database is an in-memory database and the
destination and source page sizes differ.


If sqlite3_backup_step() cannot obtain a required file-system lock, then
the busy-handler function
is invoked (if one is specified). If the
busy-handler returns non-zero before the lock is available, then
SQLITE_BUSY is returned to the caller. In this case the call to
sqlite3_backup_step() can be retried later. If the source
database connection
is being used to write to the source database when sqlite3_backup_step()
is called, then SQLITE_LOCKED is returned immediately. Again, in this
case the call to sqlite3_backup_step() can be retried later on. If
SQLITE_IOERR_XXX, SQLITE_NOMEM, or
SQLITE_READONLY is returned, then
there is no point in retrying the call to sqlite3_backup_step(). These
errors are considered fatal.  The application must accept
that the backup operation has failed and pass the backup operation handle
to the sqlite3_backup_finish() to release associated resources.

The first call to sqlite3_backup_step() obtains an exclusive lock
on the destination file. The exclusive lock is not released until either
sqlite3_backup_finish() is called or the backup operation is complete
and sqlite3_backup_step() returns SQLITE_DONE.  Every call to
sqlite3_backup_step() obtains a shared lock on the source database that
lasts for the duration of the sqlite3_backup_step() call.
Because the source database is not locked between calls to
sqlite3_backup_step(), the source database may be modified mid-way
through the backup process.  If the source database is modified by an
external process or via a database connection other than the one being
used by the backup operation, then the backup will be automatically
restarted by the next call to sqlite3_backup_step(). If the source
database is modified by the using the same database connection as is used
by the backup operation, then the backup database is automatically
updated at the same time.


 sqlite3_backup_finish()

When sqlite3_backup_step() has returned SQLITE_DONE, or when the
application wishes to abandon the backup operation, the application
should destroy the sqlite3_backup by passing it to sqlite3_backup_finish().
The sqlite3_backup_finish() interfaces releases all
resources associated with the sqlite3_backup object.
If sqlite3_backup_step() has not yet returned SQLITE_DONE, then any
active write-transaction on the destination database is rolled back.
The sqlite3_backup object is invalid
and may not be used following a call to sqlite3_backup_finish().

The value returned by sqlite3_backup_finish is SQLITE_OK if no
sqlite3_backup_step() errors occurred, regardless or whether or not
sqlite3_backup_step() completed.
If an out-of-memory condition or IO error occurred during any prior
sqlite3_backup_step() call on the same sqlite3_backup object, then
sqlite3_backup_finish() returns the corresponding error code.

A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step()
is not a permanent error and does not affect the return value of
sqlite3_backup_finish().


 

sqlite3_backup_remaining() and sqlite3_backup_pagecount()

The sqlite3_backup_remaining() routine returns the number of pages still
to be backed up at the conclusion of the most recent sqlite3_backup_step().
The sqlite3_backup_pagecount() routine returns the total number of pages
in the source database at the conclusion of the most recent
sqlite3_backup_step().
The values returned by these functions are only updated by
sqlite3_backup_step(). If the source database is modified in a way that
changes the size of the source database or the number of pages remaining,
those changes are not reflected in the output of sqlite3_backup_pagecount()
and sqlite3_backup_remaining() until after the next
sqlite3_backup_step().

Concurrent Usage of Database Handles

The source database connection may be used by the application for other
purposes while a backup operation is underway or being initialized.
If SQLite is compiled and configured to support threadsafe database
connections, then the source database connection may be used concurrently
from within other threads.

However, the application must guarantee that the destination
database connection is not passed to any other API (by any thread) after
sqlite3_backup_init() is called and before the corresponding call to
sqlite3_backup_finish().  SQLite does not currently check to see
if the application incorrectly accesses the destination database connection
and so no error code is reported, but the operations may malfunction
nevertheless.  Use of the destination database connection while a
backup is in progress might also cause a mutex deadlock.

If running in shared cache mode, the application must
guarantee that the shared cache used by the destination database
is not accessed while the backup is running. In practice this means
that the application must guarantee that the disk file being
backed up to is not accessed by any connection within the process,
not just the specific connection that was passed to sqlite3_backup_init().

The sqlite3_backup object itself is partially threadsafe. Multiple
threads may safely make multiple concurrent calls to sqlite3_backup_step().
However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
APIs are not strictly speaking threadsafe. If they are invoked at the
same time as another thread is invoking sqlite3_backup_step() it is
possible that they return invalid values.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_config()
c2: C API: Configuring The SQLite Library
c5: c3ref/config.html
c4:
The sqlite3_config() interface is used to make global configuration
changes to SQLite in order to tune SQLite to the specific needs of
the application.  The default configuration is recommended for most
applications and so this routine is usually not necessary.  It is
provided to support rare applications with unusual needs.

The sqlite3_config() interface is not threadsafe. The application
must ensure that no other SQLite interfaces are invoked by other
threads while sqlite3_config() is running.

The first argument to sqlite3_config() is an integer
configuration option that determines
what property of SQLite is to be configured.  Subsequent arguments
vary depending on the configuration option
in the first argument.

For most configuration options, the sqlite3_config() interface
may only be invoked prior to library initialization using
sqlite3_initialize() or after shutdown by sqlite3_shutdown().
The exceptional configuration options that may be invoked at any time
are called "anytime configuration options".
If sqlite3_config() is called after sqlite3_initialize() and before
sqlite3_shutdown() with a first argument that is not an anytime
configuration option, then the sqlite3_config() call will return SQLITE_MISUSE.
Note, however, that sqlite3_config() can be called as part of the
implementation of an application-defined sqlite3_os_init().

When a configuration option is set, sqlite3_config() returns SQLITE_OK.
If the option is unknown or SQLite is unable to set the option
then this routine returns a non-zero error code.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_create_collation(), sqlite3_create_collation_v2(), sqlite3_create_collation16()
c2: C API: Define New Collating Sequences
c5: c3ref/create_collation.html
c4:
These functions add, remove, or modify a collation associated
with the database connection specified as the first argument.

The name of the collation is a UTF-8 string
for sqlite3_create_collation() and sqlite3_create_collation_v2()
and a UTF-16 string in native byte order for sqlite3_create_collation16().
Collation names that compare equal according to sqlite3_strnicmp() are
considered to be the same name.

The third argument (eTextRep) must be one of the constants:

 SQLITE_UTF8,
 SQLITE_UTF16LE,
 SQLITE_UTF16BE,
 SQLITE_UTF16, or
 SQLITE_UTF16_ALIGNED.

The eTextRep argument determines the encoding of strings passed
to the collating function callback, xCompare.
The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED values for eTextRep
force strings to be UTF16 with native byte order.
The SQLITE_UTF16_ALIGNED value for eTextRep forces strings to begin
on an even byte address.

The fourth argument, pArg, is an application data pointer that is passed
through as the first argument to the collating function callback.

The fifth argument, xCompare, is a pointer to the collating function.
Multiple collating functions can be registered using the same name but
with different eTextRep parameters and SQLite will use whichever
function requires the least amount of data transformation.
If the xCompare argument is NULL then the collating function is
deleted.  When all collating functions having the same name are deleted,
that collation is no longer usable.

The collating function callback is invoked with a copy of the pArg
application data pointer and with two strings in the encoding specified
by the eTextRep argument.  The two integer parameters to the collating
function callback are the length of the two strings, in bytes. The collating
function must return an integer that is negative, zero, or positive
if the first string is less than, equal to, or greater than the second,
respectively.  A collating function must always return the same answer
given the same inputs.  If two or more collating functions are registered
to the same collation name (using different eTextRep values) then all
must give an equivalent answer when invoked with equivalent strings.
The collating function must obey the following properties for all
strings A, B, and C:


 If A==B then B==A.
 If A==B and B==C then A==C.
 If A&lt;B THEN B&gt;A.
 If A&lt;B and B&lt;C then A&lt;C.


If a collating function fails any of the above constraints and that
collating function is registered and used, then the behavior of SQLite
is undefined.

The sqlite3_create_collation_v2() works like sqlite3_create_collation()
with the addition that the xDestroy callback is invoked on pArg when
the collating function is deleted.
Collating functions are deleted when they are overridden by later
calls to the collation creation functions or when the
database connection is closed using sqlite3_close().

The xDestroy callback is not called if the
sqlite3_create_collation_v2() function fails.  Applications that invoke
sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
check the return code and dispose of the application data pointer
themselves rather than expecting SQLite to deal with it for them.
This is different from every other SQLite interface.  The inconsistency
is unfortunate but cannot be changed without breaking backwards
compatibility.

See also:  sqlite3_collation_needed() and sqlite3_collation_needed16().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_get_table(), sqlite3_free_table()
c2: C API: Convenience Routines For Running Queries
c5: c3ref/free_table.html
c4:
This is a legacy interface that is preserved for backwards compatibility.
Use of this interface is not recommended.

Definition: A result table is memory data structure created by the
sqlite3_get_table() interface.  A result table records the
complete query results from one or more queries.

The table conceptually has a number of rows and columns.  But
these numbers are not part of the result table itself.  These
numbers are obtained separately.  Let N be the number of rows
and M be the number of columns.

A result table is an array of pointers to zero-terminated UTF-8 strings.
There are (N+1)*M elements in the array.  The first M pointers point
to zero-terminated strings that  contain the names of the columns.
The remaining entries all point to query results.  NULL values result
in NULL pointers.  All other values are in their UTF-8 zero-terminated
string representation as returned by sqlite3_column_text().

A result table might consist of one or more memory allocations.
It is not safe to pass a result table directly to sqlite3_free().
A result table should be deallocated using sqlite3_free_table().

As an example of the result table format, suppose a query result
is as follows:



There are two columns (M==2) and three rows (N==3).  Thus the
result table has 8 entries.  Suppose the result table is stored
in an array named azResult.  Then azResult holds this content:



The sqlite3_get_table() function evaluates one or more
semicolon-separated SQL statements in the zero-terminated UTF-8
string of its 2nd parameter and returns a result table to the
pointer given in its 3rd parameter.

After the application has finished with the result from sqlite3_get_table(),
it must pass the result table pointer to sqlite3_free_table() in order to
release the memory that was malloced.  Because of the way the
sqlite3_malloc() happens within sqlite3_get_table(), the calling
function must not try to call sqlite3_free() directly.  Only
sqlite3_free_table() is able to release the memory properly and safely.

The sqlite3_get_table() interface is implemented as a wrapper around
sqlite3_exec().  The sqlite3_get_table() routine does not have access
to any internal data structures of SQLite.  It uses only the public
interface defined here.  As a consequence, errors that occur in the
wrapper layer outside of the internal sqlite3_exec() call are not
reflected in subsequent calls to sqlite3_errcode() or
sqlite3_errmsg().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_str_errcode(), sqlite3_str_length(), sqlite3_str_value()
c2: C API: Status Of A Dynamic String
c5: c3ref/str_errcode.html
c4:
These interfaces return the current status of an sqlite3_str object.

If any prior errors have occurred while constructing the dynamic string
in sqlite3_str X, then the sqlite3_str_errcode(X) method will return
an appropriate error code.  The sqlite3_str_errcode(X) method returns
SQLITE_NOMEM following any out-of-memory error, or
SQLITE_TOOBIG if the size of the dynamic string exceeds
SQLITE_MAX_LENGTH, or SQLITE_OK if there have been no errors.

The sqlite3_str_length(X) method returns the current length, in bytes,
of the dynamic string under construction in sqlite3_str object X.
The length returned by sqlite3_str_length(X) does not include the
zero-termination byte.

The sqlite3_str_value(X) method returns a pointer to the current
content of the dynamic string under construction in X.  The value
returned by sqlite3_str_value(X) is managed by the sqlite3_str object X
and might be freed or altered by any subsequent method on the same
sqlite3_str object.  Applications must not used the pointer returned
sqlite3_str_value(X) after any subsequent method call on the same
object.  Applications may change the content of the string returned
by sqlite3_str_value(X) as long as they do not write into any bytes
outside the range of 0 to sqlite3_str_length(X) and do not read or
write any byte after any subsequent sqlite3_str method call.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_busy_timeout()
c2: C API: Set A Busy Timeout
c5: c3ref/busy_timeout.html
c4:
This routine sets a busy handler that sleeps
for a specified amount of time when a table is locked.  The handler
will sleep multiple times until at least "ms" milliseconds of sleeping
have accumulated.  After at least "ms" milliseconds of sleeping,
the handler returns 0 which causes sqlite3_step() to return
SQLITE_BUSY.

Calling this routine with an argument less than or equal to zero
turns off all busy handlers.

There can only be a single busy handler for a particular
database connection at any given moment.  If another busy handler
was defined  (using sqlite3_busy_handler()) prior to calling
this routine, that other busy handler is cleared.

See also:  PRAGMA busy_timeout
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_finalize()
c2: C API: Destroy A Prepared Statement Object
c5: c3ref/finalize.html
c4:
The sqlite3_finalize() function is called to delete a prepared statement.
If the most recent evaluation of the statement encountered no errors
or if the statement is never been evaluated, then sqlite3_finalize() returns
SQLITE_OK.  If the most recent evaluation of statement S failed, then
sqlite3_finalize(S) returns the appropriate error code or
extended error code.

The sqlite3_finalize(S) routine can be called at any point during
the life cycle of prepared statement S:
before statement S is ever evaluated, after
one or more calls to sqlite3_reset(), or after any call
to sqlite3_step() regardless of whether or not the statement has
completed execution.

Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.

The application must finalize every prepared statement in order to avoid
resource leaks.  It is a grievous error for the application to try to use
a prepared statement after it has been finalized.  Any use of a prepared
statement after it has been finalized can result in undefined and
undesirable behavior such as segfaults and heap corruption.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_bind_parameter_index()
c2: C API: Index Of A Parameter With A Given Name
c5: c3ref/bind_parameter_index.html
c4:
Return the index of an SQL parameter given its name.  The
index value returned is suitable for use as the second
parameter to sqlite3_bind().  A zero
is returned if no matching parameter is found.  The parameter
name must be given in UTF-8 even if the original statement
was prepared from UTF-16 text using sqlite3_prepare16_v2() or
sqlite3_prepare16_v3().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_name().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_sql(), sqlite3_expanded_sql(), sqlite3_normalized_sql()
c2: C API: Retrieving Statement SQL
c5: c3ref/expanded_sql.html
c4:
The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
SQL text used to create prepared statement P if P was
created by sqlite3_prepare_v2(), sqlite3_prepare_v3(),
sqlite3_prepare16_v2(), or sqlite3_prepare16_v3().
The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
string containing the SQL text of prepared statement P with
bound parameters expanded.
The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
string containing the normalized SQL text of prepared statement P.  The
semantics used to normalize a SQL statement are unspecified and subject
to change.  At a minimum, literal values will be replaced with suitable
placeholders.

For example, if a prepared statement is created using the SQL
text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
and parameter :xyz is unbound, then sqlite3_sql() will return
the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
will return "SELECT 2345,NULL".

The sqlite3_expanded_sql() interface returns NULL if insufficient memory
is available to hold the result, or if the result would exceed the
the maximum string length determined by the SQLITE_LIMIT_LENGTH.

The SQLITE_TRACE_SIZE_LIMIT compile-time option limits the size of
bound parameter expansions.  The SQLITE_OMIT_TRACE compile-time
option causes sqlite3_expanded_sql() to always return NULL.

The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
are managed by SQLite and are automatically freed when the prepared
statement is finalized.
The string returned by sqlite3_expanded_sql(P), on the other hand,
is obtained from sqlite3_malloc() and must be freed by the application
by passing it to sqlite3_free().

The sqlite3_normalized_sql() interface is only available if
the SQLITE_ENABLE_NORMALIZE compile-time option is defined.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_system_errno()
c2: C API: Low-level system error code
c5: c3ref/system_errno.html
c4:
Attempt to return the underlying operating system error code or error
number that caused the most recent I/O error or failure to open a file.
The return value is OS-dependent.  For example, on unix systems, after
sqlite3_open_v2() returns SQLITE_CANTOPEN, this interface could be
called to get back the underlying "errno" that caused the problem, such
as ENOSPC, EAUTH, EISDIR, and so forth.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_open(), sqlite3_open16()
c2: C API: Opening A New Database Connection
c5: c3ref/open.html
c4:
These routines open an SQLite database file as specified by the
filename argument. The filename argument is interpreted as UTF-8 for
sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
order for sqlite3_open16(). A database connection handle is usually
returned in *ppDb, even if an error occurs.  The only exception is that
if SQLite is unable to allocate memory to hold the sqlite3 object,
a NULL will be written into *ppDb instead of a pointer to the sqlite3
object. If the database is opened (and/or created) successfully, then
SQLITE_OK is returned.  Otherwise an error code is returned. The
sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
an English language description of the error following a failure of any
of the sqlite3_open() routines.

The default encoding will be UTF-8 for databases created using
sqlite3_open() or sqlite3_open_v2().  The default encoding for databases
created using sqlite3_open16() will be UTF-16 in the native byte order.

Whether or not an error occurs when it is opened, resources
associated with the database connection handle should be released by
passing it to sqlite3_close() when it is no longer required.

The sqlite3_open_v2() interface works like sqlite3_open()
except that it accepts two additional parameters for additional control
over the new database connection.  The flags parameter to
sqlite3_open_v2() must include, at a minimum, one of the following
three flag combinations:


SQLITE_OPEN_READONLY
The database is opened in read-only mode.  If the database does
not already exist, an error is returned.

SQLITE_OPEN_READWRITE
The database is opened for reading and writing if possible, or
reading only if the file is write protected by the operating
system.  In either case the database must already exist, otherwise
an error is returned.  For historical reasons, if opening in
read-write mode fails due to OS-level permissions, an attempt is
made to open it in read-only mode. sqlite3_db_readonly() can be
used to determine whether the database is actually
read-write.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
The database is opened for reading and writing, and is created if
it does not already exist. This is the behavior that is always used for
sqlite3_open() and sqlite3_open16().


In addition to the required flags, the following optional flags are
also supported:


SQLITE_OPEN_URI
The filename can be interpreted as a URI if this flag is set.

SQLITE_OPEN_MEMORY
The database will be opened as an in-memory database.  The database
is named by the "filename" argument for the purposes of cache-sharing,
if shared cache mode is enabled, but the "filename" is otherwise ignored.


SQLITE_OPEN_NOMUTEX
The new database connection will use the "multi-thread"
threading mode.  This means that separate threads are allowed
to use SQLite at the same time, as long as each thread is using
a different database connection.

SQLITE_OPEN_FULLMUTEX
The new database connection will use the "serialized"
threading mode.  This means the multiple threads can safely
attempt to use the same database connection at the same time.
(Mutexes will block any actual concurrency, but in this mode
there is no harm in trying.)

SQLITE_OPEN_SHAREDCACHE
The database is opened shared cache enabled, overriding
the default shared cache setting provided by
sqlite3_enable_shared_cache().
The use of shared cache mode is discouraged and hence shared cache
capabilities may be omitted from many builds of SQLite.  In such cases,
this option is a no-op.

SQLITE_OPEN_PRIVATECACHE
The database is opened shared cache disabled, overriding
the default shared cache setting provided by
sqlite3_enable_shared_cache().


 SQLITE_OPEN_EXRESCODE
The database connection comes up in "extended result code mode".
In other words, the database behaves has if
sqlite3_extended_result_codes(db,1) where called on the database
connection as soon as the connection is created. In addition to setting
the extended result code mode, this flag also causes sqlite3_open_v2()
to return an extended result code.


 SQLITE_OPEN_NOFOLLOW
The database filename is not allowed to contain a symbolic link


If the 3rd parameter to sqlite3_open_v2() is not one of the
required combinations shown above optionally combined with other
SQLITE_OPEN_* bits
then the behavior is undefined.  Historic versions of SQLite
have silently ignored surplus bits in the flags parameter to
sqlite3_open_v2(), however that behavior might not be carried through
into future versions of SQLite and so applications should not rely
upon it.  Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
for sqlite3_open_v2().  The SQLITE_OPEN_EXCLUSIVE does *not* cause
the open to fail if the database already exists.  The SQLITE_OPEN_EXCLUSIVE
flag is intended for use by the VFS interface only, and not
by sqlite3_open_v2().

The fourth parameter to sqlite3_open_v2() is the name of the
sqlite3_vfs object that defines the operating system interface that
the new database connection should use.  If the fourth parameter is
a NULL pointer then the default sqlite3_vfs object is used.

If the filename is ":memory:", then a private, temporary in-memory database
is created for the connection.  This in-memory database will vanish when
the database connection is closed.  Future versions of SQLite might
make use of additional special filenames that begin with the ":" character.
It is recommended that when a database filename actually does begin with
a ":" character you should prefix the filename with a pathname such as
"./" to avoid ambiguity.

If the filename is an empty string, then a private, temporary
on-disk database will be created.  This private database will be
automatically deleted as soon as the database connection is closed.


 URI Filenames

If URI filename interpretation is enabled, and the filename argument
begins with "file:", then the filename is interpreted as a URI. URI
filename interpretation is enabled if the SQLITE_OPEN_URI flag is
set in the third argument to sqlite3_open_v2(), or if it has
been enabled globally using the SQLITE_CONFIG_URI option with the
sqlite3_config() method or by the SQLITE_USE_URI compile-time option.
URI filename interpretation is turned off
by default, but future releases of SQLite might enable URI filename
interpretation by default.  See "URI filenames" for additional
information.

URI filenames are parsed according to RFC 3986. If the URI contains an
authority, then it must be either an empty string or the string
"localhost". If the authority is not an empty string or "localhost", an
error is returned to the caller. The fragment component of a URI, if
present, is ignored.

SQLite uses the path component of the URI as the name of the disk file
which contains the database. If the path begins with a '/' character,
then it is interpreted as an absolute path. If the path does not begin
with a '/' (meaning that the authority section is omitted from the URI)
then the path is interpreted as a relative path.
On windows, the first component of an absolute path
is a drive specification (e.g. "C:").



The query component of a URI may contain parameters that are interpreted
either by SQLite itself, or by a custom VFS implementation.
SQLite and its built-in VFSes interpret the
following query parameters:


 vfs: The "vfs" parameter may be used to specify the name of
a VFS object that provides the operating system interface that should
be used to access the database file on disk. If this option is set to
an empty string the default VFS object is used. Specifying an unknown
VFS is an error. If sqlite3_open_v2() is used and the vfs option is
present, then the VFS specified by the option takes precedence over
the value passed as the fourth parameter to sqlite3_open_v2().

 mode: The mode parameter may be set to either "ro", "rw",
"rwc", or "memory". Attempting to set it to any other value is
an error.
If "ro" is specified, then the database is opened for read-only
access, just as if the SQLITE_OPEN_READONLY flag had been set in the
third argument to sqlite3_open_v2(). If the mode option is set to
"rw", then the database is opened for read-write (but not create)
access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
been set. Value "rwc" is equivalent to setting both
SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  If the mode option is
set to "memory" then a pure in-memory database that never reads
or writes from disk is used. It is an error to specify a value for
the mode parameter that is less restrictive than that specified by
the flags passed in the third parameter to sqlite3_open_v2().

 cache: The cache parameter may be set to either "shared" or
"private". Setting it to "shared" is equivalent to setting the
SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
sqlite3_open_v2(). Setting the cache parameter to "private" is
equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
If sqlite3_open_v2() is used and the "cache" parameter is present in
a URI filename, its value overrides any behavior requested by setting
SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.

 psow: The psow parameter indicates whether or not the
powersafe overwrite property does or does not apply to the
storage media on which the database file resides.

 nolock: The nolock parameter is a boolean query parameter
which if set disables file locking in rollback journal modes.  This
is useful for accessing a database on a filesystem that does not
support locking.  Caution:  Database corruption might result if two
or more processes write to the same database and any one of those
processes uses nolock=1.

 immutable: The immutable parameter is a boolean query
parameter that indicates that the database file is stored on
read-only media.  When immutable is set, SQLite assumes that the
database file cannot be changed, even by a process with higher
privilege, and so the database is opened read-only and all locking
and change detection is disabled.  Caution: Setting the immutable
property on a database file that does in fact change can result
in incorrect query results and/or SQLITE_CORRUPT errors.
See also: SQLITE_IOCAP_IMMUTABLE.



Specifying an unknown parameter in the query component of a URI is not an
error.  Future versions of SQLite might understand additional query
parameters.  See "query parameters with special meaning to SQLite" for
additional information.


 URI filename examples


 URI filenames  Results
 file:data.db 
Open the file "data.db" in the current directory.
 file:/home/fred/data.db
file:///home/fred/data.db 
file://localhost/home/fred/data.db  
Open the database file "/home/fred/data.db".
 file://darkstar/home/fred/data.db 
An error. "darkstar" is not a recognized authority.

file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
 Windows only: Open the file "data.db" on fred's desktop on drive
C:. Note that the %20 escaping in this example is not strictly
necessary - space characters can be used literally
in URI filenames.
 file:data.db?mode=ro&cache=private 
Open file "data.db" in the current directory for read-only access.
Regardless of whether or not shared-cache mode is enabled by
default, use a private cache.
 file:/home/fred/data.db?vfs=unix-dotfile 
Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
that uses dot-files in place of posix advisory locking.
 file:data.db?mode=readonly 
An error. "readonly" is not a valid option for the "mode" parameter.
Use "ro" instead:  "file:data.db?mode=ro".


URI hexadecimal escape sequences (%HH) are supported within the path and
query components of a URI. A hexadecimal escape sequence consists of a
percent sign - "%" - followed by exactly two hexadecimal digits
specifying an octet value. Before the path or query components of a
URI filename are interpreted, they are encoded using UTF-8 and all
hexadecimal escape sequences replaced by a single byte containing the
corresponding octet. If this process generates an invalid UTF-8 encoding,
the results are undefined.

Note to Windows users:  The encoding used for the filename argument
of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
codepage is currently defined.  Filenames containing international
characters must be converted to UTF-8 prior to passing them into
sqlite3_open() or sqlite3_open_v2().

Note to Windows Runtime users:  The temporary directory must be set
prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
features that require the use of temporary files may fail.

See also: sqlite3_temp_directory
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3
c2: C API: Database Connection Handle
c5: c3ref/sqlite3.html
c4:
Each open SQLite database is represented by a pointer to an instance of
the opaque structure named "sqlite3".  It is useful to think of an sqlite3
pointer as an object.  The sqlite3_open(), sqlite3_open16(), and
sqlite3_open_v2() interfaces are its constructors, and sqlite3_close()
and sqlite3_close_v2() are its destructors.  There are many other
interfaces (such as
sqlite3_prepare_v2(), sqlite3_create_function(), and
sqlite3_busy_timeout() to name but three) that are methods on an
sqlite3 object.
3 Constructors using this object:
 sqlite3_open(),
sqlite3_open16(),
sqlite3_open_v2()
2 Destructors using this object:
 sqlite3_close(),
sqlite3_close_v2()
77 Methods using this object:


sqlite3_autovacuum_pages
sqlite3_blob_open
sqlite3_busy_handler
sqlite3_busy_timeout
sqlite3_changes
sqlite3_changes64
sqlite3_collation_needed
sqlite3_collation_needed16
sqlite3_commit_hook
sqlite3_create_collation
sqlite3_create_collation16
sqlite3_create_collation_v2
sqlite3_create_function
sqlite3_create_function16
sqlite3_create_function_v2
sqlite3_create_module
sqlite3_create_module_v2
sqlite3_create_window_function
sqlite3_db_cacheflush
sqlite3_db_config
sqlite3_db_filename
sqlite3_db_mutex
sqlite3_db_name
sqlite3_db_readonly
sqlite3_db_release_memory
sqlite3_db_status
sqlite3_drop_modules
sqlite3_enable_load_extension
sqlite3_errcode
sqlite3_errmsg
sqlite3_errmsg16
sqlite3_error_offset
sqlite3_errstr
sqlite3_exec
sqlite3_extended_errcode
sqlite3_extended_result_codes
sqlite3_file_control
sqlite3_free_table
sqlite3_get_autocommit
sqlite3_get_clientdata
sqlite3_get_table
sqlite3_interrupt
sqlite3_is_interrupted
sqlite3_last_insert_rowid
sqlite3_limit
sqlite3_load_extension
sqlite3_next_stmt
sqlite3_overload_function
sqlite3_prepare
sqlite3_prepare16
sqlite3_prepare16_v2
sqlite3_prepare16_v3
sqlite3_prepare_v2
sqlite3_prepare_v3
sqlite3_preupdate_blobwrite
sqlite3_preupdate_count
sqlite3_preupdate_depth
sqlite3_preupdate_hook
sqlite3_preupdate_new
sqlite3_preupdate_old
sqlite3_progress_handler
sqlite3_rollback_hook
sqlite3_set_authorizer
sqlite3_set_clientdata
sqlite3_set_last_insert_rowid
sqlite3_system_errno
sqlite3_table_column_metadata
sqlite3_total_changes
sqlite3_total_changes64
sqlite3_trace_v2
sqlite3_txn_state
sqlite3_unlock_notify
sqlite3_update_hook
sqlite3_wal_autocheckpoint
sqlite3_wal_checkpoint
sqlite3_wal_checkpoint_v2
sqlite3_wal_hook



See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_value_encoding()
c2: C API: Report the internal text encoding state of an sqlite3_value object
c5: c3ref/value_encoding.html
c4:
The sqlite3_value_encoding(X) interface returns one of SQLITE_UTF8,
SQLITE_UTF16BE, or SQLITE_UTF16LE according to the current text encoding
of the value X, assuming that X has type TEXT.  If sqlite3_value_type(X)
returns something other than SQLITE_TEXT, then the return value from
sqlite3_value_encoding(X) is meaningless.  Calls to
sqlite3_value_text(X), sqlite3_value_text16(X), sqlite3_value_text16be(X),
sqlite3_value_text16le(X), sqlite3_value_bytes(X), or
sqlite3_value_bytes16(X) might change the encoding of the value X and
thus change the return from subsequent calls to sqlite3_value_encoding(X).

This routine is intended for used by applications that test and validate
the SQLite implementation.  This routine is inquiring about the opaque
internal state of an sqlite3_value object.  Ordinary applications should
not need to know what the internal state of an sqlite3_value object is and
hence should not need to use this interface.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Database Connection Configuration Options
c5: c3ref/c_dbconfig_defensive.html
c0:
SQLITE_DBCONFIG_MAINDBNAME, SQLITE_DBCONFIG_LOOKASIDE, SQLITE_DBCONFIG_ENABLE_FKEY, SQLITE_DBCONFIG_ENABLE_TRIGGER, SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, SQLITE_DBCONFIG_ENABLE_QPSG, SQLITE_DBCONFIG_TRIGGER_EQP, SQLITE_DBCONFIG_RESET_DATABASE, SQLITE_DBCONFIG_DEFENSIVE, SQLITE_DBCONFIG_WRITABLE_SCHEMA, SQLITE_DBCONFIG_LEGACY_ALTER_TABLE, SQLITE_DBCONFIG_DQS_DML, SQLITE_DBCONFIG_DQS_DDL, SQLITE_DBCONFIG_ENABLE_VIEW, SQLITE_DBCONFIG_LEGACY_FILE_FORMAT, SQLITE_DBCONFIG_TRUSTED_SCHEMA, SQLITE_DBCONFIG_STMT_SCANSTATUS, SQLITE_DBCONFIG_REVERSE_SCANORDER, SQLITE_DBCONFIG_MAX

c4:
These constants are the available integer configuration options that
can be passed as the second argument to the sqlite3_db_config() interface.

New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued.  Applications
should check the return code from sqlite3_db_config() to make sure that
the call worked.  The sqlite3_db_config() interface will return a
non-zero error code if a discontinued or unsupported configuration option
is invoked.




SQLITE_DBCONFIG_LOOKASIDE
 This option takes three additional arguments that determine the
lookaside memory allocator configuration for the database connection.
The first argument (the third parameter to sqlite3_db_config() is a
pointer to a memory buffer to use for lookaside memory.
The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
may be NULL in which case SQLite will allocate the
lookaside buffer itself using sqlite3_malloc(). The second argument is the
size of each lookaside buffer slot.  The third argument is the number of
slots.  The size of the buffer in the first argument must be greater than
or equal to the product of the second and third arguments.  The buffer
must be aligned to an 8-byte boundary.  If the second argument to
SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
rounded down to the next smaller multiple of 8.  The lookaside memory
configuration for a database connection can only be changed when that
connection is not currently using lookaside memory, or in other words
when the "current value" returned by
sqlite3_db_status(D,SQLITE_DBSTATUS_LOOKASIDE_USED,...) is zero.
Any attempt to change the lookaside memory configuration when lookaside
memory is in use leaves the configuration unchanged and returns
SQLITE_BUSY.



SQLITE_DBCONFIG_ENABLE_FKEY
 This option is used to enable or disable the enforcement of
foreign key constraints.  There should be two additional arguments.
The first argument is an integer which is 0 to disable FK enforcement,
positive to enable FK enforcement or negative to leave FK enforcement
unchanged.  The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether FK enforcement is off or on
following this call.  The second parameter may be a NULL pointer, in
which case the FK enforcement setting is not reported back. 



SQLITE_DBCONFIG_ENABLE_TRIGGER
 This option is used to enable or disable triggers.
There should be two additional arguments.
The first argument is an integer which is 0 to disable triggers,
positive to enable triggers or negative to leave the setting unchanged.
The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether triggers are disabled or enabled
following this call.  The second parameter may be a NULL pointer, in
which case the trigger setting is not reported back.

Originally this option disabled all triggers.  However, since
SQLite version 3.35.0, TEMP triggers are still allowed even if
this option is off.  So, in other words, this option now only disables
triggers in the main database schema or in the schemas of ATTACH-ed
databases. 



SQLITE_DBCONFIG_ENABLE_VIEW
 This option is used to enable or disable views.
There should be two additional arguments.
The first argument is an integer which is 0 to disable views,
positive to enable views or negative to leave the setting unchanged.
The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether views are disabled or enabled
following this call.  The second parameter may be a NULL pointer, in
which case the view setting is not reported back.

Originally this option disabled all views.  However, since
SQLite version 3.35.0, TEMP views are still allowed even if
this option is off.  So, in other words, this option now only disables
views in the main database schema or in the schemas of ATTACH-ed
databases. 



SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
 This option is used to enable or disable the
fts3_tokenizer() function which is part of the
FTS3 full-text search engine extension.
There should be two additional arguments.
The first argument is an integer which is 0 to disable fts3_tokenizer() or
positive to enable fts3_tokenizer() or negative to leave the setting
unchanged.
The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
following this call.  The second parameter may be a NULL pointer, in
which case the new setting is not reported back. 



SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
 This option is used to enable or disable the sqlite3_load_extension()
interface independently of the load_extension() SQL function.
The sqlite3_enable_load_extension() API enables or disables both the
C-API sqlite3_load_extension() and the SQL function load_extension().
There should be two additional arguments.
When the first argument to this interface is 1, then only the C-API is
enabled and the SQL function remains disabled.  If the first argument to
this interface is 0, then both the C-API and the SQL function are disabled.
If the first argument is -1, then no changes are made to state of either the
C-API or the SQL function.
The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether sqlite3_load_extension() interface
is disabled or enabled following this call.  The second parameter may
be a NULL pointer, in which case the new setting is not reported back.



 SQLITE_DBCONFIG_MAINDBNAME
 This option is used to change the name of the "main" database
schema.  The sole argument is a pointer to a constant UTF8 string
which will become the new schema name in place of "main".  SQLite
does not make a copy of the new main schema name string, so the application
must ensure that the argument passed into this DBCONFIG option is unchanged
until after the database connection closes.




SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
 Usually, when a database in wal mode is closed or detached from a
database handle, SQLite checks if this will mean that there are now no
connections at all to the database. If so, it performs a checkpoint
operation before closing the connection. This option may be used to
override this behavior. The first parameter passed to this operation
is an integer - positive to disable checkpoints-on-close, or zero (the
default) to enable them, and negative to leave the setting unchanged.
The second parameter is a pointer to an integer
into which is written 0 or 1 to indicate whether checkpoints-on-close
have been disabled - 0 if they are not disabled, 1 if they are.



 SQLITE_DBCONFIG_ENABLE_QPSG
The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
the query planner stability guarantee (QPSG).  When the QPSG is active,
a single SQL query statement will always use the same algorithm regardless
of values of bound parameters. The QPSG disables some query optimizations
that look at the values of bound parameters, which can make some queries
slower.  But the QPSG has the advantage of more predictable behavior.  With
the QPSG active, SQLite will always use the same query plan in the field as
was used during testing in the lab.
The first argument to this setting is an integer which is 0 to disable
the QPSG, positive to enable QPSG, or negative to leave the setting
unchanged. The second parameter is a pointer to an integer into which
is written 0 or 1 to indicate whether the QPSG is disabled or enabled
following this call.



 SQLITE_DBCONFIG_TRIGGER_EQP
 By default, the output of EXPLAIN QUERY PLAN commands does not
include output for any operations performed by trigger programs. This
option is used to set or clear (the default) a flag that governs this
behavior. The first parameter passed to this operation is an integer -
positive to enable output for trigger programs, or zero to disable it,
or negative to leave the setting unchanged.
The second parameter is a pointer to an integer into which is written
0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
it is not disabled, 1 if it is.



 SQLITE_DBCONFIG_RESET_DATABASE
 Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
VACUUM in order to reset a database back to an empty database
with no schema and no content. The following process works even for
a badly corrupted database file:

 If the database connection is newly opened, make sure it has read the
database schema by preparing then discarding some query against the
database, or calling sqlite3_table_column_metadata(), ignoring any
errors.  This step is only necessary if the application desires to keep
the database in WAL mode after the reset if it was in WAL mode before
the reset.
 sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
 sqlite3_exec(db, "VACUUM", 0, 0, 0);
 sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);

Because resetting a database is destructive and irreversible, the
process requires the use of this obscure API and multiple steps to
help ensure that it does not happen by accident. Because this
feature must be capable of resetting corrupt databases, and
shutting down virtual tables may require access to that corrupt
storage, the library must abandon any installed virtual tables
without calling their xDestroy() methods.


 SQLITE_DBCONFIG_DEFENSIVE
The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
"defensive" flag for a database connection.  When the defensive
flag is enabled, language features that allow ordinary SQL to
deliberately corrupt the database file are disabled.  The disabled
features include but are not limited to the following:

 The PRAGMA writable_schema=ON statement.
 The PRAGMA journal_mode=OFF statement.
 The PRAGMA schema_version=N statement.
 Writes to the sqlite_dbpage virtual table.
 Direct writes to shadow tables.




 SQLITE_DBCONFIG_WRITABLE_SCHEMA
The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
"writable_schema" flag. This has the same effect and is logically equivalent
to setting PRAGMA writable_schema=ON or PRAGMA writable_schema=OFF.
The first argument to this setting is an integer which is 0 to disable
the writable_schema, positive to enable writable_schema, or negative to
leave the setting unchanged. The second parameter is a pointer to an
integer into which is written 0 or 1 to indicate whether the writable_schema
is enabled or disabled following this call.




SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
the legacy behavior of the ALTER TABLE RENAME command such it
behaves as it did prior to version 3.24.0 (2018-06-04).  See the
"Compatibility Notice" on the ALTER TABLE RENAME documentation for
additional information. This feature can also be turned on and off
using the PRAGMA legacy_alter_table statement.




SQLITE_DBCONFIG_DQS_DML
The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
the legacy double-quoted string literal misfeature for DML statements
only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
default value of this setting is determined by the -DSQLITE_DQS
compile-time option.




SQLITE_DBCONFIG_DQS_DDL
The SQLITE_DBCONFIG_DQS option activates or deactivates
the legacy double-quoted string literal misfeature for DDL statements,
such as CREATE TABLE and CREATE INDEX. The
default value of this setting is determined by the -DSQLITE_DQS
compile-time option.




SQLITE_DBCONFIG_TRUSTED_SCHEMA
The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
assume that database schemas are untainted by malicious content.
When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
takes additional defensive steps to protect the application from harm
including:

 Prohibit the use of SQL functions inside triggers, views,
CHECK constraints, DEFAULT clauses, expression indexes,
partial indexes, or generated columns
unless those functions are tagged with SQLITE_INNOCUOUS.
 Prohibit the use of virtual tables inside of triggers or views
unless those virtual tables are tagged with SQLITE_VTAB_INNOCUOUS.

This setting defaults to "on" for legacy compatibility, however
all applications are advised to turn it off if possible. This setting
can also be controlled using the PRAGMA trusted_schema statement.




SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
the legacy file format flag.  When activated, this flag causes all newly
created database file to have a schema format version number (the 4-byte
integer found at offset 44 into the database header) of 1.  This in turn
means that the resulting database file will be readable and writable by
any SQLite version back to 3.0.0 (2004-06-18).  Without this setting,
newly created databases are generally not understandable by SQLite versions
prior to 3.3.0 (2006-01-11).  As these words are written, there
is now scarcely any need to generate database files that are compatible
all the way back to version 3.0.0, and so this setting is of little
practical use, but is provided so that SQLite can continue to claim the
ability to generate new database files that are compatible with  version
3.0.0.
Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
the VACUUM command will fail with an obscure error when attempting to
process a table with generated columns and a descending index.  This is
not considered a bug since SQLite versions 3.3.0 and earlier do not support
either generated columns or descending indexes.




SQLITE_DBCONFIG_STMT_SCANSTATUS
The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in
SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears
a flag that enables collection of the sqlite3_stmt_scanstatus_v2()
statistics. For statistics to be collected, the flag must be set on
the database handle both when the SQL statement is prepared and when it
is stepped. The flag is set (collection of statistics is enabled)
by default.  This option takes two arguments: an integer and a pointer to
an integer..  The first argument is 1, 0, or -1 to enable, disable, or
leave unchanged the statement scanstatus option.  If the second argument
is not NULL, then the value of the statement scanstatus setting after
processing the first argument is written into the integer that the second
argument points to.




SQLITE_DBCONFIG_REVERSE_SCANORDER
The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order
in which tables and indexes are scanned so that the scans start at the end
and work toward the beginning rather than starting at the beginning and
working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the
same as setting PRAGMA reverse_unordered_selects.  This option takes
two arguments which are an integer and a pointer to an integer.  The first
argument is 1, 0, or -1 to enable, disable, or leave unchanged the
reverse scan order flag, respectively.  If the second argument is not NULL,
then 0 or 1 is written into the integer that the second argument points to
depending on if the reverse scan order flag is set after processing the
first argument.



See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_vtab_in()
c2: C API: Identify and handle IN constraints in xBestIndex
c5: c3ref/vtab_in.html
c4:
This interface may only be used from within an
xBestIndex() method of a virtual table implementation.
The result of invoking this interface from any other context is
undefined and probably harmful.

A constraint on a virtual table of the form
"column IN (...)" is
communicated to the xBestIndex method as a
SQLITE_INDEX_CONSTRAINT_EQ constraint.  If xBestIndex wants to use
this constraint, it must set the corresponding
aConstraintUsage[].argvIndex to a positive integer.  Then, under
the usual mode of handling IN operators, SQLite generates bytecode
that invokes the xFilter() method once for each value
on the right-hand side of the IN operator.  Thus the virtual table
only sees a single value from the right-hand side of the IN operator
at a time.

In some cases, however, it would be advantageous for the virtual
table to see all values on the right-hand of the IN operator all at
once.  The sqlite3_vtab_in() interfaces facilitates this in two ways:



A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
if and only if the P->aConstraint[N] constraint
is an IN operator that can be processed all at once.  In other words,
sqlite3_vtab_in() with -1 in the third argument is a mechanism
by which the virtual table can ask SQLite if all-at-once processing
of the IN operator is even possible.


A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
to SQLite that the virtual table does or does not want to process
the IN operator all-at-once, respectively.  Thus when the third
parameter (F) is non-negative, this interface is the mechanism by
which the virtual table tells SQLite how it wants to process the
IN operator.


The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
within the same xBestIndex method call.  For any given P,N pair,
the return value from sqlite3_vtab_in(P,N,F) will always be the same
within the same xBestIndex call.  If the interface returns true
(non-zero), that means that the constraint is an IN operator
that can be processed all-at-once.  If the constraint is not an IN
operator or cannot be processed all-at-once, then the interface returns
false.

All-at-once processing of the IN operator is selected if both of the
following conditions are met:


 The P->aConstraintUsage[N].argvIndex value is set to a positive
integer.  This is how the virtual table tells SQLite that it wants to
use the N-th constraint.

 The last call to sqlite3_vtab_in(P,N,F) for which F was
non-negative had F>=1.


If either or both of the conditions above are false, then SQLite uses
the traditional one-at-a-time processing strategy for the IN constraint.
If both conditions are true, then the argvIndex-th parameter to the
xFilter method will be an sqlite3_value that appears to be NULL,
but which can be passed to sqlite3_vtab_in_first() and
sqlite3_vtab_in_next() to find all values on the right-hand side
of the IN constraint.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_STATIC, SQLITE_TRANSIENT
c2: C API: Constants Defining Special Destructor Behavior
c5: c3ref/c_static.html
c4:
These are special values for the destructor that is passed in as the
final argument to routines like sqlite3_result_blob().  If the destructor
argument is SQLITE_STATIC, it means that the content pointer is constant
and will never change.  It does not need to be destroyed.  The
SQLITE_TRANSIENT value means that the content will likely change in
the near future and that SQLite should make its own private copy of
the content before returning.

The typedef is necessary to work around problems in certain
C++ compilers.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_pcache_methods2
c2: C API: Application Defined Page Cache.
c5: c3ref/pcache_methods2.html
c4:
The sqlite3_config(SQLITE_CONFIG_PCACHE2, ...) interface can
register an alternative page cache implementation by passing in an
instance of the sqlite3_pcache_methods2 structure.
In many applications, most of the heap memory allocated by
SQLite is used for the page cache.
By implementing a
custom page cache using this API, an application can better control
the amount of memory consumed by SQLite, the way in which
that memory is allocated and released, and the policies used to
determine exactly which parts of a database file are cached and for
how long.

The alternative page cache mechanism is an
extreme measure that is only needed by the most demanding applications.
The built-in page cache is recommended for most uses.

The contents of the sqlite3_pcache_methods2 structure are copied to an
internal buffer by SQLite within the call to sqlite3_config.  Hence
the application may discard the parameter after the call to
sqlite3_config() returns.



The xInit() method is called once for each effective
call to sqlite3_initialize()
(usually only once during the lifetime of the process). The xInit()
method is passed a copy of the sqlite3_pcache_methods2.pArg value.
The intent of the xInit() method is to set up global data structures
required by the custom page cache implementation.
If the xInit() method is NULL, then the
built-in default page cache is used instead of the application defined
page cache.



The xShutdown() method is called by sqlite3_shutdown().
It can be used to clean up
any outstanding resources before process shutdown, if required.
The xShutdown() method may be NULL.

SQLite automatically serializes calls to the xInit method,
so the xInit method need not be threadsafe.  The
xShutdown method is only called from sqlite3_shutdown() so it does
not need to be threadsafe either.  All other methods must be threadsafe
in multithreaded applications.

SQLite will never invoke xInit() more than once without an intervening
call to xShutdown().



SQLite invokes the xCreate() method to construct a new cache instance.
SQLite will typically create one cache instance for each open database file,
though this is not guaranteed. The
first parameter, szPage, is the size in bytes of the pages that must
be allocated by the cache.  szPage will always a power of two.  The
second parameter szExtra is a number of bytes of extra storage
associated with each page cache entry.  The szExtra parameter will
a number less than 250.  SQLite will use the
extra szExtra bytes on each page to store metadata about the underlying
database page on disk.  The value passed into szExtra depends
on the SQLite version, the target platform, and how SQLite was compiled.
The third argument to xCreate(), bPurgeable, is true if the cache being
created will be used to cache database pages of a file stored on disk, or
false if it is used for an in-memory database. The cache implementation
does not have to do anything special based with the value of bPurgeable;
it is purely advisory.  On a cache where bPurgeable is false, SQLite will
never invoke xUnpin() except to deliberately delete a page.
In other words, calls to xUnpin() on a cache with bPurgeable set to
false will always have the "discard" flag set to true.
Hence, a cache created with bPurgeable false will
never contain any unpinned pages.



The xCachesize() method may be called at any time by SQLite to set the
suggested maximum cache-size (number of pages stored by) the cache
instance passed as the first argument. This is the value configured using
the SQLite "PRAGMA cache_size" command.  As with the bPurgeable
parameter, the implementation is not required to do anything with this
value; it is advisory only.



The xPagecount() method must return the number of pages currently
stored in the cache, both pinned and unpinned.



The xFetch() method locates a page in the cache and returns a pointer to
an sqlite3_pcache_page object associated with that page, or a NULL pointer.
The pBuf element of the returned sqlite3_pcache_page object will be a
pointer to a buffer of szPage bytes used to store the content of a
single database page.  The pExtra element of sqlite3_pcache_page will be
a pointer to the szExtra bytes of extra storage that SQLite has requested
for each entry in the page cache.

The page to be fetched is determined by the key. The minimum key value
is 1.  After it has been retrieved using xFetch, the page is considered
to be "pinned".

If the requested page is already in the page cache, then the page cache
implementation must return a pointer to the page buffer with its content
intact.  If the requested page is not already in the cache, then the
cache implementation should use the value of the createFlag
parameter to help it determined what action to take:


 createFlag  Behavior when page is not already in cache
 0  Do not allocate a new page.  Return NULL.
 1  Allocate a new page if it easy and convenient to do so.
Otherwise return NULL.
 2  Make every effort to allocate a new page.  Only return
NULL if allocating a new page is effectively impossible.


SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite
will only use a createFlag of 2 after a prior call with a createFlag of 1
failed.  In between the xFetch() calls, SQLite may
attempt to unpin one or more cache pages by spilling the content of
pinned pages to disk and synching the operating system disk cache.



xUnpin() is called by SQLite with a pointer to a currently pinned page
as its second argument.  If the third parameter, discard, is non-zero,
then the page must be evicted from the cache.
If the discard parameter is
zero, then the page may be discarded or retained at the discretion of
page cache implementation. The page cache implementation
may choose to evict unpinned pages at any time.

The cache must not perform any reference counting. A single
call to xUnpin() unpins the page regardless of the number of prior calls
to xFetch().



The xRekey() method is used to change the key value associated with the
page passed as the second argument. If the cache
previously contains an entry associated with newKey, it must be
discarded. Any prior cache entry associated with newKey is guaranteed not
to be pinned.

When SQLite calls the xTruncate() method, the cache must discard all
existing cache entries with page numbers (keys) greater than or equal
to the value of the iLimit parameter passed to xTruncate(). If any
of these pages are pinned, they are implicitly unpinned, meaning that
they can be safely discarded.



The xDestroy() method is used to delete a cache allocated by xCreate().
All resources associated with the specified cache should be freed. After
calling the xDestroy() method, SQLite considers the sqlite3_pcache*
handle invalid, and will not use it with any other sqlite3_pcache_methods2
functions.



SQLite invokes the xShrink() method when it wants the page cache to
free up as much of heap memory as possible.  The page cache implementation
is not obligated to free any memory, but well-behaved implementations should
do their best.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_vtab_config()
c2: C API: Virtual Table Interface Configuration
c5: c3ref/vtab_config.html
c4:
This function may be called by either the xConnect or xCreate method
of a virtual table implementation to configure
various facets of the virtual table interface.

If this interface is invoked outside the context of an xConnect or
xCreate virtual table method then the behavior is undefined.

In the call sqlite3_vtab_config(D,C,...) the D parameter is the
database connection in which the virtual table is being created and
which is passed in as the first argument to the xConnect or xCreate
method that is invoking sqlite3_vtab_config().  The C parameter is one
of the virtual table configuration options.  The presence and meaning
of parameters after C depend on which virtual table configuration option
is used.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_snapshot_recover()
c2: C API: Recover snapshots from a wal file
c5: c3ref/snapshot_recover.html
c4:
If a WAL file remains on disk after all database connections close
(either through the use of the SQLITE_FCNTL_PERSIST_WAL file control
or because the last process to have the database opened exited without
calling sqlite3_close()) and a new connection is subsequently opened
on that database and WAL file, the sqlite3_snapshot_open() interface
will only be able to open the last transaction added to the WAL file
even though the WAL file contains other valid transactions.

This function attempts to scan the WAL file associated with database zDb
of database handle db and make all valid snapshots available to
sqlite3_snapshot_open(). It is an error if there is already a read
transaction open on the database, or if the database is not a WAL mode
database.

SQLITE_OK is returned if successful, or an SQLite error code otherwise.

This interface is only available if SQLite is compiled with the
SQLITE_ENABLE_SNAPSHOT option.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_str
c2: C API: Dynamic String Object
c5: c3ref/str.html
c4:
An instance of the sqlite3_str object contains a dynamically-sized
string under construction.

The lifecycle of an sqlite3_str object is as follows:

 The sqlite3_str object is created using sqlite3_str_new().
 Text is appended to the sqlite3_str object using various
methods, such as sqlite3_str_appendf().
 The sqlite3_str object is destroyed and the string it created
is returned using the sqlite3_str_finish() interface.

1 Constructor using this object: sqlite3_str_new()
1 Destructor using this object: sqlite3_str_finish()
9 Methods using this object:


sqlite3_str_append
sqlite3_str_appendall
sqlite3_str_appendchar
sqlite3_str_appendf
sqlite3_str_errcode
sqlite3_str_length
sqlite3_str_reset
sqlite3_str_value
sqlite3_str_vappendf



See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_handle()
c2: C API: Find The Database Handle Of A Prepared Statement
c5: c3ref/db_handle.html
c4:
The sqlite3_db_handle interface returns the database connection handle
to which a prepared statement belongs.  The database connection
returned by sqlite3_db_handle is the same database connection
that was the first argument
to the sqlite3_prepare_v2() call (or its variants) that was used to
create the statement in the first place.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_soft_heap_limit64(), sqlite3_hard_heap_limit64()
c2: C API: Impose A Limit On Heap Size
c5: c3ref/hard_heap_limit64.html
c4:
These interfaces impose limits on the amount of heap memory that will be
by all database connections within a single process.

The sqlite3_soft_heap_limit64() interface sets and/or queries the
soft limit on the amount of heap memory that may be allocated by SQLite.
SQLite strives to keep heap memory utilization below the soft heap
limit by reducing the number of pages held in the page cache
as heap memory usages approaches the limit.
The soft heap limit is "soft" because even though SQLite strives to stay
below the limit, it will exceed the limit rather than generate
an SQLITE_NOMEM error.  In other words, the soft heap limit
is advisory only.

The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of
N bytes on the amount of memory that will be allocated.  The
sqlite3_hard_heap_limit64(N) interface is similar to
sqlite3_soft_heap_limit64(N) except that memory allocations will fail
when the hard heap limit is reached.

The return value from both sqlite3_soft_heap_limit64() and
sqlite3_hard_heap_limit64() is the size of
the heap limit prior to the call, or negative in the case of an
error.  If the argument N is negative
then no change is made to the heap limit.  Hence, the current
size of heap limits can be determined by invoking
sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).

Setting the heap limits to zero disables the heap limiter mechanism.

The soft heap limit may not be greater than the hard heap limit.
If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
is invoked with a value of N that is greater than the hard heap limit,
the soft heap limit is set to the value of the hard heap limit.
The soft heap limit is automatically enabled whenever the hard heap
limit is enabled. When sqlite3_hard_heap_limit64(N) is invoked and
the soft heap limit is outside the range of 1..N, then the soft heap
limit is set to N.  Invoking sqlite3_soft_heap_limit64(0) when the
hard heap limit is enabled makes the soft heap limit equal to the
hard heap limit.

The memory allocation limits can also be adjusted using
PRAGMA soft_heap_limit and PRAGMA hard_heap_limit.

The heap limits are not enforced in the current implementation
if one or more of following conditions are true:


 The limit value is set to zero.
 Memory accounting is disabled using a combination of the
sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) start-time option and
the SQLITE_DEFAULT_MEMSTATUS compile-time option.
 An alternative page cache implementation is specified using
sqlite3_config(SQLITE_CONFIG_PCACHE2,...).
 The page cache allocates from its own memory pool supplied
by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) rather than
from the heap.


The circumstances under which SQLite will enforce the heap limits may
changes in future releases of SQLite.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_module
c2: C API: Virtual Table Object
c5: c3ref/module.html
c4:
This structure, sometimes called a "virtual table module",
defines the implementation of a virtual table.
This structure consists mostly of methods for the module.

A virtual table module is created by filling in a persistent
instance of this structure and passing a pointer to that instance
to sqlite3_create_module() or sqlite3_create_module_v2().
The registration remains valid until it is replaced by a different
module or until the database connection closes.  The content
of this structure must not change while it is registered with
any database connection.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_snapshot_get()
c2: C API: Record A Database Snapshot
c5: c3ref/snapshot_get.html
c4:
The sqlite3_snapshot_get(D,S,P) interface attempts to make a
new sqlite3_snapshot object that records the current state of
schema S in database connection D.  On success, the
sqlite3_snapshot_get(D,S,P) interface writes a pointer to the newly
created sqlite3_snapshot object into *P and returns SQLITE_OK.
If there is not already a read-transaction open on schema S when
this function is called, one is opened automatically.

The following must be true for this function to succeed. If any of
the following statements are false when sqlite3_snapshot_get() is
called, SQLITE_ERROR is returned. The final value of *P is undefined
in this case.


 The database handle must not be in autocommit mode.

 Schema S of database connection D must be a WAL mode database.

 There must not be a write transaction open on schema S of database
connection D.

 One or more transactions must have been written to the current wal
file since it was created on disk (by any connection). This means
that a snapshot cannot be taken on a wal mode database with no wal
file immediately after it is first opened. At least one transaction
must be written to it first.


This function may also return SQLITE_NOMEM.  If it is called with the
database handle in autocommit mode but fails for some other reason,
whether or not a read transaction is opened on schema S is undefined.

The sqlite3_snapshot object returned from a successful call to
sqlite3_snapshot_get() must be freed using sqlite3_snapshot_free()
to avoid a memory leak.

The sqlite3_snapshot_get() interface is only available when the
SQLITE_ENABLE_SNAPSHOT compile-time option is used.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_get_clientdata(), sqlite3_set_clientdata()
c2: C API: Database Connection Client Data
c5: c3ref/get_clientdata.html
c4:
These functions are used to associate one or more named pointers
with a database connection.
A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P
to be attached to database connection D using name N.  Subsequent
calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P
or a NULL pointer if there were no prior calls to
sqlite3_set_clientdata() with the same values of D and N.
Names are compared using strcmp() and are thus case sensitive.

If P and X are both non-NULL, then the destructor X is invoked with
argument P on the first of the following occurrences:

 An out-of-memory error occurs during the call to
sqlite3_set_clientdata() which attempts to register pointer P.
 A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made
with the same D and N parameters.
 The database connection closes.  SQLite does not make any guarantees
about the order in which destructors are called, only that all
destructors will be called exactly once at some point during the
database connection closing process.


SQLite does not do anything with client data other than invoke
destructors on the client data at the appropriate time.  The intended
use for client data is to provide a mechanism for wrapper libraries
to store additional information about an SQLite database connection.

There is no limit (other than available memory) on the number of different
client data pointers (with different names) that can be attached to a
single database connection.  However, the implementation is optimized
for the case of having only one or two different client data names.
Applications and wrapper libraries are discouraged from using more than
one client data name each.

There is no way to enumerate the client data pointers
associated with a database connection.  The N parameter can be thought
of as a secret key such that only code that knows the secret key is able
to access the associated data.

Security Warning:  These interfaces should not be exposed in scripting
languages or in other circumstances where it might be possible for an
an attacker to invoke them.  Any agent that can invoke these interfaces
can probably also take control of the process.

Database connection client data is only available for SQLite
version 3.44.0 (2023-11-01) and later.

See also: sqlite3_set_auxdata() and sqlite3_get_auxdata().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_bind_parameter_count()
c2: C API: Number Of SQL Parameters
c5: c3ref/bind_parameter_count.html
c4:
This routine can be used to find the number of SQL parameters
in a prepared statement.  SQL parameters are tokens of the
form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
placeholders for values that are bound
to the parameters at a later time.

This routine actually returns the index of the largest (rightmost)
parameter. For all forms except ?NNN, this will correspond to the
number of unique parameters.  If parameters of the ?NNN form are used,
there may be gaps in the list.

See also: sqlite3_bind(),
sqlite3_bind_parameter_name(), and
sqlite3_bind_parameter_index().
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Evaluate An SQL Statement
c5: c3ref/step.html
c4:
After a prepared statement has been prepared using any of
sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
or sqlite3_prepare16_v3() or one of the legacy
interfaces sqlite3_prepare() or sqlite3_prepare16(), this function
must be called one or more times to evaluate the statement.

The details of the behavior of the sqlite3_step() interface depend
on whether the statement was prepared using the newer "vX" interfaces
sqlite3_prepare_v3(), sqlite3_prepare_v2(), sqlite3_prepare16_v3(),
sqlite3_prepare16_v2() or the older legacy
interfaces sqlite3_prepare() and sqlite3_prepare16().  The use of the
new "vX" interface is recommended for new applications but the legacy
interface will continue to be supported.

In the legacy interface, the return value will be either SQLITE_BUSY,
SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.
With the "v2" interface, any of the other result codes or
extended result codes might be returned as well.

SQLITE_BUSY means that the database engine was unable to acquire the
database locks it needs to do its job.  If the statement is a COMMIT
or occurs outside of an explicit transaction, then you can retry the
statement.  If the statement is not a COMMIT and occurs within an
explicit transaction then you should rollback the transaction before
continuing.

SQLITE_DONE means that the statement has finished executing
successfully.  sqlite3_step() should not be called again on this virtual
machine without first calling sqlite3_reset() to reset the virtual
machine back to its initial state.

If the SQL statement being executed returns any data, then SQLITE_ROW
is returned each time a new row of data is ready for processing by the
caller. The values may be accessed using the column access functions.
sqlite3_step() is called again to retrieve the next row of data.

SQLITE_ERROR means that a run-time error (such as a constraint
violation) has occurred.  sqlite3_step() should not be called again on
the VM. More information may be found by calling sqlite3_errmsg().
With the legacy interface, a more specific error code (for example,
SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, and so forth)
can be obtained by calling sqlite3_reset() on the
prepared statement.  In the "v2" interface,
the more specific error code is returned directly by sqlite3_step().

SQLITE_MISUSE means that the this routine was called inappropriately.
Perhaps it was called on a prepared statement that has
already been finalized or on one that had
previously returned SQLITE_ERROR or SQLITE_DONE.  Or it could
be the case that the same database connection is being used by two or
more threads at the same moment in time.

For all versions of SQLite up to and including 3.6.23.1, a call to
sqlite3_reset() was required after sqlite3_step() returned anything
other than SQLITE_ROW before any subsequent invocation of
sqlite3_step().  Failure to reset the prepared statement using
sqlite3_reset() would result in an SQLITE_MISUSE return from
sqlite3_step().  But after version 3.6.23.1 (2010-03-26,
sqlite3_step() began
calling sqlite3_reset() automatically in this circumstance rather
than returning SQLITE_MISUSE.  This is not considered a compatibility
break because any application that ever receives an SQLITE_MISUSE error
is broken by definition.  The SQLITE_OMIT_AUTORESET compile-time option
can be used to restore the legacy behavior.

Goofy Interface Alert: In the legacy interface, the sqlite3_step()
API always returns a generic error code, SQLITE_ERROR, following any
error other than SQLITE_BUSY and SQLITE_MISUSE.  You must call
sqlite3_reset() or sqlite3_finalize() in order to find one of the
specific error codes that better describes the error.
We admit that this is a goofy design.  The problem has been fixed
with the "v2" interface.  If you prepare all of your SQL statements
using sqlite3_prepare_v3() or sqlite3_prepare_v2()
or sqlite3_prepare16_v2() or sqlite3_prepare16_v3() instead
of the legacy sqlite3_prepare() and sqlite3_prepare16() interfaces,
then the more specific error codes are returned directly
by sqlite3_step().  The use of the "vX" interfaces is recommended.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_column_count()
c2: C API: Number Of Columns In A Result Set
c5: c3ref/column_count.html
c4:
Return the number of columns in the result set returned by the
prepared statement. If this routine returns 0, that means the
prepared statement returns no data (for example an UPDATE).
However, just because this routine returns a positive number does not
mean that one or more rows of data will be returned.  A SELECT statement
will always have a positive sqlite3_column_count() but depending on the
WHERE clause constraints and the table content, it might return no rows.

See also: sqlite3_data_count()
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Testing Interface Operation Codes
c5: c3ref/c_testctrl_always.html
c0:
SQLITE_TESTCTRL_FIRST, SQLITE_TESTCTRL_PRNG_SAVE, SQLITE_TESTCTRL_PRNG_RESTORE, SQLITE_TESTCTRL_PRNG_RESET, SQLITE_TESTCTRL_FK_NO_ACTION, SQLITE_TESTCTRL_BITVEC_TEST, SQLITE_TESTCTRL_FAULT_INSTALL, SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS, SQLITE_TESTCTRL_PENDING_BYTE, SQLITE_TESTCTRL_ASSERT, SQLITE_TESTCTRL_ALWAYS, SQLITE_TESTCTRL_RESERVE, SQLITE_TESTCTRL_JSON_SELFCHECK, SQLITE_TESTCTRL_OPTIMIZATIONS, SQLITE_TESTCTRL_ISKEYWORD, SQLITE_TESTCTRL_SCRATCHMALLOC, SQLITE_TESTCTRL_INTERNAL_FUNCTIONS, SQLITE_TESTCTRL_LOCALTIME_FAULT, SQLITE_TESTCTRL_EXPLAIN_STMT, SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD, SQLITE_TESTCTRL_NEVER_CORRUPT, SQLITE_TESTCTRL_VDBE_COVERAGE, SQLITE_TESTCTRL_BYTEORDER, SQLITE_TESTCTRL_ISINIT, SQLITE_TESTCTRL_SORTER_MMAP, SQLITE_TESTCTRL_IMPOSTER, SQLITE_TESTCTRL_PARSER_COVERAGE, SQLITE_TESTCTRL_RESULT_INTREAL, SQLITE_TESTCTRL_PRNG_SEED, SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS, SQLITE_TESTCTRL_SEEK_COUNT, SQLITE_TESTCTRL_TRACEFLAGS, SQLITE_TESTCTRL_TUNE, SQLITE_TESTCTRL_LOGEST, SQLITE_TESTCTRL_USELONGDOUBLE, SQLITE_TESTCTRL_LAST

c4:
These constants are the valid operation code parameters used
as the first argument to sqlite3_test_control().

These parameters and their meanings are subject to change
without notice.  These values are for testing purposes only.
Applications should not use any of these parameters or the
sqlite3_test_control() interface.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_pcache_page
c2: C API: Custom Page Cache Object
c5: c3ref/pcache_page.html
c4:
The sqlite3_pcache_page object represents a single page in the
page cache.  The page cache will allocate instances of this
object.  Various methods of the page cache use pointers to instances
of this object as parameters or as their return value.

See sqlite3_pcache_methods2 for additional information.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Status Parameters
c5: c3ref/c_status_malloc_count.html
c0:
SQLITE_STATUS_MEMORY_USED, SQLITE_STATUS_PAGECACHE_USED, SQLITE_STATUS_PAGECACHE_OVERFLOW, SQLITE_STATUS_SCRATCH_USED, SQLITE_STATUS_SCRATCH_OVERFLOW, SQLITE_STATUS_MALLOC_SIZE, SQLITE_STATUS_PARSER_STACK, SQLITE_STATUS_PAGECACHE_SIZE, SQLITE_STATUS_SCRATCH_SIZE, SQLITE_STATUS_MALLOC_COUNT

c4:
These integer constants designate various run-time status parameters
that can be returned by sqlite3_status().



 SQLITE_STATUS_MEMORY_USED
This parameter is the current amount of memory checked out
using sqlite3_malloc(), either directly or indirectly.  The
figure includes calls made to sqlite3_malloc() by the application
and internal memory usage by the SQLite library.  Auxiliary page-cache
memory controlled by SQLITE_CONFIG_PAGECACHE is not included in
this parameter.  The amount returned is the sum of the allocation
sizes as reported by the xSize method in sqlite3_mem_methods.


 SQLITE_STATUS_MALLOC_SIZE
This parameter records the largest memory allocation request
handed to sqlite3_malloc() or sqlite3_realloc() (or their
internal equivalents).  Only the value returned in the
*pHighwater parameter to sqlite3_status() is of interest.
The value written into the *pCurrent parameter is undefined.


 SQLITE_STATUS_MALLOC_COUNT
This parameter records the number of separate memory allocations
currently checked out.


 SQLITE_STATUS_PAGECACHE_USED
This parameter returns the number of pages used out of the
pagecache memory allocator that was configured using
SQLITE_CONFIG_PAGECACHE.  The
value returned is in pages, not in bytes.



SQLITE_STATUS_PAGECACHE_OVERFLOW
This parameter returns the number of bytes of page cache
allocation which could not be satisfied by the SQLITE_CONFIG_PAGECACHE
buffer and where forced to overflow to sqlite3_malloc().  The
returned value includes allocations that overflowed because they
where too large (they were larger than the "sz" parameter to
SQLITE_CONFIG_PAGECACHE) and allocations that overflowed because
no space was left in the page cache.


 SQLITE_STATUS_PAGECACHE_SIZE
This parameter records the largest memory allocation request
handed to the pagecache memory allocator.  Only the value returned in the
*pHighwater parameter to sqlite3_status() is of interest.
The value written into the *pCurrent parameter is undefined.


 SQLITE_STATUS_SCRATCH_USED
No longer used.


 SQLITE_STATUS_SCRATCH_OVERFLOW
No longer used.


 SQLITE_STATUS_SCRATCH_SIZE
No longer used.


 SQLITE_STATUS_PARSER_STACK
The *pHighwater parameter records the deepest parser stack.
The *pCurrent value is undefined.  The *pHighwater value is only
meaningful if SQLite is compiled with YYTRACKMAXSTACKDEPTH.


New status parameters may be added from time to time.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Compiling An SQL Statement
c5: c3ref/prepare.html
c0:
sqlite3_prepare(), sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16(), sqlite3_prepare16_v2(), sqlite3_prepare16_v3()

c4:
To execute an SQL statement, it must first be compiled into a byte-code
program using one of these routines.  Or, in other words, these routines
are constructors for the prepared statement object.

The preferred routine to use is sqlite3_prepare_v2().  The
sqlite3_prepare() interface is legacy and should be avoided.
sqlite3_prepare_v3() has an extra "prepFlags" option that is used
for special purposes.

The use of the UTF-8 interfaces is preferred, as SQLite currently
does all parsing using UTF-8.  The UTF-16 interfaces are provided
as a convenience.  The UTF-16 interfaces work by converting the
input text into UTF-8, then invoking the corresponding UTF-8 interface.

The first argument, "db", is a database connection obtained from a
prior successful call to sqlite3_open(), sqlite3_open_v2() or
sqlite3_open16().  The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded
as either UTF-8 or UTF-16.  The sqlite3_prepare(), sqlite3_prepare_v2(),
and sqlite3_prepare_v3()
interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
and sqlite3_prepare16_v3() use UTF-16.

If the nByte argument is negative, then zSql is read up to the
first zero terminator. If nByte is positive, then it is the
number of bytes read from zSql.  If nByte is zero, then no prepared
statement is generated.
If the caller knows that the supplied string is nul-terminated, then
there is a small performance advantage to passing an nByte parameter that
is the number of bytes in the input string including
the nul-terminator.

If pzTail is not NULL then *pzTail is made to point to the first byte
past the end of the first SQL statement in zSql.  These routines only
compile the first statement in zSql, so *pzTail is left pointing to
what remains uncompiled.

*ppStmt is left pointing to a compiled prepared statement that can be
executed using sqlite3_step().  If there is an error, *ppStmt is set
to NULL.  If the input text contains no SQL (if the input is an empty
string or a comment) then *ppStmt is set to NULL.
The calling procedure is responsible for deleting the compiled
SQL statement using sqlite3_finalize() after it has finished with it.
ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQLITE_OK;
otherwise an error code is returned.

The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
are retained for backwards compatibility, but their use is discouraged.
In the "vX" interfaces, the prepared statement
that is returned (the sqlite3_stmt object) contains a copy of the
original SQL text. This causes the sqlite3_step() interface to
behave differently in three ways:



If the database schema changes, instead of returning SQLITE_SCHEMA as it
always used to do, sqlite3_step() will automatically recompile the SQL
statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY
retries will occur before sqlite3_step() gives up and returns an error.



When an error occurs, sqlite3_step() will return one of the detailed
error codes or extended error codes.  The legacy behavior was that
sqlite3_step() would only return a generic SQLITE_ERROR result code
and the application would have to make a second call to sqlite3_reset()
in order to find the underlying cause of the problem. With the "v2" prepare
interfaces, the underlying reason for the error is returned immediately.



If the specific value bound to a host parameter in the
WHERE clause might influence the choice of query plan for a statement,
then the statement will be automatically recompiled, as if there had been
a schema change, on the first sqlite3_step() call following any change
to the bindings of that parameter.
The specific value of a WHERE-clause parameter might influence the
choice of query plan if the parameter is the left-hand side of a LIKE
or GLOB operator or if the parameter is compared to an indexed column
and the SQLITE_ENABLE_STAT4 compile-time option is enabled.



sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
the extra prepFlags parameter, which is a bit array consisting of zero or
more of the SQLITE_PREPARE_* flags.  The
sqlite3_prepare_v2() interface works exactly the same as
sqlite3_prepare_v3() with a zero prepFlags parameter.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: Write-Ahead Logging
c5: wal.html
c4:
1. Overview

The default method by which SQLite implements
atomic commit and rollback is a rollback journal.
Beginning with version 3.7.0 (2010-07-21), a new "Write-Ahead Log" option
(hereafter referred to as "WAL") is available.

There are advantages and disadvantages to using WAL instead of
a rollback journal.  Advantages include:




WAL is significantly faster in most scenarios.
WAL provides more concurrency as readers do not block writers and 
    a writer does not block readers.  Reading and writing can proceed 
    concurrently.
Disk I/O operations tends to be more sequential using WAL.
WAL uses many fewer fsync() operations and is thus less vulnerable to
    problems on systems where the fsync() system call is broken.


But there are also disadvantages:


All processes using a database must be on the same host computer;
    WAL does not work over a network filesystem.  This is because WAL requires
    all processes to share a small amount of memory and processes on
    separate host machines obviously cannot share memory with each other.
Transactions that involve changes against multiple ATTACHed
    databases are atomic for each individual database, but are not
    atomic across all databases as a set.
It is not possible to change the page_size after entering WAL
    mode, either on an empty database or by using VACUUM or by restoring
    from a backup using the backup API.  You must be in a rollback journal
    mode to change the page size.
It is not possible to open read-only WAL databases.
    The opening process must have write privileges for "-shm"
    wal-index shared memory file associated with the database, if that
    file exists, or else write access on the directory containing
    the database file if the "-shm" file does not exist.
    Beginning with version 3.22.0 (2018-01-22), a read-only 
    WAL-mode database file can be opened if
    the -shm and -wal files
    already exists or those files can be created or the
    database is immutable.
WAL might be very slightly slower (perhaps 1% or 2% slower)
    than the traditional rollback-journal approach
    in applications that do mostly reads and seldom write.
There is an additional quasi-persistent "-wal" file and
    "-shm" shared memory file associated with each
    database, which can make SQLite less appealing for use as an 
    application file-format.
There is the extra operation of checkpointing which, though automatic
    by default, is still something that application developers need to
    be mindful of.
WAL works best with smaller transactions.  WAL does
    not work well for very large transactions.  For transactions larger than
    about 100 megabytes, traditional rollback journal modes will likely
    be faster.  For transactions in excess of a gigabyte, WAL mode may 
    fail with an I/O or disk-full error.
    It is recommended that one of the rollback journal modes be used for
    transactions larger than a few dozen megabytes.
    Beginning with version 3.11.0 (2016-02-15), 
    WAL mode works as efficiently with
    large transactions as does rollback mode.
    


2. How WAL Works

The traditional rollback journal works by writing a copy of the
original unchanged database content into a separate rollback journal file
and then writing changes directly into the database file.  In the
event of a crash or ROLLBACK, the original content contained in the
rollback journal is played back into the database file to
revert the database file to its original state.  The COMMIT occurs
when the rollback journal is deleted.

The WAL approach inverts this.  The original content is preserved
in the database file and the changes are appended into a separate
WAL file.  A COMMIT occurs when a special record indicating a commit
is appended to the WAL.  Thus a COMMIT can happen without ever writing
to the original database, which allows readers to continue operating
from the original unaltered database while changes are simultaneously being
committed into the WAL.  Multiple transactions can be appended to the
end of a single WAL file.



2.1. Checkpointing

Of course, one wants to eventually transfer all the transactions that
are appended in the WAL file back into the original database.  Moving
the WAL file transactions back into the database is called a
"checkpoint".

Another way to think about the difference between rollback and 
write-ahead log is that in the rollback-journal
approach, there are two primitive operations, reading and writing,
whereas with a write-ahead log
there are now three primitive operations:  reading, writing, and
checkpointing.

By default, SQLite does a checkpoint automatically when the WAL file
reaches a threshold size of 1000 pages.  (The
SQLITE_DEFAULT_WAL_AUTOCHECKPOINT compile-time option can be used to
specify a different default.) Applications using WAL do
not have to do anything in order to for these checkpoints to occur.  
But if they want to, applications can adjust the automatic checkpoint
threshold.  Or they can turn off the automatic checkpoints and run 
checkpoints during idle moments or in a separate thread or process.



2.2. Concurrency

When a read operation begins on a WAL-mode database, it first
remembers the location of the last valid commit record in the WAL.
Call this point the "end mark".  Because the WAL can be growing and
adding new commit records while various readers connect to the database,
each reader can potentially have its own end mark.  But for any
particular reader, the end mark is unchanged for the duration of the
transaction, thus ensuring that a single read transaction only sees
the database content as it existed at a single point in time.

When a reader needs a page of content, it first checks the WAL to
see if that page appears there, and if so it pulls in the last copy
of the page that occurs in the WAL prior to the reader's end mark.
If no copy of the page exists in the WAL prior to the reader's end mark,
then the page is read from the original database file.  Readers can
exist in separate processes, so to avoid forcing every reader to scan
the entire WAL looking for pages (the WAL file can grow to
multiple megabytes, depending on how often checkpoints are run), a
data structure called the "wal-index" is maintained in shared memory
which helps readers locate pages in the WAL quickly and with a minimum
of I/O.  The wal-index greatly improves the performance of readers,
but the use of shared memory means that all readers must exist on the
same machine.  This is why the write-ahead log implementation will not
work on a network filesystem.

Writers merely append new content to the end of the WAL file.
Because writers do nothing that would interfere with the actions of
readers, writers and readers can run at the same time.  However,
since there is only one WAL file, there can only be one writer at
a time.

A checkpoint operation takes content from the WAL file
and transfers it back into the original database file.
A checkpoint can run concurrently with readers, however the checkpoint
must stop when it reaches a page in the WAL that is past the end mark
of any current reader.  The checkpoint has to stop at that point because
otherwise it might overwrite part of the database file that the reader
is actively using.  The checkpoint remembers (in the wal-index) how far
it got and will resume transferring content from the WAL to the database
from where it left off on the next invocation.

Thus a long-running read transaction can prevent a checkpointer from
making progress.  But presumably every read transaction will eventually
end and the checkpointer will be able to continue.

Whenever a write operation occurs, the writer checks how much progress
the checkpointer has made, and if the entire WAL has been transferred into
the database and synced and if no readers are making use of the WAL, then
the writer will rewind the WAL back to the beginning and start putting new
transactions at the beginning of the WAL.  This mechanism prevents a WAL
file from growing without bound.



2.3. Performance Considerations

Write transactions are very fast since they only involve writing
the content once (versus twice for rollback-journal transactions)
and because the writes are all sequential.  Further, syncing the
content to the disk is not required, as long as the application is
willing to sacrifice durability following a power loss or hard reboot.
(Writers sync the WAL on every transaction commit if
PRAGMA synchronous is set to FULL but omit this sync if
PRAGMA synchronous is set to NORMAL.)

On the other hand, read performance deteriorates as the WAL file
grows in size since each reader must check the WAL file for the content
and the time needed to check the WAL file is proportional
to the size of the WAL file.  The wal-index helps find content
in the WAL file much faster, but performance still falls off with
increasing WAL file size.  Hence, to maintain good read performance 
it is important to keep the WAL file size down by
running checkpoints at regular intervals.

Checkpointing does require sync operations in order to avoid
the possibility of database corruption following a power loss
or hard reboot.  The WAL must be synced to persistent storage
prior to moving content from the WAL into the database and the
database file must by synced prior to resetting the WAL.
Checkpoint also requires more seeking.
The checkpointer makes an effort to
do as many sequential page writes to the database as it can (the pages
are transferred from WAL to database in ascending order) but even
then there will typically be many seek operations interspersed among
the page writes.  These factors combine to make checkpoints slower than
write transactions.

The default strategy is to allow successive write transactions to
grow the WAL until the WAL becomes about 1000 pages in size, then to
run a checkpoint operation for each subsequent COMMIT until the WAL
is reset to be smaller than 1000 pages.  By default, the checkpoint will be
run automatically by the same thread that does the COMMIT that pushes
the WAL over its size limit.  This has the effect of causing most
COMMIT operations to be very fast but an occasional COMMIT (those that trigger
a checkpoint) to be much slower.  If that effect is undesirable, then
the application can disable automatic checkpointing and run the
periodic checkpoints in a separate thread, or separate process.
(Links to commands and interfaces to accomplish this are
shown below.)


Note that with PRAGMA synchronous set to NORMAL, the checkpoint
is the only operation to issue an I/O barrier or sync operation
(fsync() on unix or FlushFileBuffers() on windows).  If an application
therefore runs checkpoint in a separate thread or process, the main
thread or process that is doing database queries and updates will never
block on a sync operation.  This helps to prevent "latch-up" in applications
running on a busy disk drive.  The downside to
this configuration is that transactions are no longer durable and
might rollback following a power failure or hard reset.


Notice too that there is a tradeoff between average read performance
and average write performance.  To maximize the read performance,
one wants to keep the WAL as small as possible and hence run checkpoints
frequently, perhaps as often as every COMMIT.  To maximize
write performance, one wants to amortize the cost of each checkpoint
over as many writes as possible, meaning that one wants to run checkpoints
infrequently and let the WAL grow as large as possible before each 
checkpoint.  The decision of how often to run checkpoints may therefore
vary from one application to another depending on the relative read
and write performance requirements of the application.
The default strategy is to run a checkpoint once the WAL
reaches 1000 pages and this strategy seems to work well in test applications on 
workstations, but other strategies might work better on different 
platforms or for different workloads.

3. Activating And Configuring WAL Mode

An SQLite database connection defaults to 
journal_mode=DELETE.  To convert to WAL mode, use the
following pragma:


PRAGMA journal_mode=WAL;


The journal_mode pragma returns a string which is the new journal mode.
On success, the pragma will return the string "wal".  If 
the conversion to WAL could not be completed (for example, if the VFS
does not support the necessary shared-memory primitives) then the
journaling mode will be unchanged and the string returned from the
primitive will be the prior journaling mode (for example "delete").


3.1. Automatic Checkpoint

By default, SQLite will automatically checkpoint whenever a COMMIT
occurs that causes the WAL file to be 1000 pages or more in size, or when the 
last database connection on a database file closes.  The default 
configuration is intended to work well for most applications.
But programs that want more control can force a checkpoint
using the wal_checkpoint pragma or by calling the
sqlite3_wal_checkpoint() C interface.  The automatic checkpoint
threshold can be changed or automatic checkpointing can be completely
disabled using the wal_autocheckpoint pragma or by calling the
sqlite3_wal_autocheckpoint() C interface.  A program can also 
use sqlite3_wal_hook() to register a callback to be invoked whenever
any transaction commits to the WAL.  This callback can then invoke
sqlite3_wal_checkpoint() or sqlite3_wal_checkpoint_v2() based on whatever
criteria it thinks is appropriate.  (The automatic checkpoint mechanism
is implemented as a simple wrapper around sqlite3_wal_hook().)

3.2. Application-Initiated Checkpoints

An application can initiate a checkpoint using any writable database
connection on the database simply by invoking
sqlite3_wal_checkpoint() or sqlite3_wal_checkpoint_v2().
There are three subtypes of checkpoints that vary in their aggressiveness:
PASSIVE, FULL, and RESTART.  The default checkpoint style is PASSIVE, which
does as much work as it can without interfering with other database
connections, and which might not run to completion if there are
concurrent readers or writers.
All checkpoints initiated by sqlite3_wal_checkpoint() and
by the automatic checkpoint mechanism are PASSIVE.  FULL and RESTART
checkpoints try harder to run the checkpoint to completion and can only
be initiated by a call to sqlite3_wal_checkpoint_v2().  See the
sqlite3_wal_checkpoint_v2() documentation for additional information
on FULL and RESET checkpoints.

3.3. Persistence of WAL mode

Unlike the other journaling modes, 
PRAGMA journal_mode=WAL is
persistent.  If a process sets WAL mode, then closes and reopens the
database, the database will come back in WAL mode.  In contrast, if
a process sets (for example) PRAGMA journal_mode=TRUNCATE and then closes and
reopens the database will come back up in the default rollback mode of
DELETE rather than the previous TRUNCATE setting.

The persistence of WAL mode means that applications can be converted
to using SQLite in WAL mode without making any changes to the application
itself.  One has merely to run "PRAGMA journal_mode=WAL;" on the
database file(s) using the command-line shell or other utility, then
restart the application.

The WAL journal mode will be set on all
connections to the same database file if it is set on any one connection.




4. The WAL File

While a database connection is open on a WAL-mode database, SQLite
maintains an extra journal file called a "Write Ahead Log" or "WAL File".
The name of this file on disk is usually the name of the database file
with an extra "-wal" suffix, though different naming rules may
apply if SQLite is compiled with SQLITE_ENABLE_8_3_NAMES.

The WAL file exists for as long as any database connection has the
database open.  Usually, the WAL file is deleted automatically when the
last connection to the database closes.  However, if the last process to
have the database open exits without cleanly
shutting down the database connection, or if the 
SQLITE_FCNTL_PERSIST_WAL file control is used, then the WAL file
might be retained on disk after all connections to the database have
been closed.  The WAL file is part of the persistent state of the
database and should be kept with the database if the database is copied
or moved.  If a database file is separated from its WAL file, then
transactions that were previously committed to the database might be lost,
or the database file might become corrupted.
The only safe way to remove a WAL file is
to open the database file using one of the sqlite3_open() interfaces
then immediately close the database using sqlite3_close().

The WAL file format is precisely defined and is cross-platform.



5. Read-Only Databases

Older versions of SQLite could not read a WAL-mode database that was
read-only.  In other words, write access was required in order to read a
WAL-mode database.  This constraint was relaxed beginning with
SQLite version 3.22.0 (2018-01-22).

On newer versions of SQLite,
a WAL-mode database on read-only media, or a WAL-mode database that lacks
write permission, can still be read as long as one or more of the following
conditions are met:

The -shm and -wal files already exists and are readable
There is write permission on the directory containing the database so
    that the -shm and -wal files can be created.
The database connection is opened using the
    immutable query parameter.


Even though it is possible to open a read-only WAL-mode database,
it is good practice to converted to 
PRAGMA journal_mode=DELETE prior to burning an
SQLite database image onto read-only media.



6. Avoiding Excessively Large WAL Files

In normal cases, new content is appended to the WAL file until the
WAL file accumulates about 1000 pages (and is thus about 4MB 
in size) at which point a checkpoint is automatically run and the WAL file
is recycled.  The checkpoint does not normally truncate the WAL file
(unless the journal_size_limit pragma is set).  Instead, it merely
causes SQLite to start overwriting the WAL file from the beginning.
This is done because it is normally faster to overwrite an existing file
than to append.  When the last connection to a database closes, that
connection does one last checkpoint and then deletes the WAL and its
associated shared-memory file, to clean up the disk.

So in the vast majority of cases, applications need not worry about
the WAL file at all.  SQLite will automatically take care of it.  But
it is possible to get SQLite into a state where the WAL file will grow
without bound, causing excess disk space usage and slow queries speeds.
The following bullets enumerate some of the ways that this can happen
and how to avoid them.



Disabling the automatic checkpoint mechanism.
In its default configuration, SQLite will checkpoint the WAL file at the
conclusion of any transaction when the WAL file is more than 1000 pages
long.  However, compile-time and run-time options exist that can disable
or defer this automatic checkpoint.  If an application disables the
automatic checkpoint, then there is nothing to prevent the WAL file
from growing excessively.


Checkpoint starvation.
A checkpoint is only able to run to completion, and reset the WAL file,
if there are no other database connections using the WAL file.  If another
connection has a read transaction open,
then the checkpoint cannot reset the WAL file because
doing so might delete content out from under the reader.
The checkpoint will do as much work as it can without upsetting the
reader, but it cannot run to completion.
The checkpoint will start up again where it left off after the next
write transaction.  This repeats until some checkpoint is able to complete.

However, if a database has many concurrent overlapping readers
and there is always at least one active reader, then
no checkpoints will be able to complete
and hence the WAL file will grow without bound.

This scenario can be avoided by ensuring that there are "reader gaps":
times when no processes are reading from the 
database and that checkpoints are attempted during those times.
In applications with many concurrent readers, one might also consider 
running manual checkpoints with the SQLITE_CHECKPOINT_RESTART or
SQLITE_CHECKPOINT_TRUNCATE option which will ensure that the checkpoint
runs to completion before returning.  The disadvantage of using
SQLITE_CHECKPOINT_RESTART and SQLITE_CHECKPOINT_TRUNCATE is that
readers might block while the checkpoint is running.


Very large write transactions.
A checkpoint can only complete when no other transactions are running, 
which means the WAL file cannot be reset in the middle of a write
transaction.  So a large change to a large database
might result in a large WAL file.  The WAL file will be checkpointed
once the write transaction completes (assuming there are no other readers
blocking it) but in the meantime, the file can grow very big.

As of SQLite version 3.11.0 (2016-02-15), 
the WAL file for a single transaction
should be proportional in size to the transaction itself.  Pages that
are changed by the transaction should only be written into the WAL file
once.  However, with older versions of SQLite, the same page might be
written into the WAL file multiple times if the transaction grows larger
than the page cache.


7. Implementation Of Shared-Memory For The WAL-Index

The wal-index is implemented using an ordinary file that is
mmapped for robustness.  Early (pre-release) implementations of WAL mode
stored the wal-index in volatile shared-memory, such as files created in
/dev/shm on Linux or /tmp on other unix systems.  The problem
with that approach is that processes with a different root directory
(changed via chroot)
will see different files and hence use different shared memory areas,
leading to database corruption.  Other methods for creating nameless
shared memory blocks are not portable across the various flavors of
unix.  And we could not find any method to create nameless shared
memory blocks on windows.  The only way we have found to guarantee
that all processes accessing the same database file use the same shared
memory is to create the shared memory by mmapping a file in the same
directory as the database itself.

Using an ordinary disk file to provide shared memory has the 
disadvantage that it might actually do unnecessary disk I/O by
writing the shared memory to disk.  However, the developers do not
think this is a major concern since the wal-index rarely exceeds
32 KiB in size and is never synced.  Furthermore, the wal-index 
backing file is deleted when the last database connection disconnects,
which often prevents any real disk I/O from ever happening.

Specialized applications for which the default implementation of
shared memory is unacceptable can devise alternative methods via a
custom VFS.  
For example, if it is known that a particular database
will only be accessed by threads within a single process, the wal-index
can be implemented using heap memory instead of true shared memory.



8. Use of WAL Without Shared-Memory

Beginning in SQLite version 3.7.4 (2010-12-07), 
WAL databases can be created, read, and
written even if shared memory is unavailable as long as the
locking_mode is set to EXCLUSIVE before the first attempted access.
In other words, a process can interact with
a WAL database without using shared memory if that
process is guaranteed to be the only process accessing the database.
This feature allows WAL databases to be created, read, and written
by legacy VFSes that lack the "version 2" shared-memory
methods xShmMap, xShmLock, xShmBarrier, and xShmUnmap on the
sqlite3_io_methods object.

If EXCLUSIVE locking mode
is set prior to the first WAL-mode 
database access, then SQLite never attempts to call any of the
shared-memory methods and hence no shared-memory
wal-index is ever created.
In that case, the database connection remains in EXCLUSIVE mode
as long as the journal mode is WAL; attempts to change the locking
mode using "PRAGMA locking_mode=NORMAL;" are no-ops.
The only way to change out of EXCLUSIVE locking mode is to first
change out of WAL journal mode.

If NORMAL locking mode is in effect for the first WAL-mode database
access, then the shared-memory wal-index is created.  This means that the
underlying VFS must support the "version 2" shared-memory.
If the VFS does not support shared-memory methods, then the attempt to
open a database that is already in WAL mode, or the attempt convert a
database into WAL mode, will fail.
As long as exactly one connection is using a shared-memory wal-index, 
the locking mode can be changed freely between NORMAL and EXCLUSIVE.  
It is only when the shared-memory wal-index is omitted, when the locking 
mode is EXCLUSIVE prior to the first WAL-mode database access, that the 
locking mode is stuck in EXCLUSIVE.



9. Sometimes Queries Return SQLITE_BUSY In WAL Mode

The second advantage of WAL-mode is that
writers do not block readers and readers to do not block writers.
This is mostly true.
But there are some obscure cases where a query against a WAL-mode
database can return SQLITE_BUSY, so applications should be prepared
for that happenstance.

Cases where a query against a WAL-mode database can return SQLITE_BUSY
include the following:


If another database connection has the database mode open
in exclusive locking mode then all queries against the
database will return SQLITE_BUSY.  Both Chrome and Firefox open their
database files in exclusive locking mode, so attempts to read Chrome or
Firefox databases while the applications are running will run into this
problem, for example.

 When the last connection to a particular database is closing,
that connection will acquire an exclusive lock for a short time while
it cleans up the WAL and shared-memory files.  If a separate attempt
is made to open and query the database while the first connection is
still in the middle of its cleanup process, the second connection
might get an SQLITE_BUSY error.


If the last connection to a database crashed, then the first new
connection to open the database will start a recovery process.  An
exclusive lock is held during recovery.  So if a third database connection
tries to jump in and query while the second connection is running recovery,
the third connection will get an SQLITE_BUSY error.




10. Backwards Compatibility

The database file format is unchanged for WAL mode.  However, the
WAL file and the wal-index are new concepts and so older versions of 
SQLite will not know
how to recover a crashed SQLite database that was operating in WAL mode
when the crash occurred.
To prevent older versions of SQLite (prior to version 3.7.0, 2010-07-22)
from trying to recover
a WAL-mode database (and making matters worse) the database file format
version numbers (bytes 18 and 19 in the database header)
are increased from 1 to 2 in WAL mode.
Thus, if an older version of SQLite attempts to connect to an SQLite
database that is operating in WAL mode, it will report an error along
the lines of "file is encrypted or is not a database".

One can explicitly change out of WAL mode using a pragma such as
this:


PRAGMA journal_mode=DELETE;



Deliberately changing out of WAL mode changes the database file format
version numbers back to 1 so that older versions of SQLite can once again 
access the database file.
This page last modified on  2024-07-14 23:07:20 UTC


c2: The Spellfix1 Virtual Table
c5: spellfix1.html
c4:
1. Overview

This spellfix1 virtual table can be used to search
a large vocabulary for close matches.  For example, spellfix1
can be used to suggest corrections to misspelled words.  Or,
it could be used with FTS4 to do full-text search using potentially
misspelled words.

The implementation for the spellfix1 virtual table is held in the
SQLite source tree in the miscellaneous extensions folder and in
particular in the file 
ext/misc/spellfix1.c.
The spellfix1 virtual table is not included in the SQLite amalgamation
and is not a part of any standard SQLite build.  It is a loadable extension.

Once the spellfix1 extension is loaded, an instance of the spellfix1 
virtual table is created like this:


CREATE VIRTUAL TABLE demo USING spellfix1;


The "spellfix1" term is the name of the spellfix module and must be 
entered as shown.  The "demo" term is the
name of the virtual table you will be creating and can be altered
to suit the needs of your application.  The virtual table is initially
empty.  In order for the virtual table to be useful, you will need to
populate it with your vocabulary.  Suppose you
have a list of words in a table named "big_vocabulary".  Then do this:


INSERT INTO demo(word) SELECT word FROM big_vocabulary;


If you intend to use this virtual table in cooperation with an FTS4
table (for spelling correction of search terms) then you might extract
the vocabulary using an fts4aux table:


INSERT INTO demo(word) SELECT term FROM search_aux WHERE col='*';


You can also provide the virtual table with a "rank" for each word.
The "rank" is an estimate of how common the word is.  Larger numbers
mean the word is more common.  If you omit the rank when populating
the table, then a rank of 1 is assumed.  But if you have rank 
information, you can supply it and the virtual table will show a
slight preference for selecting more commonly used terms.  To
populate the rank from an fts4aux table "search_aux" do something
like this:


INSERT INTO demo(word,rank)
   SELECT term, documents FROM search_aux WHERE col='*';


To query the virtual table, include a MATCH operator in the WHERE
clause.  For example:


SELECT word FROM demo WHERE word MATCH 'kennasaw';


Using a dataset of American place names (derived from
http://geonames.usgs.gov/domestic/download_data.htm) the query above
returns 20 results beginning with:


kennesaw
kenosha
kenesaw
kenaga
keanak


If you append the character '*' to the end of the pattern, then
a prefix search is performed.  For example:


SELECT word FROM demo WHERE word MATCH 'kennes*';


Yields 20 results beginning with:


kennesaw
kennestone
kenneson
kenneys
keanes
keenes


2. Search Refinements

By default, the spellfix1 table returns no more than 20 results.
(It might return less than 20 if there were fewer good matches.)
You can change the upper bound on the number of returned rows by
adding a "top=N" term to the WHERE clause of your query, where N
is the new maximum.  For example, to see the 5 best matches:


SELECT word FROM demo WHERE word MATCH 'kennes*' AND top=5;


Each entry in the spellfix1 virtual table is associated with
a particular language, identified by the integer "langid" column.
The default langid is 0 and if no other actions are taken, the
entire vocabulary is a part of the 0 language.  But if your application
needs to operate in multiple languages, then you can specify different
vocabulary items for each language by specifying the langid field
when populating the table.  For example:


INSERT INTO demo(word,langid) SELECT word, 0 FROM en_vocabulary;
INSERT INTO demo(word,langid) SELECT word, 1 FROM de_vocabulary;
INSERT INTO demo(word,langid) SELECT word, 2 FROM fr_vocabulary;
INSERT INTO demo(word,langid) SELECT word, 3 FROM ru_vocabulary;
INSERT INTO demo(word,langid) SELECT word, 4 FROM cn_vocabulary;


After the virtual table has been populated with items from multiple
languages, specify the language of interest using a "langid=N" term
in the WHERE clause of the query:


SELECT word FROM demo WHERE word MATCH 'hildes*' AND langid=1;


Note that if you do not include the "langid=N" term in the WHERE clause,
the search will be against language 0 (English in the example above.)
All spellfix1 searches are against a single language id.  There is no
way to search all languages at once.
 

3. Virtual Table Details

Each row in the spellfix1 virtual table has a unique rowid 
with seven columns plus five extra hidden columns.
The columns are as follows:


rowid
A unique integer number associated with each
vocabulary item in the table.  This can be used
as a foreign key on other tables in the database.

word
The text of the word that matches the pattern.
Both word and pattern can contain unicode characters
and can be mixed case.

rank
This is the rank of the word, as specified in the
original INSERT statement.


distance
This is an edit distance or Levenshtein distance going
from the pattern to the word.

langid
This is the language-id of the word.  All queries are
against a single language-id, which defaults to 0.
For any given query this value is the same on all rows.

score
The score is a combination of rank and distance.  The
idea is that a lower score is better.  The virtual table
attempts to find words with the lowest score and 
by default (unless overridden by ORDER BY) returns
results in order of increasing score.

matchlen
In a prefix search, the matchlen is the number of characters in
the string that match against the prefix.  For a non-prefix search,
this is the same as length(word).

phonehash
This column shows the phonetic hash prefix that was used to restrict
the search.  For any given query, this column should be the same for
every row.  This information is available for diagnostic purposes and
is not normally considered useful in real applications.

top
(HIDDEN)  For any query, this value is the same on all
rows.  It is an integer which is the maximum number of
rows that will be output.  The actually number of rows
output might be less than this number, but it will never
be greater.  The default value for top is 20, but that
can be changed for each query by including a term of
the form "top=N" in the WHERE clause of the query.

scope
(HIDDEN)  For any query, this value is the same on all
rows.  The scope is a measure of how widely the virtual
table looks for matching words.  Smaller values of
scope cause a broader search.  The scope is normally
chosen automatically and is capped at 4.  Applications
can change the scope by including a term of the form
"scope=N" in the WHERE clause of the query.  Increasing
the scope will make the query run faster, but will reduce
the possible corrections.

srchcnt
(HIDDEN)  For any query, this value is the same on all
rows.  This value is an integer which is the number of
words examined using the edit-distance algorithm to
find the top matches that are ultimately displayed.  This
value is for diagnostic use only.

soundslike
(HIDDEN)  When inserting vocabulary entries, this field
can be set to a spelling that matches what the word
sounds like.  See the DEALING WITH UNUSUAL AND DIFFICULT
SPELLINGS section below for details.

command
(HIDDEN)  The value of the "command" column is always NULL.  However,
applications can insert special strings into the "command" column in order
to provoke certain behaviors in the spellfix1 virtual table.
For example, inserting the string 'reset' into the "command" column
will cause the virtual table to reread its edit distance weights
(if there are any).


4. Algorithm

The spellfix1 virtual table creates a single
shadow table named "%_vocab" (where the % is replaced by the name of
the virtual table; Ex: "demo_vocab" for the "demo" virtual table).  
the shadow table contains the following columns:


id
The unique id (INTEGER PRIMARY KEY)

rank
The rank of word.

langid
The language id for this entry.

word
The original UTF8 text of the vocabulary word

k1
The word transliterated into lower-case ASCII.  
There is a standard table of mappings from non-ASCII
characters into ASCII.  Examples: "æ" -> "ae",
"þ" -> "th", "ß" -> "ss", "á" -> "a", ...  The
accessory function spellfix1_translit(X) will do
the non-ASCII to ASCII mapping.  The built-in lower(X)
function will convert to lower-case.  Thus:
k1 = lower(spellfix1_translit(word)).

If the word is already all lower-case ASCII, then the k1 column
will contain a NULL.  This reduces the storage requirements for
the %_vocab table and helps spellfix to run a little faster.
Therefore, it is advantageous to populate as much of the spellfix
table as possible using lower-case ASCII vocabulary.

k2
This field holds a phonetic code derived from coalesce(k1,word).
Letters that have similar sounds are mapped into the same symbol.
For example, all vowels and vowel clusters become the
single symbol "A".  And the letters "p", "b", "f", and
"v" all become "B".  All nasal sounds are represented
as "N".  And so forth.  The mapping is based on
ideas found in Soundex, Metaphone, and other
long-standing phonetic matching systems.  This key can
be generated by the function spellfix1_phonehash(X).  
Hence: k2 = spellfix1_phonehash(coalesce(k1,word))


There is also a function for computing the Wagner edit distance or the
Levenshtein distance between a pattern and a word.  This function
is exposed as spellfix1_editdist(X,Y).  The edit distance function
returns the "cost" of converting X into Y.  Some transformations
cost more than others.  Changing one vowel into a different vowel,
for example is relatively cheap, as is doubling a constant, or
omitting the second character of a double-constant.  Other transformations
or more expensive.  The idea is that the edit distance function returns
a low cost for words that are similar and a higher cost for words
that are further apart.  In this implementation, the maximum cost
of any single-character edit (delete, insert, or substitute) is 100,
with lower costs for some edits (such as transforming vowels).

The "score" for a comparison is the edit distance between the pattern
and the word, adjusted down by the base-2 logarithm of the word rank.
For example, a match with distance 100 but rank 1000 would have a
score of 122 (= 100 - log2(1000) + 32) whereas a match with distance
100 with a rank of 1 would have a score of 131 (100 - log2(1) + 32).
(NB:  The constant 32 is added to each score to keep it from going
negative in case the edit distance is zero.)  In this way, frequently
used words get a slightly lower cost which tends to move them toward
the top of the list of alternative spellings.

A straightforward implementation of a spelling corrector would be
to compare the search term against every word in the vocabulary
and select the 20 with the lowest scores.  However, there will 
typically be hundreds of thousands or millions of words in the
vocabulary, and so this approach is not fast enough.

Suppose the term that is being spell-corrected is X.  To limit
the search space, X is converted to a k2-like key using the
equivalent of:


   key = spellfix1_phonehash(lower(spellfix1_translit(X)))


This key is then limited to "scope" characters.  The default scope
value is 4, but an alternative scope can be specified using the
"scope=N" term in the WHERE clause.  After the key has been truncated,
the edit distance is run against every term in the vocabulary that
has a k2 value that begins with the abbreviated key.

For example, suppose the input word is "Paskagula".  The phonetic 
key is "BACACALA" which is then truncated to 4 characters "BACA".
The edit distance is then run on the 4980 entries (out of
272,597 entries total) of the vocabulary whose k2 values begin with
BACA, yielding "Pascagoula" as the best match.

Only terms of the vocabulary with a matching langid are searched.
Hence, the same table can contain entries from multiple languages
and only the requested language will be used.  The default langid
is 0.



5. Configurable Edit Distance

The built-in Wagner edit-distance function with fixed weights can be
replaced by the editdist3() edit-distance function
with application-defined weights and support for unicode, by specifying
the "edit_cost_table=TABLENAME" parameter to the spellfix1 module
when the virtual table is created.
For example:


CREATE VIRTUAL TABLE demo2 USING spellfix1(edit_cost_table=APPCOST);


The editdist3() edit-distance function can also be selected or 
deselected at run-time by inserting an appropriate string into the
"command" column of the virtual table:


INSERT INTO demo2(command) VALUES('edit_cost_table=APPCOST');



In the examples above, the APPCOST table would be interrogated to find
the edit distance coefficients.  It is the presence of the "edit_cost_table="
parameter to the spellfix1 module name that causes editdist3() to be used
in place of the built-in edit distance function.  If APPCOST is an empty
string, then the built-in Wagner edit-distance function is used.

The edit distance coefficients are normally read from the APPCOST table
once and there after stored in memory.  Hence, run-time changes to the
APPCOST table will not normally affect the edit distance results.
However, inserting the special string 'reset' into the "command" column of the
virtual table causes the edit distance coefficients to be reread the
APPCOST table.  Hence, applications should run a SQL statement similar
to the following when changes to the APPCOST table occur:


INSERT INTO demo2(command) VALUES("reset");


6. Dealing With Unusual And Difficult Spellings

The algorithm above works quite well for most cases, but there are
exceptions.  These exceptions can be dealt with by making additional
entries in the virtual table using the "soundslike" column.

For example, many words of Greek origin begin with letters "ps" where
the "p" is silent.  Ex:  psalm, pseudonym, psoriasis, psyche.  In
another example, many Scottish surnames can be spelled with an
initial "Mac" or "Mc".  Thus, "MacKay" and "McKay" are both pronounced
the same.

Accommodation can be made for words that are not spelled as they
sound by making additional entries into the virtual table for the
same word, but adding an alternative spelling in the "soundslike"
column.  For example, the canonical entry for "psalm" would be this:


  INSERT INTO demo(word) VALUES('psalm');


To enhance the ability to correct the spelling of "salm" into
"psalm", make an addition entry like this:


  INSERT INTO demo(word,soundslike) VALUES('psalm','salm');


It is ok to make multiple entries for the same word as long as
each entry has a different soundslike value.  Note that if no
soundslike value is specified, the soundslike defaults to the word
itself.

Listed below are some cases where it might make sense to add additional
soundslike entries.  The specific entries will depend on the application
and the target language.


Silent "p" in words beginning with "ps":  psalm, psyche
Silent "p" in words beginning with "pn":  pneumonia, pneumatic
Silent "p" in words beginning with "pt":  pterodactyl, ptolemaic
Silent "d" in words beginning with "dj":  djinn, Djikarta
Silent "k" in words beginning with "kn":  knight, Knuthson
Silent "g" in words beginning with "gn":  gnarly, gnome, gnat
"Mac" versus "Mc" beginning Scottish surnames
"Tch" sounds in Slavic words:  Tchaikovsky vs. Chaykovsky
The letter "j" pronounced like "h" in Spanish:  LaJolla
Words beginning with "wr" versus "r":  write vs. rite
Miscellaneous problem words such as "debt", "tsetse",
      "Nguyen", "Van Nuyes".


7. Auxiliary Functions

The source code module that implements the spellfix1 virtual table also
implements several SQL functions that might be useful to applications
that employ spellfix1 or for testing or diagnostic work while developing
applications that use spellfix1.  The following auxiliary functions are
available:


editdist3(P,W)editdist3(P,W,L)editdist3(T)
These routines provide direct access to the version of the Wagner
edit-distance function that allows for application-defined weights
on edit operations.  The first two forms of this function compare
pattern P against word W and return the edit distance.  In the first
function, the langid is assumed to be 0 and in the second, the
langid is given by the L parameter.  The third form of this function
reloads edit distance coefficients from the table named by T.

spellfix1_editdist(P,W)
This routine provides access to the built-in Wagner edit-distance
function that uses default, fixed costs.  The value returned is
the edit distance needed to transform W into P.

spellfix1_phonehash(X)
This routine constructs a phonetic hash of the pure ascii input word X
and returns that hash.  This routine is used internally by spellfix1 in
order to transform the K1 column of the shadow table into the K2
column.

spellfix1_scriptcode(X)
Given an input string X, this routine attempts to determine the dominant
script of that input and returns the ISO-15924 numeric code for that
script.  The current implementation understands the following scripts:

 215 - Latin
 220 - Cyrillic
 200 - Greek

Additional language codes might be added in future releases.

spellfix1_translit(X)
This routine transliterates unicode text into pure ascii, returning
the pure ascii representation of the input text X.  This is the function
that is used internally to transform vocabulary words into the K1
column of the shadow table.





8. The editdist3 function

The editdist3 algorithm is a function that computes the minimum edit 
distance (a.k.a. the Levenshtein distance) between two input strings.
The editdist3 algorithm is a configurable alternative to the default
edit distance function of spellfix1.
Features of editdist3 include:


It works with unicode (UTF8) text.

A table of insertion, deletion, and substitution costs can be 
       provided by the application.

Multi-character insertions, deletions, and substitutions can be
       enumerated in the cost table.


9. The editdist3 COST table

To program the costs of editdist3, create a table such as the following:


CREATE TABLE editcost(
  iLang INT,   -- The language ID
  cFrom TEXT,  -- Convert text from this
  cTo   TEXT,  -- Convert text into this
  iCost INT    -- The cost of doing the conversion
);


The cost table can be named anything you want - it does not have to be
called "editcost".  And the table can contain additional columns.
The only requirement is that the
table must contain the four columns show above, with exactly the names shown.

The iLang column is a non-negative integer that identifies a set of costs
appropriate for a particular language.  The editdist3 function will only use
a single iLang value for any given edit-distance computation.  The default
value is 0.  It is recommended that applications that only need to use a
single language always use iLang==0 for all entries.

The iCost column is the numeric cost of transforming cFrom into cTo.  This
value should be a non-negative integer, and should probably be less than 100.
The default single-character insertion and deletion costs are 100 and the
default single-character to single-character substitution cost is 150.  A
cost of 10000 or more is considered "infinite" and causes the rule to be
ignored.

The cFrom and cTo columns show edit transformation strings.  Either or both
columns may contain more than one character.  Or either column (but not both)
may hold an empty string.  When cFrom is empty, that is the cost of inserting
cTo.  When cTo is empty, that is the cost of deleting cFrom.

In the spellfix1 algorithm, cFrom is the text as the user entered it and
cTo is the correctly spelled text as it exists in the database.  The goal
of the editdist3 algorithm is to determine how close the user-entered text is
to the dictionary text.

There are three special-case entries in the cost table:


cFromcToMeaning
'''?'The default insertion cost
'?'''The default deletion cost
'?''?'The default substitution cost


If any of the special-case entries shows above are omitted, then the
value of 100 is used for insertion and deletion and 150 is used for
substitution.  To disable the default insertion, deletion, and/or substitution
set their respective cost to 10000 or more.

Other entries in the cost table specific transforms for particular 
characters.
The cost of specific transforms should be less than the default costs, or else
the default costs will take precedence and the specific transforms will never 
be used.

Some example, cost table entries:


INSERT INTO editcost(iLang, cFrom, cTo, iCost)
VALUES(0, 'a', 'ä', 5);


The rule above says that the letter "a" in user input can be matched against
the letter "ä" in the dictionary with a penalty of 5.


INSERT INTO editcost(iLang, cFrom, cTo, iCost)
VALUES(0, 'ss', 'ß', 8);


The number of characters in cFrom and cTo do not need to be the same.  The
rule above says that "ss" on user input will match "ß" with a penalty of 8.

10. Experimenting with the editcost3() function

The spellfix1 virtual table
uses editdist3 if the "edit_cost_table=TABLE" option
is specified as an argument when the spellfix1 virtual table is created.  
But editdist3 can also be tested directly using the built-in "editdist3()"
SQL function.  The editdist3() SQL function has 3 forms:


 editdist3('TABLENAME');
 editdist3('string1', 'string2');
 editdist3('string1', 'string2', langid);


The first form loads the edit distance coefficients from a table called
'TABLENAME'.  Any prior coefficients are discarded.  So when experimenting
with weights and the weight table changes, simply rerun the single-argument
form of editdist3() to reload revised coefficients.  Note that the 
edit distance
weights used by the editdist3() SQL function are independent from the
weights used by the spellfix1 virtual table.

The second and third forms return the computed edit distance between strings
'string1' and "string2'.  In the second form, a language id of 0 is used.
The language id is specified in the third form.


c2: SQLite Is Serverless
c5: serverless.html
c4:
1. SQLite Is Serverless


Most SQL database engines are implemented as a separate server process.
Programs that want to access the database communicate with the server
using some kind of interprocess communication (typically TCP/IP) to send 
requests to the server and to receive back results. 
SQLite does not work this way. 
With SQLite, the process that wants to access the database reads and 
writes directly from the database files on disk. 
There is no intermediary server process.



There are advantages and disadvantages to being serverless.
The main advantage is that there is no separate server process
to install, setup, configure, initialize, manage, and troubleshoot. 
This is one reason why SQLite is a 
"zero-configuration" database engine. 
Programs that use SQLite require no administrative support for 
setting up the database engine before they are run.
Any program that is able to access the disk is able to use an SQLite database.



On the other hand, a database engine that uses a server can 
provide better protection from bugs in the client 
application - stray pointers in a client cannot corrupt memory 
on the server. 
And because a server is a single persistent process,
it is able to control database access with more precision, 
allowing for finer-grained locking and better concurrency.



Most SQL database engines are client/server based. 
Of those that are serverless, SQLite is the only one
known to this author that allows multiple applications
to access the same database at the same time. 


2. Classic Serverless Vs. Neo-Serverless


(This section was added on 2018-04-02)


Recently, folks have begun to use the
word "serverless" to mean something subtly different from its intended
meaning in this document.  Here are two possible definitions of "serverless":



Classic Serverless:
The database engine runs within the same process, thread, and address space
as the application.  There is no message passing or network activity.


Neo-Serverless:
The database engine runs in a separate namespace from the application,
probably on a separate machine, but the database is provided as a
turn-key service by the hosting provider, requires no management or
administration by the application owners, and is so easy to use
that the developers can think of the database as being serverless
even if it really does use a server under the covers.



SQLite is an example of a classic serverless database engine.
With SQLite, there are no other processes, threads, machines, or
other mechanisms (apart from host computer OS and filesystem)
to help provide database services or implementation.  There really
is no server.


Microsoft Azure Cosmos DB
and
Amazon S3
are examples of a neo-serverless databases.
These database are implemented by server processes running separately
in the cloud.
But the servers are maintained and administered by the ISP, not by
the application developer.
Application developers just use the service.  Developers do not have to
provision, configure, or manage database server instances, as all of that
work is handled automatically by the service provider.  Database servers
do in fact exist, they are just hidden from the developers.


It is important to understand these two different definitions for
"serverless".
When a database claims to be "serverless",
be sure to discern whether they mean "classic serverless"
or "neo-serverless".


c2: The DBSTAT Virtual Table
c5: dbstat.html
c4:
1. Overview


The DBSTAT virtual table is a read-only eponymous virtual table that returns
information about the amount of disk space used to store the content
of an SQLite database.
Example use cases for the
DBSTAT virtual table include the sqlite3_analyzer.exe
utility program and the
table size pie-chart in
the Fossil-implemented version control system
for SQLite.



The DBSTAT virtual table is available on all 
database connections when SQLite is built using the
SQLITE_ENABLE_DBSTAT_VTAB compile-time option.


The DBSTAT virtual table is an eponymous virtual table, meaning
that is not necessary to run CREATE VIRTUAL TABLE to create an
instance of the dbstat virtual table before using it.  The "dbstat"
module name can be used as if it were a table name to query the
dbstat virtual table directly.  For example:

SELECT * FROM dbstat;



If a named virtual table that uses the dbstat module is desired,
then the recommended way to create an instance of the dbstat
virtual table is as follows:

CREATE VIRTUAL TABLE temp.stat USING dbstat(main);



Note the "temp." qualifier before the virtual table name ("stat").  This
qualifier causes the virtual table to be temporary - to only exist for
the duration of the current database connection.  This is the
recommended approach.


The "main" argument to dbstat is default schema
for which information is to be provided.  The default is "main", and
so the use of "main" in the example above is redundant.  For any
particular query, the schema can be changed by specifying the
alternative schema as a function argument to the virtual table
name in the FROM clause of the query.  (See further discussion of
table-valued functions in the FROM clause for more details.)


The schema for the DBSTAT virtual table looks like this:
CREATE TABLE dbstat(
  name       TEXT,        -- Name of table or index
  path       TEXT,        -- Path to page from root
  pageno     INTEGER,     -- Page number, or page count
  pagetype   TEXT,        -- 'internal', 'leaf', 'overflow', or NULL
  ncell      INTEGER,     -- Cells on page (0 for overflow pages)
  payload    INTEGER,     -- Bytes of payload on this page or btree
  unused     INTEGER,     -- Bytes of unused space on this page or btree
  mx_payload INTEGER,     -- Largest payload size of all cells on this row
  pgoffset   INTEGER,     -- Byte offset of the page in the database file
  pgsize     INTEGER,     -- Size of the page, in bytes
  schema     TEXT HIDDEN, -- Database schema being analyzed
  aggregate  BOOL HIDDEN  -- True to enable aggregate mode
);



The DBSTAT table only reports on the content of btrees within the database file.
Freelist pages, pointer-map pages, and the lock page are omitted from
the analysis.


By default, there is a single row in the DBSTAT table for each
btree page the database file.  Each row provides
information about the space utilization of that one page of the
database.  However, if the hidden column "aggregate" is TRUE, then
results are aggregated and there is a single row in the DBSTAT table
for each btree in the database, providing information about space
utilization across the entire btree.


2. The "path" column of the dbstat virtual table


The "path" column describes the path taken from the 
root node of the btree structure to each page.  The
"path" of the root node itself is '/'.
The "path" is NULL when "aggregate" is TRUE.

The "path" for the left-most child page of the root of
a btree page is '/000/'. (Btrees store content ordered from left to right
so the pages to the left have smaller keys than the pages to the right.)
The next to left-most child of the root page is '/001', and so on,
each sibling page identified by a 3-digit hex  value.
The children of the 451st left-most sibling have paths such
as '/1c2/000/, '/1c2/001/' etc.

Overflow pages are specified by appending a '+' character and a 
six-digit hexadecimal value to the path to the cell they are linked
from. For example, the three overflow pages in a chain linked from 
the left-most cell of the 450th child of the root page are identified
by the paths:

'/1c2/000+000000'         // First page in overflow chain
'/1c2/000+000001'         // Second page in overflow chain
'/1c2/000+000002'         // Third page in overflow chain



If the paths are sorted using the BINARY collation sequence, then
the overflow pages associated with a cell will appear earlier in the
sort-order than its child page:

'/1c2/000/'               // Left-most child of 451st child of root




3. Aggregated Data


Beginning with SQLite version 3.31.0 (2020-01-22), the DBSTAT table
has a new hidden column named "aggregate", which if constrained to be
TRUE will cause DBSTAT to generate one row per btree in the database,
rather than one row per page.  When running in aggregated mode, the 
"path", "pagetype", and "pgoffset" columns are always NULL and the
"pageno" column holds the number of pages in the entire btree, rather
than the number of the page that corresponds to the row.


The following table shows the meanings of the (non-hidden) columns of
DBSTAT in both normal and aggregated mode:




Column
Normal meaning
Aggregate-mode meaning


name

The name of the table or index that is implemented by
the btree of the current row

path
See description above
Always NULL

pageno
The page number of the database page for the current row
The total number of pages in the btree for the current row

pagetype
'leaf' or 'interior'
Always NULL

ncell
Number of cells on the current page or btree

payload
Bytes of useful payload on the current page or btree

unused
Unused bytes of on the current page or btree

mx_payload
The largest payload found anywhere in the current page
or btree.

pgoffset
Byte offset to the start of the page
Always NULL

pgsize
Total storage space used by the current page or btree.



4. Example uses of the dbstat virtual table


To find the total number of pages used to store table "xyz" in schema "aux1",
use either of the following two queries (the first is the traditional way,
and the second shows the use of the aggregated feature):

SELECT count(*) FROM dbstat('aux1') WHERE name='xyz';
SELECT pageno FROM dbstat('aux1',1) WHERE name='xyz';



To see how efficiently the content of a table is stored on disk,
compute the amount of space used to hold actual content divided
by the total amount of disk space used.  The closer this number
is to 100%, the more efficient the packing.  (In this example, the
'xyz' table is assumed to be in the 'main' schema.  Again, there
are two different versions that show the use of DBSTAT both without
and with the new aggregated feature, respectively.)

SELECT sum(pgsize-unused)*100.0/sum(pgsize) FROM dbstat WHERE name='xyz';
SELECT (pgsize-unused)*100.0/pgsize FROM dbstat
 WHERE name='xyz' AND aggregate=TRUE;



To find the average fan-out for a table, run:

SELECT avg(ncell) FROM dbstat WHERE name='xyz' AND pagetype='internal';




Modern filesystems operate faster when disk accesses are sequential.
Hence, SQLite will run faster if the content of the database file
is on sequential pages.  To find out what fraction of the pages in
a database are sequential (and thus obtain a measurement that might
be useful in determining when to VACUUM), run a query like the following:

CREATE TEMP TABLE s(rowid INTEGER PRIMARY KEY, pageno INT);
INSERT INTO s(pageno) SELECT pageno FROM dbstat ORDER BY path;
SELECT sum(s1.pageno+1==s2.pageno)*1.0/count(*)
  FROM s AS s1, s AS s2
 WHERE s1.rowid+1=s2.rowid;
DROP TABLE s;

This page last modified on  2022-01-08 05:02:57 UTC


c2: Measuring and Reducing CPU Usage in SQLite
c5: cpu.html
c4:
1. Overview

The graph below shows the number of CPU cycles used by SQLite on a
standard workload, for versions of SQLite going back about 10 years.
Recent versions of SQLite use about one third as many the CPU cycles
compared to older versions.


This article describes how the SQLite developers measure CPU usage,
what those measurements actually mean, and the techniques used by
SQLite developers on their continuing quest to further reduce the
CPU usage of the SQLite library.






Measured using cachegrind on Ubuntu 16.04 on x64 with gcc 5.4.0 and -Os.



2. Measuring Performance

In brief, the CPU performance of SQLite is measured as follows:


 Compile SQLite in an as-delivered configuration, without any special
     telemetry or debugging options.
 Link SQLite against a test program that runs approximately 30,000
     SQL statements representing a typical workload.
 Count the number of CPU cycles consumed using
     cachegrind.


2.1. Compile Options

For performance measurement, SQLite is compiled in approximately the same
way as it would be for use in production systems.  The compile-time configuration
is "approximate" in the sense that every production use of SQLite is 
different. Compile-time options used by one system are not necessarily
the same as those used by others.  The key point is that options that 
significantly impact the generated machine code are avoided.  For example,
the -DSQLITE_DEBUG option is omitted because that option inserts thousands
of assert() statements in the middle of performance critical sections of the
SQLite library.  The -pg option (on GCC) is omitted because it causes the
compiler to emit extra probabilistic performance measuring code which interferes
with actual performance measurements.


For performance measurements,
the -Os option is used (optimize for size) rather than -O2 because the
-O2 option creates so much code movement that it is difficult to associate
specific CPU instructions to C source code lines.

2.2. Workload


The "typical" workload is generated by the
speedtest1.c
program in the canonical SQLite source tree.  This program strives to
exercise the SQLite library in a way that is typical of real-world
applications.  Of course, every application is different, and so
no test program can exactly mirror the behavior of all applications.


The speedtest1.c program is updated from time to time as the SQLite
developers' understanding of what constitutes "typical" usage evolves.


The 
speed-check.sh shell
script, also in the canonical source tree, is used to run the speedtest1.c
program.  To replicate the performance measurements, collect the following
files into a single directory:

 the "speed-check.sh" script,
 the "speedtest1.c" test program, and
 the SQLite amalgamation source files "sqlite3.c" and
     "sqlite3.h"


Then run "sh speed-check.sh trunk".


2.3. Performance Measurement


Cachegrind is used to
measure performance because it gives answers that are repeatable to 
7 or more significant digits.  In comparison, actual (wall-clock)
run times are scarcely repeatable beyond one significant digit.



2.4. Microoptimizations


The high repeatability of cachegrind allows the SQLite developers to
implement and measure "microoptimizations".  A microoptimization is
a change to the code that results in a very small performance increase.
Typical micro-optimizations reduce the number of CPU cycles by 0.1% or
0.05% or even less.  Such improvements are impossible to measure with
real-world timings.  But hundreds or thousands of microoptimizations
add up, resulting in measurable real-world performance gains.

3. Performance Measurement Workflow


As SQLite developers edit the SQLite source code, they run the
speed-check.sh
shell script to track the performance impact of changes.  This
script compiles the speedtest1.c program, runs it under cachegrind,
processes the cachegrind output using the
cg_anno.tcl TCL
script, then saves the results in a series of text files.
Typical output from the speed-check.sh script looks like this:


==8683== 
==8683== I   refs:      1,060,925,768
==8683== I1  misses:       23,731,246
==8683== LLi misses:            5,176
==8683== I1  miss rate:          2.24%
==8683== LLi miss rate:          0.00%
==8683== 
==8683== D   refs:        557,686,925  (361,828,925 rd   + 195,858,000 wr)
==8683== D1  misses:        5,067,063  (  3,544,278 rd   +   1,522,785 wr)
==8683== LLd misses:           57,958  (     16,067 rd   +      41,891 wr)
==8683== D1  miss rate:           0.9% (        1.0%     +         0.8%  )
==8683== LLd miss rate:           0.0% (        0.0%     +         0.0%  )
==8683== 
==8683== LL refs:          28,798,309  ( 27,275,524 rd   +   1,522,785 wr)
==8683== LL misses:            63,134  (     21,243 rd   +      41,891 wr)
==8683== LL miss rate:            0.0% (        0.0%     +         0.0%  )
   text	   data	    bss	    dec	    hex	filename
 523044	   8240	   1976	 533260	  8230c	sqlite3.o
 220507 1007870 7769352 sqlite3.c


The important parts of the output (the parts that the developers pay
the most attention to) are shown in red.
Basically, the developers want to know the size of the compiled SQLite
library and how many CPU cycles were needed to run the performance test.

The output from the 
cg_anno.tcl script
shows the number of CPU cycles spent on each line of code.
The report is approximately 80,000 lines long.  The following is a brief
snippet taken from the middle of the report to show what it looks like:


         .  SQLITE_PRIVATE int sqlite3BtreeNext(BtCursor *pCur, int *pRes){
         .    MemPage *pPage;
         .    assert( cursorOwnsBtShared(pCur) );
         .    assert( pRes!=0 );
         .    assert( *pRes==0 || *pRes==1 );
         .    assert( pCur-&gt;skipNext==0 || pCur-&gt;eState!=CURSOR_VALID );
   369,648    pCur-&gt;info.nSize = 0;
   369,648    pCur-&gt;curFlags &amp;= ~(BTCF_ValidNKey|BTCF_ValidOvfl);
   369,648    *pRes = 0;
   739,296    if( pCur-&gt;eState!=CURSOR_VALID ) return btreeNext(pCur, pRes);
 1,473,580    pPage = pCur-&gt;apPage&#91;pCur-&gt;iPage&#93;;
 1,841,975    if( (++pCur-&gt;aiIdx&#91;pCur-&gt;iPage&#93;)&gt;=pPage-&gt;nCell ){
     4,340      pCur-&gt;aiIdx&#91;pCur-&gt;iPage&#93;--;
     5,593      return btreeNext(pCur, pRes);
         .    }
   728,110    if( pPage-&gt;leaf ){
         .      return SQLITE_OK;
         .    }else{
     3,117      return moveToLeftmost(pCur);
         .    }
   721,876  }



The numbers on the left are the CPU cycle counts for that line of code,
of course.


The cg_anno.tcl script removes extraneous details from the default 
cachegrind annotation
output so that before-and-after reports can be compared using a 
side-by-side diff to view specific details of how a
micro-optimization attempt affected performance.


4. Limitations

The use of the standardized speedtest1.c workload and cachegrind has
enabled significant performance improvement.
However, it is important to recognize the limitations of this approach:



Performance measurements are done with a single compiler (gcc 5.4.0),
optimization setting (-Os), and
on a single platform (Ubuntu 16.04 LTS on x64).  The performance of
other compilers and processors may vary.


The speedtest1.c workload that is being measured tries to be representative
of a wide range of typical uses of SQLite.  But every application is
different.  The speedtest1.c workload might not be a good proxy for the
kinds of activities performed by some applications.  The SQLite developers
are constantly working to improve the speedtest1.c program, to make it
a better proxy for actual SQLite usage.  Community feedback is welcomed.


The cycle counts provided by cachegrind are a good proxy for actual
performance, but they are not 100% accurate.


Only CPU cycle counts are being measured here. 
CPU cycle counts are a good proxy for energy consumption,
but do not necessary correlate well with real-world timings.
Time spent doing I/O is not reflected in the CPU cycle counts,
and I/O time predominates in many SQLite usage scenarios.

This page last modified on  2022-01-08 05:02:57 UTC


c2: The Tcl interface to the SQLite library
c5: tclsqlite.html
c4:
The Tcl interface to the SQLite library

The SQLite library is designed to be very easy to use from
a Tcl or Tcl/Tk script.  SQLite
began as a Tcl extension
and the primary test suite for SQLite is written in TCL.  SQLite
can be used with any programming language, but its connections to
TCL run deep.

This document gives an overview of the Tcl
programming interface for SQLite.

The API

The interface to the SQLite library consists of single
tcl command named sqlite3
Because there is only this
one command, the interface is not placed in a separate
namespace.

The sqlite3 command is mostly used as follows
to open or create a database:


sqlite3&nbsp;&nbsp;dbcmd&nbsp;&nbsp;?database-name?&nbsp;&nbsp;?options?


To get information only, the sqlite3 command may be given exactly
one argument, either "-version", "-sourceid" or "-has-codec", which will
return the specified datum with no other effect.


With other arguments, the sqlite3 command opens the database
named in the second non-option argument, or named "" if there is no such.
If the open succeeds, a new Tcl command named by the first argument is created
and "" is returned.
(This approach is similar to the way widgets are created in Tk.)
If the open fails, an error is raised without creating a Tcl command
and an error message string is returned.

If the database does not already exist, the default behavior
is for it to be created automatically (though this can be changed by
using the "-create false" option).



The name of the database is usually just the name of a disk file in which
the database is stored.  If the name of the database is
the special name ":memory:", then a new database is created
in memory.  If the name of the database is an empty string, then
the database is created in an empty file that is automatically deleted
when the database connection closes.  URI filenames can be used if
the "-uri yes" option is supplied on the sqlite3 command.



Options understood by the sqlite3 command include:





-create BOOLEAN

If true, then a new database is created if one does not already exist.
If false, then an attempt to open a database file that does not previously
exist raises an error.  The default behavior is "true".


-nomutex BOOLEAN

If true, then all mutexes for the database connection are disabled.
This provides a small performance boost in single-threaded applications.


-readonly BOOLEAN

If true, then open the database file read-only.  If false, then the
database is opened for both reading and writing if filesystem permissions
allow, or for reading only if filesystem write permission is denied
by the operating system.  The default setting is "false".  Note that
if the previous process to have the database did not exit cleanly
and left behind a hot journal, then the write permission is required
to recover the database after opening, and the database cannot be
opened read-only.


-uri BOOLEAN

If true, then interpret the filename argument as a URI filename.  If
false, then the argument is a literal filename.  The default value is
"false".


-vfs VFSNAME

Use an alternative VFS named by the argument.


-fullmutex BOOLEAN

If true, multiple threads can safely attempt to use the database.
If false, such attempts are unsafe. The default value depends upon
how the extension is built.


-nofollow BOOLEAN

If true, and the database name refers to a symbolic link,
it will not be followed to open the true database file.
If false, symbolic links will be followed.
The default is "false".








Once an SQLite database is open, it can be controlled using
methods of the dbcmd.
There are currently 40 methods
defined.




authorizer
backup
bind_fallback
busy
cache
changes
close
collate
collation_needed
commit_hook
complete
config
copy
deserialize


enable_load_extension
errorcode
eval
exists
function
incrblob
interrupt
last_insert_rowid
nullvalue
onecolumn
preupdate
profile
progress
restore


rollback_hook
serialize
status
timeout
total_changes
trace
trace_v2
transaction
unlock_notify
update_hook
version
wal_hook





The use of each of these methods will be explained in the sequel, though
not in the order shown above.


The "eval" method


The most useful dbcmd method is "eval".  The eval method is used
to execute SQL on the database.  The syntax of the eval method looks
like this:


dbcmd&nbsp;&nbsp;eval&nbsp;&nbsp;?-withoutnulls?&nbsp;&nbsp;sql
&nbsp;&nbsp;?array-name?&nbsp;&nbsp;?script?



The job of the eval method is to execute the SQL statement or statements
given in the second argument.  For example, to create a new table in
a database, you can do this:


sqlite3 db1 ./testdb
db1 eval {CREATE TABLE t1(a int, b text)}


The above code creates a new table named t1 with columns
a and b.  What could be simpler?

Query results are returned as a list of column values.  If a
query requests 2 columns and there are 3 rows matching the query,
then the returned list will contain 6 elements.  For example:


db1 eval {INSERT INTO t1 VALUES(1,'hello')}
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
set x &#91;db1 eval {SELECT * FROM t1 ORDER BY a}&#93;


The variable $x is set by the above code to


1 hello 2 goodbye 3 howdy!


You can also process the results of a query one row at a time
by specifying the name of an array variable and a script following
the SQL code.  For each row of the query result, the values of all
columns will be inserted into the array variable and the script will
be executed.  For instance:


db1 eval {SELECT * FROM t1 ORDER BY a} values {
&nbsp;&nbsp;&nbsp;&nbsp;parray values
&nbsp;&nbsp;&nbsp;&nbsp;puts ""
}


This last code will give the following output:


values(*) = a b
values(a) = 1
values(b) = hello

values(*) = a b
values(a) = 2
values(b) = goodbye

values(*) = a b
values(a) = 3
values(b) = howdy!



For each column in a row of the result, the name of that column
is used as an index in to array and the value of the column is stored
in the corresponding array entry.  (Caution:  If two or more columns
in the result set of a query have the same name, then the last column
with that name will overwrite prior values and earlier columns with the
same name will be inaccessible.) The special array index * is
used to store a list of column names in the order that they appear.



Normally, NULL SQL results are stored in the array using the
nullvalue setting.  However, if
the -withoutnulls option is used, then NULL SQL values
cause the corresponding array element to be unset instead.



If the array variable name is omitted or is the empty string, then the value of
each column is stored in a variable with the same name as the column
itself.  For example:



db1 eval {SELECT * FROM t1 ORDER BY a} {
&nbsp;&nbsp;&nbsp;&nbsp;puts "a=$a b=$b"
}



From this we get the following output



a=1 b=hello
a=2 b=goodbye
a=3 b=howdy!





Tcl variable names can appear in the SQL statement of the second argument
in any position where it is legal to put a string or number literal.  The
value of the variable is substituted for the variable name.  If the
variable does not exist a NULL values is used.  For example:



db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}



Note that it is not necessary to quote the $bigstring value.  That happens
automatically.  If $bigstring is a large string or binary object, this
technique is not only easier to write, it is also much more efficient
since it avoids making a copy of the content of $bigstring.



If the $bigstring variable has both a string and a "bytearray" representation,
then TCL inserts the value as a string.  If it has only a "bytearray"
representation, then the value is inserted as a BLOB.  To force a
value to be inserted as a BLOB even if it also has a text representation,
use a "@" character to in place of the "$".  Like this:



db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}



If the variable does not have a bytearray representation, then "@" works
just like "$".  Note that ":" works like "$" in all cases so the following
is another way to express the same statement:



db1 eval {INSERT INTO t1 VALUES(5,:bigstring)}


The use of ":" instead of "$" before the name of a variable can
sometimes be useful if the SQL text is enclosed in double-quotes "..."
instead of curly-braces {...}.
When the SQL is contained within double-quotes "..." then TCL will do
the substitution of $-variables, which can lead to SQL injection if
extreme care is not used.  But TCL will never substitute a :-variable
regardless of whether double-quotes "..." or curly-braces {...} are
used to enclose the SQL, so the use of :-variables adds an extra
measure of defense against SQL
injection.



The "close" method



As its name suggests, the "close" method to an SQLite database just
closes the database.  This has the side-effect of deleting the
dbcmd Tcl command.  Here is an example of opening and then
immediately closing a database:



sqlite3 db1 ./testdb
db1 close



If you delete the dbcmd directly, that has the same effect
as invoking the "close" method.  So the following code is equivalent
to the previous:


sqlite3 db1 ./testdb
rename db1 {}


The "transaction" method



The "transaction" method is used to execute a TCL script inside an SQLite
database transaction.  The transaction is committed when the script completes,
or it rolls back if the script fails.  If the transaction occurs within
another transaction (even one that is started manually using BEGIN) it
is a no-op.



The transaction command can be used to group together several SQLite
commands in a safe way.  You can always start transactions manually using
BEGIN, of
course.  But if an error occurs so that the COMMIT or ROLLBACK are never
run, then the database will remain locked indefinitely.  Also, BEGIN
does not nest, so you have to make sure no other transactions are active
before starting a new one.  The "transaction" method takes care of
all of these details automatically.



The syntax looks like this:



dbcmd&nbsp;&nbsp;transaction&nbsp;&nbsp;?transaction-type?
&nbsp;&nbsp;script




The transaction-type can be one of deferred,
exclusive or immediate.  The default is deferred.


The "cache" method



The "eval" method described above keeps a cache of
prepared statements
for recently evaluated SQL commands.
The "cache" method is used to control this cache.
The first form of this command is:


dbcmd&nbsp;&nbsp;cache size&nbsp;&nbsp;N


This sets the maximum number of statements that can be cached.
The upper limit is 100.  The default is 10.  If you set the cache size
to 0, no caching is done.

The second form of the command is this:



dbcmd&nbsp;&nbsp;cache flush


The cache-flush method
finalizes
all prepared statements currently
in the cache.


The "complete" method



The "complete" method takes a string of supposed SQL as its only argument.
It returns TRUE if the string is a complete statement of SQL and FALSE if
there is more to be entered.

The "complete" method is useful when building interactive applications
in order to know when the user has finished entering a line of SQL code.
This is really just an interface to the
sqlite3_complete() C
function.

The "config" method



The "config" method queries or changes certain configuration settings for
the database connection using the sqlite3_db_config() interface.
Run this method with no arguments to get a TCL list of available
configuration settings and their current values:


dbcmd&nbsp;&nbsp;config


The above will return something like this:


defensive 0 dqs_ddl 1 dqs_dml 1 enable_fkey 0 enable_qpsg 0 enable_trigger 1 enable_view 1 fts3_tokenizer 1 legacy_alter_table 0 legacy_file_format 0 load_extension 0 no_ckpt_on_close 0 reset_database 0 trigger_eqp 0 trusted_schema 1 writable_schema 0


Add the name of an individual configuration setting to query the current
value of that setting.  Optionally add a boolean value to change a setting.


The following four configuration changes are recommended for maximum
application security.  Turning off the trust_schema setting prevents
virtual tables and dodgy SQL functions from being used inside of triggers,
views, CHECK constraints, generated columns, and expression indexes.
Turning off the dqs_dml and dqs_ddl settings prevents the use of
double-quoted strings.  Turning on defensive prevents direct writes
to shadow tables.


db config trusted_schema 0
db config defensive 1
db config dqs_dml 0
db config dqs_ddl 0


The "copy" method



The "copy" method copies data from a file into a table.
It returns the number of rows processed successfully from the file.
The syntax of the copy method looks like this:


dbcmd&nbsp;&nbsp;copy&nbsp;&nbsp;conflict-algorithm
&nbsp;&nbsp;table-name&nbsp;&nbsp;&nbsp;file-name&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;?column-separator?
&nbsp;&nbsp;?null-indicator?


Conflict-algorithm must be one of the SQLite conflict algorithms for
the INSERT statement: rollback, abort,
fail,ignore, or replace. See the SQLite Language
section for ON CONFLICT for
more information. The conflict-algorithm must be specified in lower case.


Table-name must already exists as a table.  File-name must exist, and
each row must contain the same number of columns as defined in the table.
If a line in the file contains more or less than the number of columns defined,
the copy method rollbacks any inserts, and returns an error.

Column-separator is an optional column separator string.  The default is
the ASCII tab character \t. 

Null-indicator is an optional string that indicates a column value is null.
The default is an empty string.  Note that column-separator and
null-indicator are optional positional arguments; if null-indicator
is specified, a column-separator argument must be specified and
precede the null-indicator argument.

The copy method implements similar functionality to the .import
SQLite shell command.

The "timeout" method


The "timeout" method is used to control how long the SQLite library
will wait for locks to clear before giving up on a database transaction.
The default timeout is 0 millisecond.  (In other words, the default behavior
is not to wait at all.)

The SQLite database allows multiple simultaneous
readers or a single writer but not both.  If any process is writing to
the database no other process is allows to read or write.  If any process
is reading the database other processes are allowed to read but not write.
The entire database shared a single lock.

When SQLite tries to open a database and finds that it is locked, it
can optionally delay for a short while and try to open the file again.
This process repeats until the query times out and SQLite returns a
failure.  The timeout is adjustable.  It is set to 0 by default so that
if the database is locked, the SQL statement fails immediately.  But you
can use the "timeout" method to change the timeout value to a positive
number.  For example:

db1 timeout 2000

The argument to the timeout method is the maximum number of milliseconds
to wait for the lock to clear.  So in the example above, the maximum delay
would be 2 seconds.

The "busy" method


The "busy" method, like "timeout", only comes into play when the
database is locked.  But the "busy" method gives the programmer much more
control over what action to take.  The "busy" method specifies a callback
Tcl procedure that is invoked whenever SQLite tries to open a locked
database.  A single integer argument is appended to the callback before
it is invoke.  The argument is the number of prior calls to the busy
callback for the current locking event.  It is intended that
the callback will do some other useful work for a short while
(such as service GUI events) then return
so that the lock can be tried again.  The callback procedure should
return "0" if it wants SQLite to try again to open the database and
should return "1" if it wants SQLite to abandon the current operation.

If the busy method is invoked without an argument, the name of the callback
procedure last set by the busy method is returned.  If no callback procedure
has been set, an empty string is returned.

The "enable_load_extension" method


The extension loading mechanism of SQLite (accessed using the
load_extension() SQL function) is turned off by default.  This is
a security precaution.  If an application wants to make use of the
load_extension() function it must first turn the capability on using
this method.

This method takes a single boolean argument which will turn the
extension loading functionality on or off.

For best security, do not use this method unless truly needed,
and run PRAGMA trusted_schema=OFF or the
"db config trusted_schema 0" method before
invoking this method.

This method maps to the sqlite3_enable_load_extension() C/C++
interface.

The "exists" method


The "exists" method is similar to "onecolumn" and "eval" in that
it executes SQL statements.  The difference is that the "exists" method
always returns a boolean value which is TRUE if a query in the SQL
statement it executes returns one or more rows and FALSE if the SQL
returns an empty set.

The "exists" method is often used to test for the existence of
rows in a table.  For example:


if {&#91;db exists {SELECT 1 FROM table1 WHERE user=$user}&#93;} {
&nbsp;&nbsp;&nbsp;# Processing if $user exists
} else {
&nbsp;&nbsp;&nbsp;# Processing if $user does not exist
}


The "last_insert_rowid" method


The "last_insert_rowid" method returns an integer which is the ROWID
of the most recently inserted database row.

The "function" method


The "function" method registers new SQL functions with the SQLite engine.
The arguments are the name of the new SQL function and a TCL command that
implements that function.  Arguments to the function are appended to the
TCL command before it is invoked.


For security reasons, it is recommended that applications first set
PRAGMA trusted_schema=OFF or run the
"db config trusted_schema 0"
method before using this method.


The syntax looks like this:



dbcmd&nbsp;&nbsp;function
&nbsp;&nbsp;sql-name
&nbsp;&nbsp;?options?
&nbsp;&nbsp;script



The following example creates a new SQL function named "hex" that converts
its numeric argument in to a hexadecimal encoded string:



db function hex {format 0x%X}


The "function" method accepts the following options:



-argcount INTEGER

Specify the number of arguments that the SQL function accepts.  The default
value of -1 means any number of arguments.

-deterministic

This option indicates that the function will always return the same
answer given the same argument values.  The SQLite query optimizer
uses this information to cache answers from function calls with
constant inputs and reuse the result rather than invoke the function
repeatedly.


-directonly

This option restricts the function to only be usable by direct
top-level SQL statement.  The function will not be accessible to
triggers, views, CHECK constraints, generated columns, or index
expressions.  This option is recommended for all application-defined
SQL functions, and is highly recommended for any SQL
function that has side effects or that reveals internal state of
the application.

Security Warning:
Without this switch, an attacker might be able to change the
schema of a database file to include the new function inside a trigger
or view or CHECK constraint and thereby trick the application into
running the function with parameters of the attacker's choosing.
Hence, if the new function has side effects or reveals internal
state about the application and the -directonly option is not
used, that is a potential security vulnerability.


-innocuous

This option indicates that the function has no side effects and
does not leak any information that cannot be computed directly
from its input parameters.  When this option is specified, the
function may be used in triggers, views, CHECK constraints,
generated columns, and/or index expressions even if
PRAGMA trusted_schema=OFF.  The use of this option is discouraged
unless it is truly needed.


-returntype integer|real|text|blob|any

This option is used to configure the type of the result returned by the
function.  If this option is set to "any" (the default), SQLite attempts to
determine the type of each value returned by the function implementation based
on the Tcl value's internal type. Or, if it is set to "text" or "blob", the
returned value is always a text or blob value, respectively. If this option is
set to "integer", SQLite attempts to coerce the value returned by the function
to an integer. If this is not possible without data loss, it attempts to coerce
it to a real value, and finally falls back to text. If this option is set to
"real", an attempt is made to return a real value, falling back to text if this
is not possible.







The "nullvalue" method



The "nullvalue" method changes the representation for NULL returned
as result of the "eval" method.


db1 nullvalue NULL


The "nullvalue" method is useful to differ between NULL and empty
column values as Tcl lacks a NULL representation.  The default
representation for NULL values is an empty string.

The "onecolumn" method


The "onecolumn" method works like
"eval" in that it evaluates the
SQL query statement given as its argument.  The difference is that
"onecolumn" returns a single element which is the first column of the
first row of the query result.

This is a convenience method.  It saves the user from having to
do a "&#91;lindex&nbsp;...&nbsp;0&#93;" on the results of an "eval"
in order to extract a single column result.

The "changes" method


The "changes" method returns an integer which is the number of rows
in the database that were inserted, deleted, and/or modified by the most
recent "eval" method.

The "total_changes" method


The "total_changes" method returns an integer which is the number of rows
in the database that were inserted, deleted, and/or modified since the
current database connection was first opened.

The "authorizer" method


The "authorizer" method provides access to the
sqlite3_set_authorizer
C/C++ interface.  The argument to authorizer is the name of a procedure that
is called when SQL statements are being compiled in order to authorize
certain operations.  The callback procedure takes 5 arguments which describe
the operation being coded.  If the callback returns the text string
"SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.


If the argument is an empty string then the authorizer is disabled.
If the argument is omitted, then the current authorizer is returned.

The "bind_fallback" method


The "bind_fallback" method gives the application control over how to
handle parameter binding when no TCL variable matches the parameter name.

When the eval method sees a named SQL
parameter such as "$abc" or ":def" or "@ghi" in an SQL statement, it tries
to look up a TCL variable with the same name, and it binds the value
of that TCL variable to the SQL parameter.  If no such TCL variable exists,
the default behavior is to bind an SQL NULL value to the parameter.  However,
if a bind_fallback proc is specified, then that proc is invoked with the
name of the SQL parameter and the return value from the proc is bound to
the SQL parameter.  Or if the proc returns an error, then the SQL statement
aborts with that error.  If the proc returns with some code other than
TCL_OK or TCL_ERROR, then the SQL parameter is bound to NULL, as it would
be by default.

The "bind_fallback" method has a single optional argument.  If the argument
is an empty string, then the bind_fallback is cancelled and the default behavior
is restored.  If the argument is a non-empty string, then the argument is a
TCL command (usually the name of a proc) to invoke whenever an SQL parameter
is seen that does not match any TCL variable.  If the "bind_fallback" method
is given no arguments, then the current bind_fallback command is returned.

As an example, the following setup causes TCL to throw an error if
an SQL statement contains an parameter that does not match any global
TCL variable:


proc bind_error {nm} {
  error "no such variable: $nm"
}
db bind_fallback bind_error


The "progress" method


This method registers a callback that is invoked periodically during
query processing.  There are two arguments: the number of SQLite virtual
machine opcodes between invocations, and the TCL command to invoke.
Setting the progress callback to an empty string disables it.

The progress callback can be used to display the status of a lengthy
query or to process GUI events during a lengthy query.

The "collate" method


This method registers new text collating sequences.  There are
two arguments: the name of the collating sequence and the name of a
TCL procedure that implements a comparison function for the collating
sequence.


For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:



proc nocase_compare {a b} {
  return &#91;string compare &#91;string tolower $a] &#91;string tolower $b]]
}
db collate NOCASE nocase_compare


The "collation_needed" method


This method registers a callback routine that is invoked when the SQLite
engine needs a particular collating sequence but does not have that
collating sequence registered.  The callback can register the collating
sequence.  The callback is invoked with a single parameter which is the
name of the needed collating sequence.

The "commit_hook" method


This method registers a callback routine that is invoked just before
SQLite tries to commit changes to a database.  If the callback throws
an exception or returns a non-zero result, then the transaction rolls back
rather than commit.

The "rollback_hook" method


This method registers a callback routine that is invoked just before
SQLite tries to do a rollback.  The script argument is run without change.

The "status" method

This method returns status information from the most recently evaluated
SQL statement.  The status method takes a single argument which should be
either "steps" or "sorts".  If the argument is "steps", then the method
returns the number of full table scan steps that the previous SQL statement
evaluated.  If the argument is "sorts", the method returns the number of
sort operations.  This information can be used to detect queries that are
not using indices to speed search or sorting.

The status method is basically a wrapper on the
sqlite3_stmt_status() C-language interface.

The "update_hook" method


This method registers a callback routine that is invoked just after
each row is modified by an UPDATE, INSERT, or DELETE statement.  Four
arguments are appended to the callback before it is invoked:


The keyword "INSERT", "UPDATE", or "DELETE", as appropriate
The name of the database which is being changed
The table that is being changed
The rowid of the row in the table being changed


The callback must not do anything that will modify the database connection
that invoked the update hook such as running queries.

The "preupdate" method


This method either registers a callback routine that is invoked just
before each row is modified by an UPDATE, INSERT, or DELETE statement,
or may perform certain operations related to the impending update.

To register or remove a preupdate callback, use this syntax:

dbcmd&nbsp;&nbsp;preupdate&nbsp;&nbsp;hook&nbsp;&nbsp;?SCRIPT?

When a preupdate callback is registered, then prior to each row modification,
the callback is run with these arguments:

The keyword "INSERT", "UPDATE", or "DELETE", as appropriate
The name of the database which is being changed
The table that is being changed
The original rowid of the row in the table being changed
The new rowid (if any) of the row in the table being changed

The callback must not do anything that will modify the database connection
that invoked the preupdate hook such as running queries.

When the callback is executing, and only then, these preupdate operations
may be performed by use of the indicated syntax:

dbcmd&nbsp;&nbsp;preupdate&nbsp;&nbsp;count
dbcmd&nbsp;&nbsp;preupdate&nbsp;&nbsp;depth
dbcmd&nbsp;&nbsp;preupdate&nbsp;&nbsp;new&nbsp;&nbsp;INDEX
dbcmd&nbsp;&nbsp;preupdate&nbsp;&nbsp;old&nbsp;&nbsp;INDEX



The count submethod returns the number of columns in the row that is
being inserted, updated, or deleted.
The depth submethod returns the update nesting depth. This will be
0 for a direct insert, update, or delete operation;
1 for inserts, updates, or deletes invoked by top-level triggers;
or higher values for changes resulting from trigger-invoked triggers.

The old and new submethods return the selected original
or changed column value respectively of the row being updated.

Note that the Tcl interface (and underlying SQLite library) must have
been built with the preprocessor symbol SQLITE_ENABLE_PREUPDATE_HOOK
defined for the preupdate method to be available.

The "wal_hook" method


This method registers a callback routine that is invoked after transaction
commit when the database is in WAL mode.  Two arguments are appended to the
callback command before it is invoked:


The name of the database on which the transaction was committed
The number of entries in the write-ahead log (WAL) file for that database


This method might decide to run a checkpoint either itself or as a
subsequent idle callback.  Note that SQLite only allows a single WAL hook.
By default this single WAL hook is used for the auto-checkpointing.  If you
set up an explicit WAL hook, then that one WAL hook must ensure that checkpoints
are occurring since the auto-checkpointing mechanism will be disabled.

This method should return an integer value that is equivalent to an
SQLite error code (usually 0 for SQLITE_OK in the case of success or 1 for
SQLITE_ERROR if some error occurs). As in sqlite3_wal_hook(), the results of
returning an integer that does not correspond to an SQLite error code are
undefined. If the value returned by the script cannot be interpreted as an
integer value, or if the script throws a Tcl exception, no error is returned to
SQLite but a Tcl background-error is raised.

The "incrblob" method


This method opens a TCL channel that can be used to read or write
into a preexisting BLOB in the database.  The syntax is like this:


dbcmd&nbsp;&nbsp;incrblob&nbsp;&nbsp;?-readonly?
&nbsp;&nbsp;?DB?&nbsp;&nbsp;TABLE&nbsp;&nbsp;COLUMN&nbsp;&nbsp;ROWID



The command returns a new TCL channel for reading or writing to the BLOB.
The channel is opened using the underlying
sqlite3_blob_open() C-language
interface.  Close the channel using the close command of TCL.


The "errorcode" method


This method returns the numeric error code that resulted from the most
recent SQLite operation.

The "trace" method


The "trace" method registers a callback that is invoked as each SQL
statement is compiled.  The text of the SQL is appended as a single string
to the command before it is invoked.  This can be used (for example) to
keep a log of all SQL operations that an application performs.


The "trace_v2" method


The "trace_v2" method registers a callback that is invoked as each SQL
statement is compiled. The syntax is as follows:



dbcmd&nbsp;&nbsp;trace_v2&nbsp;&nbsp;?callback?&nbsp;&nbsp;?mask?


This command causes the "callback" script to be invoked whenever
certain conditions occurs.  The conditions are determined by the mask
argument, which should be a TCL-list of zero or more of the following
keywords:


 statement
 profile
 row
 close


Traces for statement invoke the callback with two arguments
whenever a new SQL statement is run.
The first argument is an integer which is the value of the pointer
to the underlying sqlite3_stmt object.  This integer can be used
to correlate SQL statement text with the result of a profile
or row callback. The second argument is the
unexpanded text of the SQL statement being run.  By "unexpanded", we
mean that variable substitutions in the text are not expanded into the
variable values.  This is different from the behavior of the "trace"
method which does expand variable substitutions.

Traces for profile invoke the callback with two arguments
as each SQL statement finishes.  The first argument is an integer which
is the value of the underlying sqlite3_stmt object.  The second
argument is the approximate run-time for the statement in nanoseconds.
The run-time is the best estimate available depending on the capabilities
of the platform on which the application is running.

Traces for row invoke the callback with a single argument
whenever a new result row is available from an SQL statement.
The argument is an integer which is the value of the underlying
sqlite3_stmt object pointer.

Traces for close invoke the callback with a single argument
as the database connection is closing.  The argument is an integer which
is the value of a pointer to the underlying sqlite3 object that is
closing.

There can only be a single trace callback registered on a database
connection.  Each use of "trace" or "trace_v2" cancels all prior
trace callback.

The "backup" method


The "backup" method makes a backup copy of a live database.  The
command syntax is like this:


dbcmd&nbsp;&nbsp;backup&nbsp;&nbsp;?source-database?&nbsp;&nbsp;backup-filename


The optional source-database argument tells which database in
the current connection should be backed up.  The default value is main
(or, in other words, the primary database file).  To back up TEMP tables
use temp.  To backup an auxiliary database added to the connection
using the ATTACH command, use the name of that database as it was assigned
in the ATTACH command.

The backup-filename is the name of a file into which the backup is
written.  Backup-filename does not have to exist ahead of time, but if
it does, it must be a well-formed SQLite database.

The "restore" method


The "restore" method copies the content from a separate database file
into the current database connection, overwriting any preexisting content.
The command syntax is like this:


dbcmd&nbsp;&nbsp;restore&nbsp;&nbsp;?target-database?&nbsp;&nbsp;source-filename


The optional target-database argument tells which database in
the current connection should be overwritten with new content.
The default value is main
(or, in other words, the primary database file).  To repopulate the TEMP tables
use temp.  To overwrite an auxiliary database added to the connection
using the ATTACH command, use the name of that database as it was assigned
in the ATTACH command.

The source-filename is the name of an existing well-formed SQLite
database file from which the content is extracted.

The "serialize" method


The "serialize" method creates a BLOB which is a complete copy of an
underlying database.  The syntax is like this:


dbcmd&nbsp;&nbsp;serialize&nbsp;&nbsp;?database?


The optional argument is the name of the schema or database to be serialized.
The default value is "main".

This routine returns a TCL byte-array that is the complete content of
the identified database.  This byte-array can be written into a file and
then used as an ordinary SQLite database, or it can be sent over a TCP/IP
connection to some other application, or passed to the "deserialize" method
of another database connection.

This method only functions if SQLite is compiled with -DSQLITE_ENABLE_DESERIALIZE

The "deserialize" method

The "deserialize" method takes a TCL byte-array that contains an SQLite
database file and adds it to the database connection.  The syntax is:


dbcmd&nbsp;&nbsp;deserialize&nbsp;&nbsp;?database?&nbsp;&nbsp;value


The option database argument identifies which attached database
should receive the deserialization.  The default is "main".

This command causes SQLite to disconnect from the previous database and
reattach to an in-memory database with the content in value.  If value
is not a byte-array containing a well-defined SQLite database, then subsequent
commands will likely return SQLITE_CORRUPT errors.

This method only functions if SQLite is compiled with -DSQLITE_ENABLE_DESERIALIZE

The "interrupt" method

The "interrupt" method invokes the sqlite3_interrupt() interface, causing
any pending queries to halt.

The "version" method

  Return the current library version. For example, "3.23.0".

The "profile" method

This method is used to profile the execution of SQL statements run by
   the application. The syntax is as follows:



dbcmd&nbsp;&nbsp;profile&nbsp;&nbsp;?script?


Unless script is an empty string, this method arranges for the
script to be evaluated after the execution of each SQL statement.
Two arguments are appended to script before it is invoked: the
text of the SQL statement executed and the time elapsed while executing
the statement, in nanoseconds.

A database handle may only have a single profile script registered at
any time. If there is already a script registered when the profile method
is invoked, the previous profile script is replaced by the new one. If the
script argument is an empty string, any previously registered
profile callback is canceled but no new profile script is registered.


The "unlock_notify" method

The unlock_notify method is used access the sqlite3_unlock_notify()
   interface to the SQLite core library for testing purposes.  The use of
   this method by applications is discouraged.


