# page_content

c0: struct sqlite3_api_routines
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.


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_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_create_filename(), sqlite3_free_filename()
c2: C API: Create and Destroy VFS Filenames
c5: c3ref/create_filename.html
c4:
These interfces 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_blob_read()
c2: C API: Read Data From A BLOB Incrementally
c5: c3ref/blob_read.html
c4:
This function is used to read data from an open BLOB handle into a
caller-supplied buffer. N bytes of data are copied into buffer Z
from the open BLOB, starting at offset iOffset.

If offset iOffset is less than N bytes from the end of the BLOB,
SQLITE_ERROR is returned and no data is read.  If N or iOffset is
less than zero, SQLITE_ERROR is returned and no data is read.
The size of the blob (and hence the maximum value of N+iOffset)
can be determined using the sqlite3_blob_bytes() interface.

An attempt to read from an expired BLOB handle fails with an
error code of SQLITE_ABORT.

On success, sqlite3_blob_read() returns SQLITE_OK.
Otherwise, an error code or an extended error code is returned.

This routine only works on a BLOB handle which has been created
by a prior successful call to sqlite3_blob_open() and which has not
been closed by sqlite3_blob_close().  Passing any other pointer in
to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_write().
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.

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.


c0: sqlite3_value_dup(), sqlite3_value_free()
c2: C API: Copy And Free SQL Values
c5: c3ref/value_dup.html
c4:
The sqlite3_value_dup(V) interface makes a copy of the sqlite3_value
object D and returns a pointer to that copy.  The sqlite3_value returned
is a protected sqlite3_value object even if the input is not.
The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
memory allocation fails. If V is a pointer value, then the result
of sqlite3_value_dup(V) is a NULL value.

The sqlite3_value_free(V) interface frees an sqlite3_value object
previously obtained from sqlite3_value_dup().  If V is a NULL pointer
then sqlite3_value_free(V) is a harmless no-op.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_aggregate_context()
c2: C API: Obtain Aggregate Function Context
c5: c3ref/aggregate_context.html
c4:
Implementations of aggregate SQL functions use this
routine to allocate memory for storing their state.

The first time the sqlite3_aggregate_context(C,N) routine is called
for a particular aggregate function, SQLite allocates
N bytes of memory, zeroes out that memory, and returns a pointer
to the new memory. On second and subsequent calls to
sqlite3_aggregate_context() for the same aggregate function instance,
the same buffer is returned.  Sqlite3_aggregate_context() is normally
called once for each invocation of the xStep callback and then one
last time when the xFinal callback is invoked.  When no rows match
an aggregate query, the xStep() callback of the aggregate function
implementation is never called and xFinal() is called exactly once.
In those cases, sqlite3_aggregate_context() might be called for the
first time from within xFinal().

The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
when first called if N is less than or equal to zero or if a memory
allocate error occurs.

The amount of space allocated by sqlite3_aggregate_context(C,N) is
determined by the N parameter on first successful call.  Changing the
value of N in any subsequent call to sqlite3_aggregate_context() within
the same aggregate function instance will not resize the memory
allocation.  Within the xFinal callback, it is customary to set
N=0 in calls to sqlite3_aggregate_context(C,N) so that no
pointless memory allocations occur.

SQLite automatically frees the memory allocated by
sqlite3_aggregate_context() when the aggregate query concludes.

The first parameter must be a copy of the
SQL function context that is the first parameter
to the xStep or xFinal callback routine that implements the aggregate
function.

This routine must be called from the same thread in which
the aggregate SQL function is running.
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.


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.


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: SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_BLOB, SQLITE_NULL
c2: C API: Fundamental Datatypes
c5: c3ref/c_blob.html
c4:
Every value in SQLite has one of five fundamental datatypes:


 64-bit signed integer
 64-bit IEEE floating point number
 string
 BLOB
 NULL


These constants are codes for each of those types.

Note that the SQLITE_TEXT constant was also used in SQLite version 2
for a completely different meaning.  Software that links against both
SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
SQLITE_TEXT.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, SQLITE_UTF16, SQLITE_ANY, SQLITE_UTF16_ALIGNED
c2: C API: Text Encodings
c5: c3ref/c_any.html
c4:
These constant define integer codes that represent the various
text encodings supported by SQLite.
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_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) must 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_MISUSE or perhaps
exhibit some other undefined or harmful behavior.

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: Result Values From A Query
c5: c3ref/column_blob.html
c0:
sqlite3_column_blob(), sqlite3_column_double(), sqlite3_column_int(), sqlite3_column_int64(), sqlite3_column_text(), sqlite3_column_text16(), sqlite3_column_value(), sqlite3_column_bytes(), sqlite3_column_bytes16(), sqlite3_column_type()

c4:
Summary:


Details:

These routines return information about a single column of the current
result row of a query.  In every case the first argument is a pointer
to the prepared statement that is being evaluated (the sqlite3_stmt*
that was returned from sqlite3_prepare_v2() or one of its variants)
and the second argument is the index of the column for which information
should be returned. The leftmost column of the result set has the index 0.
The number of columns in the result can be determined using
sqlite3_column_count().

If the SQL statement does not currently point to a valid row, or if the
column index is out of range, the result is undefined.
These routines may only be called when the most recent call to
sqlite3_step() has returned SQLITE_ROW and neither
sqlite3_reset() nor sqlite3_finalize() have been called subsequently.
If any of these routines are called after sqlite3_reset() or
sqlite3_finalize() or after sqlite3_step() has returned
something other than SQLITE_ROW, the results are undefined.
If sqlite3_step() or sqlite3_reset() or sqlite3_finalize()
are called from a different thread while any of these routines
are pending, then the results are undefined.

The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
each return the value of a result column in a specific data format.  If
the result column is not initially in the requested format (for example,
if the query returns an integer but the sqlite3_column_text() interface
is used to extract the value) then an automatic type conversion is performed.

The sqlite3_column_type() routine returns the
datatype code for the initial data type
of the result column.  The returned value is one of SQLITE_INTEGER,
SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.
The return value of sqlite3_column_type() can be used to decide which
of the first six interface should be used to extract the column value.
The value returned by sqlite3_column_type() is only meaningful if no
automatic type conversions have occurred for the value in question.
After a type conversion, the result of calling sqlite3_column_type()
is undefined, though harmless.  Future
versions of SQLite may change the behavior of sqlite3_column_type()
following a type conversion.

If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
or sqlite3_column_bytes16() interfaces can be used to determine the size
of that BLOB or string.

If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-16 string, then sqlite3_column_bytes() converts
the string to UTF-8 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes() uses
sqlite3_snprintf() to convert that value to a UTF-8 string and returns
the number of bytes in that string.
If the result is NULL, then sqlite3_column_bytes() returns zero.

If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
the string to UTF-16 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes16() uses
sqlite3_snprintf() to convert that value to a UTF-16 string and returns
the number of bytes in that string.
If the result is NULL, then sqlite3_column_bytes16() returns zero.

The values returned by sqlite3_column_bytes() and
sqlite3_column_bytes16() do not include the zero terminators at the end
of the string.  For clarity: the values returned by
sqlite3_column_bytes() and sqlite3_column_bytes16() are the number of
bytes in the string, not the number of characters.

Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
even empty strings, are always zero-terminated.  The return
value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.

Strings returned by sqlite3_column_text16() always have the endianness
which is native to the platform, regardless of the text encoding set
for the database.

Warning: The object returned by sqlite3_column_value() is an
unprotected sqlite3_value object.  In a multithreaded environment,
an unprotected sqlite3_value object may only be used safely with
sqlite3_bind_value() and sqlite3_result_value().
If the unprotected sqlite3_value object returned by
sqlite3_column_value() is used in any other way, including calls
to routines like sqlite3_value_int(), sqlite3_value_text(),
or sqlite3_value_bytes(), the behavior is not threadsafe.
Hence, the sqlite3_column_value() interface
is normally only useful within the implementation of
application-defined SQL functions or virtual tables, not within
top-level application code.

These routines may attempt to convert the datatype of the result.
For example, if the internal representation is FLOAT and a text result
is requested, sqlite3_snprintf() is used internally to perform the
conversion automatically.  The following table details the conversions
that are applied:



Note that when type conversions occur, pointers returned by prior
calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
sqlite3_column_text16() may be invalidated.
Type conversions and pointer invalidations might occur
in the following cases:


 The initial content is a BLOB and sqlite3_column_text() or
sqlite3_column_text16() is called.  A zero-terminator might
need to be added to the string.
 The initial content is UTF-8 text and sqlite3_column_bytes16() or
sqlite3_column_text16() is called.  The content must be converted
to UTF-16.
 The initial content is UTF-16 text and sqlite3_column_bytes() or
sqlite3_column_text() is called.  The content must be converted
to UTF-8.


Conversions between UTF-16be and UTF-16le are always done in place and do
not invalidate a prior pointer, though of course the content of the buffer
that the prior pointer references will have been modified.  Other kinds
of conversion are done in place when it is possible, but sometimes they
are not possible and in those cases prior pointers are invalidated.

The safest policy is to invoke these routines
in one of the following ways:


sqlite3_column_text() followed by sqlite3_column_bytes()
sqlite3_column_blob() followed by sqlite3_column_bytes()
sqlite3_column_text16() followed by sqlite3_column_bytes16()


In other words, you should call sqlite3_column_text(),
sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
into the desired format, then invoke sqlite3_column_bytes() or
sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
to sqlite3_column_text() or sqlite3_column_blob() with calls to
sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
with calls to sqlite3_column_bytes().

The pointers returned are valid until a type conversion occurs as
described above, or until sqlite3_step() or sqlite3_reset() or
sqlite3_finalize() is called.  The memory space used to hold strings
and BLOBs is freed automatically.  Do not pass the pointers returned
from sqlite3_column_blob(), sqlite3_column_text(), etc. into
sqlite3_free().

As long as the input parameters are correct, these routines will 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_column_blob()
 sqlite3_column_text()
 sqlite3_column_text16()
 sqlite3_column_bytes()
 sqlite3_column_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: struct sqlite3_pcache
c2: C API: Custom Page Cache Object
c5: c3ref/pcache.html
c4:
The sqlite3_pcache type is opaque.  It is implemented by
the pluggable module.  The SQLite core has no knowledge of
its size or internal structure and never deals with the
sqlite3_pcache object except by holding and passing pointers
to the object.

See sqlite3_pcache_methods2 for additional information.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: struct sqlite3_backup
c2: C API: Online Backup Object
c5: c3ref/backup.html
c4:
The sqlite3_backup object records state information about an ongoing
online backup operation.  The sqlite3_backup object is created by
a call to sqlite3_backup_init() and is destroyed by a call to
sqlite3_backup_finish().

See Also: Using the SQLite Online Backup API
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.

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.

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.


c0: sqlite3_autovacuum_pages()
c2: C API: Autovacuum Compaction Amount Callback
c5: c3ref/autovacuum_pages.html
c4:
The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback
function C that is invoked prior to each autovacuum of the database
file.  The callback is passed a copy of the generic data pointer (P),
the schema-name of the attached database that is being autovacuumed,
the the size of the database file in pages, the number of free pages,
and the number of bytes per page, respectively.  The callback should
return the number of free pages that should be removed by the
autovacuum.  If the callback returns zero, then no autovacuum happens.
If the value returned is greater than or equal to the number of
free pages, then a complete autovacuum happens.

If there are multiple ATTACH-ed database files that are being
modified as part of a transaction commit, then the autovacuum pages
callback is invoked separately for each file.

The callback is not reentrant. The callback function should
not attempt to invoke any other SQLite interface.  If it does, bad
things may happen, including segmentation faults and corrupt database
files.  The callback function should be a simple function that
does some arithmetic on its input parameters and returns a result.

The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
destructor for the P parameter.  If X is not NULL, then X(P) is
invoked whenever the database connection closes or when the callback
is overwritten by another invocation of sqlite3_autovacuum_pages().

There is only one autovacuum pages callback per database connection.
Each call to the sqlite3_autovacuum_pages() interface overrides all
previous invocations for that database connection.  If the callback
argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
then the autovacuum steps callback is cancelled.  The return value
from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
be some other error code if something goes wrong.  The current
implementation will only return SQLITE_OK or SQLITE_MISUSE, but other
return codes might be added in future releases.

If no autovacuum pages callback is specified (the usual case) or
a NULL pointer is provided for the callback,
then the default behavior is to vacuum all free pages.  So, in other
words, the default behavior is the same as if the callback function
were something like this:


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_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: 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_vtab_cursor
c2: C API: Virtual Table Cursor Object
c5: c3ref/vtab_cursor.html
c4:
Every virtual table module implementation uses a subclass of the
following structure to describe cursors that point into the
virtual table and are used
to loop through the virtual table.  Cursors are created using the
xOpen method of the module and are destroyed
by the xClose method.  Cursors are used
by the xFilter, xNext, xEof, xColumn, and xRowid methods
of the module.  Each module implementation will define
the content of a cursor structure to suit its own needs.

This superclass exists in order to define fields of the cursor that
are common to all implementations.
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_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_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: sqlite3_strglob()
c2: C API: String Globbing
c5: c3ref/strglob.html
c4:
The sqlite3_strglob(P,X) interface returns zero if and only if
string X matches the GLOB pattern P.
The definition of GLOB pattern matching used in
sqlite3_strglob(P,X) is the same as for the "X GLOB P" operator in the
SQL dialect understood by SQLite.  The sqlite3_strglob(P,X) function
is case sensitive.

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_strlike().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_next_stmt()
c2: C API: Find the next prepared statement
c5: c3ref/next_stmt.html
c4:
This interface returns a pointer to the next prepared statement after
pStmt associated with the database connection pDb.  If pStmt is NULL
then this interface returns a pointer to the first prepared statement
associated with the database connection pDb.  If no prepared statement
satisfies the conditions of this routine, it returns NULL.

The database connection pointer D in a call to
sqlite3_next_stmt(D,S) must refer to an open database
connection and in particular must not be a NULL pointer.
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 implemention, 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.


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: sqlite3_str_new()
1 Destructor: sqlite3_str_finish()
9 Methods:


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.


c2: C API: Introduction
c5: c3ref/intro.html
c4:
C-language Interface Specification for SQLite


These pages are intended to be precise and detailed specification.
For a tutorial introduction, see instead:

SQLite In 5 Minutes Or Less and/or
the Introduction To The SQLite C/C++ Interface.

This same content is also available as a
single large HTML file.


The SQLite interface elements can be grouped into three categories:


List Of Objects.
    This is a list of all abstract objects and datatypes used by the
    SQLite library.  There are couple dozen objects in total, but
    the two most important objects are:
    A database connection object sqlite3, and the
    prepared statement object sqlite3_stmt.

List Of Constants.
    This is a list of numeric constants used by SQLite and represented by
    #defines in the sqlite3.h header file.  These constants
    are things such as numeric result codes from
    various interfaces (ex: SQLITE_OK) or flags passed
    into functions to control behavior
    (ex: SQLITE_OPEN_READONLY).

List Of Functions.
    This is a list of all functions and methods operating on the 
    objects and using and/or
    returning constants.  There
    are many functions, but most applications only use a handful.


c0: sqlite3_db_status()
c2: C API: Database Connection Status
c5: c3ref/db_status.html
c4:
This interface is used to retrieve runtime status information
about a single database connection.  The first argument is the
database connection object to be interrogated.  The second argument
is an integer constant, taken from the set of
SQLITE_DBSTATUS options, that
determines the parameter to interrogate.  The set of
SQLITE_DBSTATUS options is likely
to grow in future releases of SQLite.

The current value of the requested parameter is written into *pCur
and the highest instantaneous value is written into *pHiwtr.  If
the resetFlg is true, then the highest instantaneous value is
reset back down to the current value.

The sqlite3_db_status() routine returns SQLITE_OK on success and a
non-zero error code on failure.

See also: sqlite3_status() and sqlite3_stmt_status().
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_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_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_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.


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 passsed 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_log()
c2: C API: Error Logging Interface
c5: c3ref/log.html
c4:
The sqlite3_log() interface writes a message into the error log
established by the SQLITE_CONFIG_LOG option to sqlite3_config().
If logging is enabled, the zFormat string and subsequent arguments are
used with sqlite3_snprintf() to generate the final output string.

The sqlite3_log() interface is intended for use by extensions such as
virtual tables, collating functions, and SQL functions.  While there is
nothing to prevent an application from calling sqlite3_log(), doing so
is considered bad form.

The zFormat string must not be NULL.

To avoid deadlocks and other threading problems, the sqlite3_log() routine
will not use dynamically allocated memory.  The log message is stored in
a fixed-length buffer on the stack.  If the log message is longer than
a few hundred characters, it will be truncated to the length of the
buffer.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_keyword_count(), sqlite3_keyword_name(), sqlite3_keyword_check()
c2: C API: SQL Keyword Checking
c5: c3ref/keyword_check.html
c4:
These routines provide access to the set of SQL language keywords
recognized by SQLite.  Applications can uses these routines to determine
whether or not a specific identifier needs to be escaped (for example,
by enclosing in double-quotes) so as not to confuse the parser.

The sqlite3_keyword_count() interface returns the number of distinct
keywords understood by SQLite.

The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and
makes *Z point to that keyword expressed as UTF8 and writes the number
of bytes in the keyword into *L.  The string that *Z points to is not
zero-terminated.  The sqlite3_keyword_name(N,Z,L) routine returns
SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
or L are NULL or invalid pointers then calls to
sqlite3_keyword_name(N,Z,L) result in undefined behavior.

The sqlite3_keyword_check(Z,L) interface checks to see whether or not
the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
if it is and zero if not.

The parser used by SQLite is forgiving.  It is often possible to use
a keyword as an identifier as long as such use does not result in a
parsing ambiguity.  For example, the statement
"CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
creates a new table named "BEGIN" with three columns named
"REPLACE", "PRAGMA", and "END".  Nevertheless, best practice is to avoid
using keywords as identifiers.  Common techniques used to avoid keyword
name collisions include:

 Put all identifier names inside double-quotes.  This is the official
SQL way to escape identifier names.
 Put identifier names inside &#91;...&#93;.  This is not standard SQL,
but it is what SQL Server does and so lots of programmers use this
technique.
 Begin every identifier with the letter "Z" as no SQL keywords start
with "Z".
 Include a digit somewhere in every identifier name.


Note that the number of keywords understood by SQLite can depend on
compile-time options.  For example, "VACUUM" is not a keyword if
SQLite is compiled with the -DSQLITE_OMIT_VACUUM option.  Also,
new keywords may be added to future releases of SQLite.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_blob_open()
c2: C API: Open A BLOB For Incremental I/O
c5: c3ref/blob_open.html
c4:
This interfaces opens a handle to the BLOB located
in row iRow, column zColumn, table zTable in database zDb;
in other words, the same BLOB that would be selected by:


SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;


Parameter zDb is not the filename that contains the database, but
rather the symbolic name of the database. For attached databases, this is
the name that appears after the AS keyword in the ATTACH statement.
For the main database file, the database name is "main". For TEMP
tables, the database name is "temp".

If the flags parameter is non-zero, then the BLOB is opened for read
and write access. If the flags parameter is zero, the BLOB is opened for
read-only access.

On success, SQLITE_OK is returned and the new BLOB handle is stored
in *ppBlob. Otherwise an error code is returned and, unless the error
code is SQLITE_MISUSE, *ppBlob is set to NULL. This means that, provided
the API is not misused, it is always safe to call sqlite3_blob_close()
on *ppBlob after this function it returns.

This function fails with SQLITE_ERROR if any of the following are true:

 Database zDb does not exist,
 Table zTable does not exist within database zDb,
 Table zTable is a WITHOUT ROWID table,
 Column zColumn does not exist,
 Row iRow is not present in the table,
 The specified column of row iRow contains a value that is not
a TEXT or BLOB value,
 Column zColumn is part of an index, PRIMARY KEY or UNIQUE
constraint and the blob is being opened for read/write access,
 Foreign key constraints are enabled,
column zColumn is part of a child key definition and the blob is
being opened for read/write access.


Unless it returns SQLITE_MISUSE, this function sets the
database connection error code and message accessible via
sqlite3_errcode() and sqlite3_errmsg() and related functions.

A BLOB referenced by sqlite3_blob_open() may be read using the
sqlite3_blob_read() interface and modified by using
sqlite3_blob_write().  The BLOB handle can be moved to a
different row of the same table using the sqlite3_blob_reopen()
interface.  However, the column, table, or database of a BLOB handle
cannot be changed after the BLOB handle is opened.

If the row that a BLOB handle points to is modified by an
UPDATE, DELETE, or by ON CONFLICT side-effects
then the BLOB handle is marked as "expired".
This is true if any column of the row is changed, even a column
other than the one the BLOB handle is open on.
Calls to sqlite3_blob_read() and sqlite3_blob_write() for
an expired BLOB handle fail with a return code of SQLITE_ABORT.
Changes written into a BLOB prior to the BLOB expiring are not
rolled back by the expiration of the BLOB.  Such changes will eventually
commit if the transaction continues to completion.

Use the sqlite3_blob_bytes() interface to determine the size of
the opened blob.  The size of a blob may not be changed by this
interface.  Use the UPDATE SQL command to change the size of a
blob.

The sqlite3_bind_zeroblob() and sqlite3_result_zeroblob() interfaces
and the built-in zeroblob SQL function may be used to create a
zero-filled blob to read or write using the incremental-blob interface.

To avoid a resource leak, every open BLOB handle should eventually
be released by a call to sqlite3_blob_close().

See also: sqlite3_blob_close(),
sqlite3_blob_reopen(), sqlite3_blob_read(),
sqlite3_blob_bytes(), sqlite3_blob_write().
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

c4:
These constants are the available integer configuration options that
can be passed as the first argument to the sqlite3_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_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 behaviour.
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.

See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_bind_parameter_name()
c2: C API: Name Of A Host Parameter
c5: c3ref/bind_parameter_name.html
c4:
The sqlite3_bind_parameter_name(P,N) interface returns
the name of the N-th SQL parameter in the prepared statement P.
SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
respectively.
In other words, the initial ":" or "$" or "@" or "?"
is included as part of the name.
Parameters of the form "?" without a following integer have no name
and are referred to as "nameless" or "anonymous parameters".

The first host parameter has an index of 1, not 0.

If the value N is out of range or if the N-th parameter is
nameless, then NULL is returned.  The returned string is
always in UTF-8 encoding even if the named parameter was
originally specified as UTF-16 in sqlite3_prepare16(),
sqlite3_prepare16_v2(), or sqlite3_prepare16_v3().

See also: sqlite3_bind(),
sqlite3_bind_parameter_count(), and
sqlite3_bind_parameter_index().
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.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Result Codes
c5: c3ref/c_abort.html
c0:
sqlite3_interrupt(), sqlite3_file_control(), SQLITE_OK, SQLITE_ERROR, SQLITE_INTERNAL, SQLITE_PERM, SQLITE_BUSY, SQLITE_LOCKED, SQLITE_NOMEM, SQLITE_READONLY, SQLITE_INTERRUPT, SQLITE_IOERR, SQLITE_CORRUPT, SQLITE_NOTFOUND, SQLITE_FULL, SQLITE_CANTOPEN, SQLITE_PROTOCOL, SQLITE_EMPTY, SQLITE_SCHEMA, SQLITE_TOOBIG, SQLITE_CONSTRAINT, SQLITE_MISMATCH, SQLITE_MISUSE, SQLITE_NOLFS, SQLITE_AUTH, SQLITE_FORMAT, SQLITE_RANGE, SQLITE_NOTADB, SQLITE_NOTICE, SQLITE_WARNING, SQLITE_ROW, SQLITE_DONE

c4:
Many SQLite functions return an integer result code from the set shown
here in order to indicate success or failure.

New error codes may be added in future versions of SQLite.

See also: extended result code definitions
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:


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.


c0: SQLITE_SYNC_NORMAL, SQLITE_SYNC_FULL, SQLITE_SYNC_DATAONLY
c2: C API: Synchronization Type Flags
c5: c3ref/c_sync_dataonly.html
c4:
When SQLite invokes the xSync() method of an
sqlite3_io_methods object it uses a combination of
these integer values as the second argument.

When the SQLITE_SYNC_DATAONLY flag is used, it means that the
sync operation only needs to flush data to mass storage.  Inode
information need not be flushed. If the lower four bits of the flag
equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
If the lower four bits equal SQLITE_SYNC_FULL, that means
to use Mac OS X style fullsync instead of fsync().

Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
with the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL
settings.  The synchronous pragma determines when calls to the
xSync VFS method occur and applies uniformly across all platforms.
The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
energetic or rigorous or forceful the sync operations are and
only make a difference on Mac OSX for the default SQLite code.
(Third-party VFS implementations might also make the distinction
between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
operating systems natively supported by SQLite, only Mac OSX
cares about the difference.)
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Mutex Types
c5: c3ref/c_mutex_fast.html
c0:
sqlite3_randomness(), 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_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_user_data()
c2: C API: User Data For Functions
c5: c3ref/user_data.html
c4:
The sqlite3_user_data() interface returns a copy of
the pointer that was the pUserData parameter (the 5th parameter)
of the sqlite3_create_function()
and sqlite3_create_function16() routines that originally
registered the application defined function.

This routine must be called from the same thread in which
the application-defined function is running.
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: sqlite3_drop_modules()
c2: C API: Remove Unnecessary Virtual Table Implementations
c5: c3ref/drop_modules.html
c4:
The sqlite3_drop_modules(D,L) interface removes all virtual
table modules from database connection D except those named on list L.
The L parameter must be either NULL or a pointer to an array of pointers
to strings where the array is terminated by a single NULL pointer.
If the L parameter is NULL, then all virtual table modules are removed.

See also: sqlite3_create_module()
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_blob_bytes()
c2: C API: Return The Size Of An Open BLOB
c5: c3ref/blob_bytes.html
c4:
Returns the size in bytes of the BLOB accessible via the
successfully opened BLOB handle in its only argument.  The
incremental blob I/O routines can only read or overwriting existing
blob content; they cannot change the size of a blob.

This routine only works on a BLOB handle which has been created
by a prior successful call to sqlite3_blob_open() and which has not
been closed by sqlite3_blob_close().  Passing any other pointer in
to this routine results in undefined and probably undesirable behavior.
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: SQLITE_TXN_NONE, SQLITE_TXN_READ, SQLITE_TXN_WRITE
c2: C API: Allowed return values from [sqlite3_txn_state()]
c5: c3ref/c_txn_none.html
c4:
These constants define the current transaction state of a database file.
The sqlite3_txn_state(D,S) interface returns one of these
constants in order to describe the transaction state of schema S
in database connection D.



 SQLITE_TXN_NONE
The SQLITE_TXN_NONE state means that no transaction is currently
pending.


 SQLITE_TXN_READ
The SQLITE_TXN_READ state means that the database is currently
in a read transaction.  Content has been read from the database file
but nothing in the database file has changed.  The transaction state
will advanced to SQLITE_TXN_WRITE if any changes occur and there are
no other conflicting concurrent write transactions.  The transaction
state will revert to SQLITE_TXN_NONE following a ROLLBACK or
COMMIT.


 SQLITE_TXN_WRITE
The SQLITE_TXN_WRITE state means that the database is currently
in a write transaction.  Content has been written to the database file
but has not yet committed.  The transaction state will change to
to SQLITE_TXN_NONE at the next ROLLBACK or COMMIT.
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.


c2: C API: Device Characteristics
c5: c3ref/c_iocap_atomic.html
c0:
SQLITE_IOCAP_ATOMIC, SQLITE_IOCAP_ATOMIC512, SQLITE_IOCAP_ATOMIC1K, SQLITE_IOCAP_ATOMIC2K, SQLITE_IOCAP_ATOMIC4K, SQLITE_IOCAP_ATOMIC8K, SQLITE_IOCAP_ATOMIC16K, SQLITE_IOCAP_ATOMIC32K, SQLITE_IOCAP_ATOMIC64K, SQLITE_IOCAP_SAFE_APPEND, SQLITE_IOCAP_SEQUENTIAL, SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN, SQLITE_IOCAP_POWERSAFE_OVERWRITE, SQLITE_IOCAP_IMMUTABLE, SQLITE_IOCAP_BATCH_ATOMIC

c4:
The xDeviceCharacteristics method of the sqlite3_io_methods
object returns an integer which is a vector of these
bit values expressing I/O characteristics of the mass storage
device that holds the file that the sqlite3_io_methods
refers to.

The SQLITE_IOCAP_ATOMIC property means that all writes of
any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
mean that writes of blocks that are nnn bytes in size and
are aligned to an address which is an integer multiple of
nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
that when data is appended to a file, the data is appended
first then the size of the file is extended, never the other
way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
information is written to disk in the same order as calls
to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
after reboot following a crash or power loss, the only bytes in a
file that were written at the application level might have changed
and that adjacent bytes, even bytes within the same sector are
guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
flag indicates that a file cannot be deleted when open.  The
SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
read-only media and cannot be changed even by processes with
elevated privileges.

The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
filesystem supports doing multiple write operations atomically when those
write operations are bracketed by SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and
SQLITE_FCNTL_COMMIT_ATOMIC_WRITE.
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.


c0: sqlite3_db_readonly()
c2: C API: Determine if a database is read-only
c5: c3ref/db_readonly.html
c4:
The sqlite3_db_readonly(D,N) interface returns 1 if the database N
of connection D is read-only, 0 if it is read/write, or -1 if N is not
the name of a database on connection D.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_cacheflush()
c2: C API: Flush caches to disk mid-transaction
c5: c3ref/db_cacheflush.html
c4:
If a write-transaction is open on database connection D when the
sqlite3_db_cacheflush(D) interface invoked, any dirty
pages in the pager-cache that are not currently in use are written out
to disk. A dirty page may be in use if a database cursor created by an
active SQL statement is reading from it, or if it is page 1 of a database
file (page 1 is always "in use").  The sqlite3_db_cacheflush(D)
interface flushes caches for all schemas - "main", "temp", and
any attached databases.

If this function needs to obtain extra database locks before dirty pages
can be flushed to disk, it does so. If those locks cannot be obtained
immediately and there is a busy-handler callback configured, it is invoked
in the usual manner. If the required lock still cannot be obtained, then
the database is skipped and an attempt made to flush any dirty pages
belonging to the next (if any) database. If any databases are skipped
because locks cannot be obtained, but no other error occurs, this
function returns SQLITE_BUSY.

If any other error occurs while flushing dirty pages to disk (for
example an IO error or out-of-memory condition), then processing is
abandoned and an SQLite error code is returned to the caller immediately.

Otherwise, if no error occurs, sqlite3_db_cacheflush() returns SQLITE_OK.

This function does not set the database handle error code or message
returned by the sqlite3_errcode() and sqlite3_errmsg() functions.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_database_file_object()
c2: C API: Database File Corresponding To A Journal
c5: c3ref/database_file_object.html
c4:
If X is the name of a rollback or WAL-mode journal file that is
passed into the xOpen method of sqlite3_vfs, then
sqlite3_database_file_object(X) returns a pointer to the sqlite3_file
object that represents the main database file.

This routine is intended for use in custom VFS implementations
only.  It is not a general-purpose interface.
The argument sqlite3_file_object(X) must be a filename pointer that
has been passed into sqlite3_vfs.xOpen method where the
flags parameter to xOpen contains one of the bits
SQLITE_OPEN_MAIN_JOURNAL or SQLITE_OPEN_WAL.  Any other use
of this routine results in undefined and probably undesirable
behavior.
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.
18 Methods:


sqlite3_value_blob
sqlite3_value_bytes
sqlite3_value_bytes16
sqlite3_value_double
sqlite3_value_dup
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: 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: 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_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_declare_vtab()
c2: C API: Declare The Schema Of A Virtual Table
c5: c3ref/declare_vtab.html
c4:
The xCreate and xConnect methods of a
virtual table module call this interface
to declare the format (the names and datatypes of the columns) of
the virtual tables they implement.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_auto_extension()
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: 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: sqlite3_get_autocommit()
c2: C API: Test For Auto-Commit Mode
c5: c3ref/get_autocommit.html
c4:
The sqlite3_get_autocommit() interface returns non-zero or
zero if the given database connection is or is not in autocommit mode,
respectively.  Autocommit mode is on by default.
Autocommit mode is disabled by a BEGIN statement.
Autocommit mode is re-enabled by a COMMIT or ROLLBACK.

If certain kinds of errors occur on a statement within a multi-statement
transaction (errors including SQLITE_FULL, SQLITE_IOERR,
SQLITE_NOMEM, SQLITE_BUSY, and SQLITE_INTERRUPT) then the
transaction might be rolled back automatically.  The only way to
find out whether SQLite automatically rolled back the transaction after
an error is to use this function.

If another thread changes the autocommit status of the database
connection while this routine is running, then the return value
is undefined.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: File Locking Levels
c5: c3ref/c_lock_exclusive.html
c0:
SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, SQLITE_LOCK_EXCLUSIVE

c4:
SQLite uses one of these integer values as the second
argument to calls it makes to the xLock() and xUnlock() methods
of an sqlite3_io_methods object.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_load_extension()
c2: C API: Load An Extension
c5: c3ref/load_extension.html
c4:
This interface loads an SQLite extension library from the named file.

The sqlite3_load_extension() interface attempts to load an
SQLite extension library contained in the file zFile.  If
the file cannot be loaded directly, attempts are made to load
with various operating-system specific extensions added.
So for example, if "samplelib" cannot be loaded, then names like
"samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
be tried also.

The entry point is zProc.
zProc may be 0, in which case SQLite will try to come up with an
entry point name on its own.  It first tries "sqlite3_extension_init".
If that does not work, it constructs a name "sqlite3_X_init" where the
X is consists of the lower-case equivalent of all ASCII alphabetic
characters in the filename from the last "/" to the first following
"." and omitting any initial "lib".
The sqlite3_load_extension() interface returns
SQLITE_OK on success and SQLITE_ERROR if something goes wrong.
If an error occurs and pzErrMsg is not 0, then the
sqlite3_load_extension() interface shall attempt to
fill *pzErrMsg with error message text stored in memory
obtained from sqlite3_malloc(). The calling function
should free this memory by calling sqlite3_free().

Extension loading must be enabled using
sqlite3_enable_load_extension() or
sqlite3_db_config(db,SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL)
prior to calling this API,
otherwise an error will be returned.

Security warning: It is recommended that the
SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION method be used to enable only this
interface.  The use of the sqlite3_enable_load_extension() interface
should be avoided.  This will keep the SQL function load_extension()
disabled and prevent SQL injections from giving attackers
access to extension loading capabilities.

See also the load_extension() SQL function.
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.


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: SQLITE_ACCESS_EXISTS, SQLITE_ACCESS_READWRITE, SQLITE_ACCESS_READ
c2: C API: Flags for the xAccess VFS method
c5: c3ref/c_access_exists.html
c4:
These integer constants can be used as the third parameter to
the xAccess method of an sqlite3_vfs object.  They determine
what kind of permissions the xAccess method is looking for.
With SQLITE_ACCESS_EXISTS, the xAccess method
simply checks whether the file exists.
With SQLITE_ACCESS_READWRITE, the xAccess method
checks whether the named directory is both readable and writable
(in other words, if files can be added, removed, and renamed within
the directory).
The SQLITE_ACCESS_READWRITE constant is currently used only by the
temp_store_directory pragma, though this could change in a future
release of SQLite.
With SQLITE_ACCESS_READ, the xAccess method
checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
currently unused, though it might be used in a future release of
SQLite.
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_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_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_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.


c0: SQLITE_DESERIALIZE_FREEONCLOSE, SQLITE_DESERIALIZE_RESIZEABLE, SQLITE_DESERIALIZE_READONLY
c2: C API: Flags for sqlite3_deserialize()
c5: c3ref/c_deserialize_freeonclose.html
c4:
The following are allowed values for 6th argument (the F argument) to
the sqlite3_deserialize(D,S,P,N,M,F) interface.

The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
in the P argument is held in memory obtained from sqlite3_malloc64()
and that SQLite should take ownership of this memory and automatically
free it when it has finished using it.  Without this flag, the caller
is responsible for freeing any dynamically allocated memory.

The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
grow the size of the database using calls to sqlite3_realloc64().  This
flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
Without this flag, the deserialized database cannot increase in size beyond
the number of bytes specified by the M parameter.

The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
should be treated as read-only.
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.


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 no commonly needed.
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.


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: sqlite3_vtab_nochange()
c2: C API: Determine If Virtual Table Column Access Is For UPDATE
c5: c3ref/vtab_nochange.html
c4:
If the sqlite3_vtab_nochange(X) routine is called within the xColumn
method of a virtual table, then it might return true if the
column is being fetched as part of an UPDATE operation during which the
column value will not change.  The virtual table implementation can use
this hint as permission to substitute a return value that is less
expensive to compute and that the corresponding
xUpdate method understands as a "no-change" value.

If the xColumn method calls sqlite3_vtab_nochange() and finds that
the column is not changed by the UPDATE statement, then the xColumn
method can optionally return without setting a result, without calling
any of the sqlite3_result_xxxxx() interfaces.
In that case, sqlite3_value_nochange(X) will return true for the
same column in the xUpdate method.

The sqlite3_vtab_nochange() routine is an optimization.  Virtual table
implementations should continue to give a correct answer even if the
sqlite3_vtab_nochange() interface were to always return false.  In the
current implementation, the sqlite3_vtab_nochange() interface does always
returns false for the enhanced UPDATE FROM statement.
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: sqlite3_threadsafe()
c2: C API: Test To See If The Library Is Threadsafe
c5: c3ref/threadsafe.html
c4:
The sqlite3_threadsafe() function returns zero if and only if
SQLite was compiled with mutexing code omitted due to the
SQLITE_THREADSAFE compile-time option being set to 0.

SQLite can be compiled with or without mutexes.  When
the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes
are enabled and SQLite is threadsafe.  When the
SQLITE_THREADSAFE macro is 0,
the mutexes are omitted.  Without the mutexes, it is not safe
to use SQLite concurrently from more than one thread.

Enabling mutexes incurs a measurable performance penalty.
So if speed is of utmost importance, it makes sense to disable
the mutexes.  But for maximum safety, mutexes should be enabled.
The default behavior is for mutexes to be enabled.

This interface can be used by an application to make sure that the
version of SQLite that it is linking against was compiled with
the desired setting of the SQLITE_THREADSAFE macro.

This interface only reports on the compile-time mutex setting
of the SQLITE_THREADSAFE flag.  If SQLite is compiled with
SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
can be fully or partially disabled using a call to sqlite3_config()
with the verbs SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD,
or SQLITE_CONFIG_SERIALIZED.  The return value of the
sqlite3_threadsafe() function shows only the compile-time setting of
thread safety, not any run-time changes to that setting made by
sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
is unchanged by calls to sqlite3_config().

See the threading mode documentation for additional information.
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_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_snapshot_free()
c2: C API: Destroy a snapshot
c5: c3ref/snapshot_free.html
c4:
The sqlite3_snapshot_free(P) interface destroys sqlite3_snapshot P.
The application must eventually free every sqlite3_snapshot object
using this routine to avoid a memory leak.

The sqlite3_snapshot_free() 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_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: struct sqlite3_snapshot
c2: C API: Database Snapshot
c5: c3ref/snapshot.html
c4:
An instance of the snapshot object records the state of a WAL mode
database for some specific point in history.

In WAL mode, multiple database connections that are open on the
same database file can each be reading a different historical version
of the database file.  When a database connection begins a read
transaction, that connection sees an unchanging copy of the database
as it existed for the point in time when the transaction first started.
Subsequent changes to the database from other connections are not seen
by the reader until a new read transaction is started.

The sqlite3_snapshot object records state information about an historical
version of the database file so that it is possible to later open a new read
transaction that sees that historical version of the database rather than
the most recent version.
1 Constructor: sqlite3_snapshot_get()
1 Destructor: sqlite3_snapshot_free()
3 Methods:
 sqlite3_snapshot_cmp(),
sqlite3_snapshot_open(),
sqlite3_snapshot_recover()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_close(), sqlite3_close_v2()
c2: C API: Closing A Database Connection
c5: c3ref/close.html
c4:
The sqlite3_close() and sqlite3_close_v2() routines are destructors
for the sqlite3 object.
Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
the sqlite3 object is successfully destroyed and all associated
resources are deallocated.

Ideally, applications should finalize all
prepared statements, close all BLOB handles, and
finish all sqlite3_backup objects associated
with the sqlite3 object prior to attempting to close the object.
If the database connection is associated with unfinalized prepared
statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
sqlite3_close() will leave the database connection open and return
SQLITE_BUSY. If sqlite3_close_v2() is called with unfinalized prepared
statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
it returns SQLITE_OK regardless, but instead of deallocating the database
connection immediately, it marks the database connection as an unusable
"zombie" and makes arrangements to automatically deallocate the database
connection after all prepared statements are finalized, all BLOB handles
are closed, and all backups have finished. The sqlite3_close_v2() interface
is intended for use with host languages that are garbage collected, and
where the order in which destructors are called is arbitrary.

If an sqlite3 object is destroyed while a transaction is open,
the transaction is automatically rolled back.

The C parameter to sqlite3_close(C) and sqlite3_close_v2(C)
must be either a NULL
pointer or an sqlite3 object pointer obtained
from sqlite3_open(), sqlite3_open16(), or
sqlite3_open_v2(), and not previously closed.
Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
argument is a harmless no-op.
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.
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() interface returns the English-language text
that describes the result code, as UTF-8.
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.


c0: sqlite3_vtab_on_conflict()
c2: C API: Determine The Virtual Table Conflict Policy
c5: c3ref/vtab_on_conflict.html
c4:
This function may only be called from within a call to the xUpdate method
of a virtual table implementation for an INSERT or UPDATE operation. The
value returned is one of SQLITE_ROLLBACK, SQLITE_IGNORE, SQLITE_FAIL,
SQLITE_ABORT, or SQLITE_REPLACE, according to the ON CONFLICT mode
of the SQL statement that triggered the call to the xUpdate method of the
virtual table.
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_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.


c2: C API: Checkpoint Mode Values
c5: c3ref/c_checkpoint_full.html
c0:
SQLITE_CHECKPOINT_PASSIVE, SQLITE_CHECKPOINT_FULL, SQLITE_CHECKPOINT_RESTART, SQLITE_CHECKPOINT_TRUNCATE

c4:
These constants define all valid values for the "checkpoint mode" passed
as the third parameter to the sqlite3_wal_checkpoint_v2() interface.
See the sqlite3_wal_checkpoint_v2() documentation for details on the
meaning of each of these checkpoint modes.
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() or sqlite3_trace_v2() overrides
(cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().

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_wal_autocheckpoint()
c2: C API: Configure an auto-checkpoint
c5: c3ref/wal_autocheckpoint.html
c4:
The sqlite3_wal_autocheckpoint(D,N) is a wrapper around
sqlite3_wal_hook() that causes any database on database connection D
to automatically checkpoint
after committing a transaction if there are N or
more frames in the write-ahead log file.  Passing zero or
a negative value as the nFrame parameter disables automatic
checkpoints entirely.

The callback registered by this function replaces any existing callback
registered using sqlite3_wal_hook().  Likewise, registering a callback
using sqlite3_wal_hook() disables the automatic checkpoint mechanism
configured by this function.

The wal_autocheckpoint pragma can be used to invoke this interface
from SQL.

Checkpoints initiated by this mechanism are
PASSIVE.

Every new database connection defaults to having the auto-checkpoint
enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
pages.  The use of this interface
is only necessary if the default setting is found to be suboptimal
for a particular application.
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:
 sqlite3_open(),
sqlite3_open16(),
sqlite3_open_v2()
2 Destructors:
 sqlite3_close(),
sqlite3_close_v2()
76 Methods:


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_table
sqlite3_interrupt
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_profile
sqlite3_progress_handler
sqlite3_rollback_hook
sqlite3_set_authorizer
sqlite3_set_last_insert_rowid
sqlite3_system_errno
sqlite3_table_column_metadata
sqlite3_total_changes
sqlite3_total_changes64
sqlite3_trace
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_complete(), sqlite3_complete16()
c2: C API: Determine If An SQL Statement Is Complete
c5: c3ref/complete.html
c4:
These routines are useful during command-line input to determine if the
currently entered text seems to form a complete SQL statement or
if additional input is needed before sending the text into
SQLite for parsing.  These routines return 1 if the input string
appears to be a complete SQL statement.  A statement is judged to be
complete if it ends with a semicolon token and is not a prefix of a
well-formed CREATE TRIGGER statement.  Semicolons that are embedded within
string literals or quoted identifier names or comments are not
independent tokens (they are part of the token in which they are
embedded) and thus do not count as a statement terminator.  Whitespace
and comments that follow the final semicolon are ignored.

These routines return 0 if the statement is incomplete.  If a
memory allocation fails, then SQLITE_NOMEM is returned.

These routines do not parse the SQL statements thus
will not detect syntactically incorrect SQL.

If SQLite has not been initialized using sqlite3_initialize() prior
to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
automatically by sqlite3_complete16().  If that initialization fails,
then the return value from sqlite3_complete16() will be non-zero
regardless of whether or not the input SQL is complete.

The input to sqlite3_complete() must be a zero-terminated
UTF-8 string.

The input to sqlite3_complete16() must be a zero-terminated
UTF-16 string in native byte order.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Extended Result Codes
c5: c3ref/c_abort_rollback.html
c0:
SQLITE_ERROR_MISSING_COLLSEQ, SQLITE_ERROR_RETRY, SQLITE_ERROR_SNAPSHOT, SQLITE_IOERR_READ, SQLITE_IOERR_SHORT_READ, SQLITE_IOERR_WRITE, SQLITE_IOERR_FSYNC, SQLITE_IOERR_DIR_FSYNC, SQLITE_IOERR_TRUNCATE, SQLITE_IOERR_FSTAT, SQLITE_IOERR_UNLOCK, SQLITE_IOERR_RDLOCK, SQLITE_IOERR_DELETE, SQLITE_IOERR_BLOCKED, SQLITE_IOERR_NOMEM, SQLITE_IOERR_ACCESS, SQLITE_IOERR_CHECKRESERVEDLOCK, SQLITE_IOERR_LOCK, SQLITE_IOERR_CLOSE, SQLITE_IOERR_DIR_CLOSE, SQLITE_IOERR_SHMOPEN, SQLITE_IOERR_SHMSIZE, SQLITE_IOERR_SHMLOCK, SQLITE_IOERR_SHMMAP, SQLITE_IOERR_SEEK, SQLITE_IOERR_DELETE_NOENT, SQLITE_IOERR_MMAP, SQLITE_IOERR_GETTEMPPATH, SQLITE_IOERR_CONVPATH, SQLITE_IOERR_VNODE, SQLITE_IOERR_AUTH, SQLITE_IOERR_BEGIN_ATOMIC, SQLITE_IOERR_COMMIT_ATOMIC, SQLITE_IOERR_ROLLBACK_ATOMIC, SQLITE_IOERR_DATA, SQLITE_IOERR_CORRUPTFS, SQLITE_LOCKED_SHAREDCACHE, SQLITE_LOCKED_VTAB, SQLITE_BUSY_RECOVERY, SQLITE_BUSY_SNAPSHOT, SQLITE_BUSY_TIMEOUT, SQLITE_CANTOPEN_NOTEMPDIR, SQLITE_CANTOPEN_ISDIR, SQLITE_CANTOPEN_FULLPATH, SQLITE_CANTOPEN_CONVPATH, SQLITE_CANTOPEN_DIRTYWAL, SQLITE_CANTOPEN_SYMLINK, SQLITE_CORRUPT_VTAB, SQLITE_CORRUPT_SEQUENCE, SQLITE_CORRUPT_INDEX, SQLITE_READONLY_RECOVERY, SQLITE_READONLY_CANTLOCK, SQLITE_READONLY_ROLLBACK, SQLITE_READONLY_DBMOVED, SQLITE_READONLY_CANTINIT, SQLITE_READONLY_DIRECTORY, SQLITE_ABORT_ROLLBACK, SQLITE_CONSTRAINT_CHECK, SQLITE_CONSTRAINT_COMMITHOOK, SQLITE_CONSTRAINT_FOREIGNKEY, SQLITE_CONSTRAINT_FUNCTION, SQLITE_CONSTRAINT_NOTNULL, SQLITE_CONSTRAINT_PRIMARYKEY, SQLITE_CONSTRAINT_TRIGGER, SQLITE_CONSTRAINT_UNIQUE, SQLITE_CONSTRAINT_VTAB, SQLITE_CONSTRAINT_ROWID, SQLITE_CONSTRAINT_PINNED, SQLITE_CONSTRAINT_DATATYPE, SQLITE_NOTICE_RECOVER_WAL, SQLITE_NOTICE_RECOVER_ROLLBACK, SQLITE_WARNING_AUTOINDEX, SQLITE_AUTH_USER, SQLITE_OK_LOAD_PERMANENTLY, SQLITE_OK_SYMLINK

c4:
In its default configuration, SQLite API routines return one of 30 integer
result codes.  However, experience has shown that many of
these result codes are too coarse-grained.  They do not provide as
much information about problems as programmers might like.  In an effort to
address this, newer versions of SQLite (version 3.3.8 2006-10-09
and later) include
support for additional result codes that provide more detailed information
about errors. These extended result codes are enabled or disabled
on a per database connection basis using the
sqlite3_extended_result_codes() API.  Or, the extended code for
the most recent error can be obtained using
sqlite3_extended_errcode().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_filename()
c2: C API: Return The Filename For A Database Connection
c5: c3ref/db_filename.html
c4:
The sqlite3_db_filename(D,N) interface returns a pointer to the filename
associated with database N of connection D.
If there is no attached database N on the database
connection D, or if database N is a temporary or in-memory database, then
this function will return either a NULL pointer or an empty string.

The string value returned by this routine is owned and managed by
the database connection.  The value will be valid until the database N
is DETACH-ed or until the database connection closes.

The filename returned by this function is the output of the
xFullPathname method of the VFS.  In other words, the filename
will be an absolute pathname, even if the filename used
to open the database originally was a URI or relative pathname.

If the filename pointer returned by this routine is not NULL, then it
can be used as the filename input parameter to these routines:

 sqlite3_uri_parameter()
 sqlite3_uri_boolean()
 sqlite3_uri_int64()
 sqlite3_filename_database()
 sqlite3_filename_journal()
 sqlite3_filename_wal()

See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Mutexes
c5: c3ref/mutex_alloc.html
c0:
sqlite3_mutex_alloc(), sqlite3_mutex_free(), sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave()

c4:
The SQLite core uses these routines for thread
synchronization. Though they are intended for internal
use by SQLite, code that links against SQLite is
permitted to use any of these routines.

The SQLite source code contains multiple implementations
of these mutex routines.  An appropriate implementation
is selected automatically at compile-time.  The following
implementations are available in the SQLite core:


   SQLITE_MUTEX_PTHREADS
   SQLITE_MUTEX_W32
   SQLITE_MUTEX_NOOP


The SQLITE_MUTEX_NOOP implementation is a set of routines
that does no real locking and is appropriate for use in
a single-threaded application.  The SQLITE_MUTEX_PTHREADS and
SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
and Windows.

If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
implementation is included with the library. In this case the
application must supply a custom mutex implementation using the
SQLITE_CONFIG_MUTEX option of the sqlite3_config() function
before calling sqlite3_initialize() or any other public sqlite3_
function that calls sqlite3_initialize().

The sqlite3_mutex_alloc() routine allocates a new
mutex and returns a pointer to it. The sqlite3_mutex_alloc()
routine returns NULL if it is unable to allocate the requested
mutex.  The argument to sqlite3_mutex_alloc() must one of these
integer constants:


  SQLITE_MUTEX_FAST
  SQLITE_MUTEX_RECURSIVE
  SQLITE_MUTEX_STATIC_MAIN
  SQLITE_MUTEX_STATIC_MEM
  SQLITE_MUTEX_STATIC_OPEN
  SQLITE_MUTEX_STATIC_PRNG
  SQLITE_MUTEX_STATIC_LRU
  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


The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
cause sqlite3_mutex_alloc() to create
a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
is used but not necessarily so when SQLITE_MUTEX_FAST is used.
The mutex implementation does not need to make a distinction
between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
not want to.  SQLite will only request a recursive mutex in
cases where it really needs one.  If a faster non-recursive mutex
implementation is available on the host platform, the mutex subsystem
might return such a mutex in response to SQLITE_MUTEX_FAST.

The other allowed parameters to sqlite3_mutex_alloc() (anything other
than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
a pointer to a static preexisting mutex.  Nine static mutexes are
used by the current version of SQLite.  Future versions of SQLite
may add additional static mutexes.  Static mutexes are for internal
use by SQLite only.  Applications that use SQLite mutexes should
use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
SQLITE_MUTEX_RECURSIVE.

Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
returns a different mutex on every call.  For the static
mutex types, the same mutex is returned on every call that has
the same type number.

The sqlite3_mutex_free() routine deallocates a previously
allocated dynamic mutex.  Attempting to deallocate a static
mutex results in undefined behavior.

The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
to enter a mutex.  If another thread is already within the mutex,
sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
upon successful entry.  Mutexes created using
SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
In such cases, the
mutex must be exited an equal number of times before another thread
can enter.  If the same thread tries to enter any mutex other
than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.

Some systems (for example, Windows 95) do not support the operation
implemented by sqlite3_mutex_try().  On those systems, sqlite3_mutex_try()
will always return SQLITE_BUSY. The SQLite core only ever uses
sqlite3_mutex_try() as an optimization so this is acceptable
behavior.

The sqlite3_mutex_leave() routine exits a mutex that was
previously entered by the same thread.   The behavior
is undefined if the mutex is not currently entered by the
calling thread or is not currently allocated.

If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
sqlite3_mutex_leave() is a NULL pointer, then all three routines
behave as no-ops.

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


c0: sqlite3_column_name(), sqlite3_column_name16()
c2: C API: Column Names In A Result Set
c5: c3ref/column_name.html
c4:
These routines return the name assigned to a particular column
in the result set of a SELECT statement.  The sqlite3_column_name()
interface returns a pointer to a zero-terminated UTF-8 string
and sqlite3_column_name16() returns a pointer to a zero-terminated
UTF-16 string.  The first parameter is the prepared statement
that implements the SELECT statement. The second parameter is the
column number.  The leftmost column is number 0.

The returned string pointer is valid until either the prepared statement
is destroyed by sqlite3_finalize() or until the statement is automatically
reprepared by the first call to sqlite3_step() for a particular run
or until the next call to
sqlite3_column_name() or sqlite3_column_name16() on the same column.

If sqlite3_malloc() fails during the processing of either routine
(for example during a conversion from UTF-8 to UTF-16) then a
NULL pointer is returned.

The name of a result column is the value of the "AS" clause for
that column, if there is an AS clause.  If there is no AS clause
then the name of the column is unspecified and may change from
one release of SQLite to the next.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Flags For File Open Operations
c5: c3ref/c_open_autoproxy.html
c0:
SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_DELETEONCLOSE, SQLITE_OPEN_EXCLUSIVE, SQLITE_OPEN_AUTOPROXY, SQLITE_OPEN_URI, SQLITE_OPEN_MEMORY, SQLITE_OPEN_MAIN_DB, SQLITE_OPEN_TEMP_DB, SQLITE_OPEN_TRANSIENT_DB, SQLITE_OPEN_MAIN_JOURNAL, SQLITE_OPEN_TEMP_JOURNAL, SQLITE_OPEN_SUBJOURNAL, SQLITE_OPEN_SUPER_JOURNAL, SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, SQLITE_OPEN_PRIVATECACHE, SQLITE_OPEN_WAL, SQLITE_OPEN_NOFOLLOW, SQLITE_OPEN_EXRESCODE

c4:
These bit values are intended for use in the
3rd parameter to the sqlite3_open_v2() interface and
in the 4th parameter to the sqlite3_vfs.xOpen method.

Only those flags marked as "Ok for sqlite3_open_v2()" may be
used as the third argument to the sqlite3_open_v2() interface.
The other flags have historically been ignored by sqlite3_open_v2(),
though future versions of SQLite might change so that an error is
raised if any of the disallowed bits are passed into sqlite3_open_v2().
Applications should not depend on the historical behavior.

Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
sqlite3_open_v2() does *not* cause the underlying database file
to be opened using O_EXCL.  Passing SQLITE_OPEN_EXCLUSIVE into
sqlite3_open_v2() has historically be a no-op and might become an
error in future versions of SQLite.
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: 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_clear_bindings()
c2: C API: Reset All Bindings On A Prepared Statement
c5: c3ref/clear_bindings.html
c4:
Contrary to the intuition of many, sqlite3_reset() does not reset
the bindings on a prepared statement.
Use this routine to reset all host parameters to NULL.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_result_subtype()
c2: C API: Setting The Subtype Of An SQL Function
c5: c3ref/result_subtype.html
c4:
The sqlite3_result_subtype(C,T) function causes the subtype of
the result from the application-defined SQL function with
sqlite3_context C to be the value T.  Only the lower 8 bits
of the subtype T are preserved in current versions of SQLite;
higher order bits are discarded.
The number of subtype bytes preserved by SQLite might increase
in future releases of SQLite.
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 idxPtr values are recorded and passed into the
xFilter method.
sqlite3_free() is used to free idxPtr if and only if
needToFreeIdxPtr 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:
 sqlite3_vtab_collation(),
sqlite3_vtab_distinct(),
sqlite3_vtab_rhs_value()
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 the sqlite3_result_text* interfaces
is negative, then SQLite takes result text from the 2nd parameter
through 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_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.


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: SQLITE_DETERMINISTIC, SQLITE_DIRECTONLY, SQLITE_SUBTYPE, SQLITE_INNOCUOUS
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 flags is a security feature which is recommended
for all application-defined SQL functions, and especially for functions
that have side-effects or that could potentially leak sensitive
information.



 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 may call
sqlite3_value_subtype() to inspect the sub-types of its arguments.
Specifying this flag makes no difference for scalar or aggregate user
functions. However, if it is not specified for a user-defined window
function, then any sub-types belonging to arguments passed to the window
function may be discarded before the window function is called (i.e.
sqlite3_value_subtype() will always return 0).


See also lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Source Of Data In A Query Result
c5: c3ref/column_database_name.html
c0:
sqlite3_column_database_name(), sqlite3_column_database_name16(), sqlite3_column_table_name(), sqlite3_column_table_name16(), sqlite3_column_origin_name(), sqlite3_column_origin_name16()

c4:
These routines provide a means to determine the database, table, and
table column that is the origin of a particular result column in
SELECT statement.
The name of the database or table or column can be returned as
either a UTF-8 or UTF-16 string.  The _database_ routines return
the database name, the _table_ routines return the table name, and
the origin_ routines return the column name.
The returned string is valid until the prepared statement is destroyed
using sqlite3_finalize() or until the statement is automatically
reprepared by the first call to sqlite3_step() for a particular run
or until the same information is requested
again in a different encoding.

The names returned are the original un-aliased names of the
database, table, and column.

The first argument to these interfaces is a prepared statement.
These functions return information about the Nth result column returned by
the statement, where N is the second function argument.
The left-most column is column 0 for these routines.

If the Nth column returned by the statement is an expression or
subquery and is not a column value, then all of these functions return
NULL.  These routines might also return NULL if a memory allocation error
occurs.  Otherwise, they return the name of the attached database, table,
or column that query result column was extracted from.

As with all other SQLite APIs, those whose names end with "16" return
UTF-16 encoded strings and the other functions return UTF-8.

These APIs are only available if the library was compiled with the
SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol.

If two or more threads call one or more
column metadata interfaces
for the same prepared statement and result column
at the same time then the results are undefined.
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 the estimated of
the number of nanosecond 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: 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.


c0: sqlite3_blob_write()
c2: C API: Write Data Into A BLOB Incrementally
c5: c3ref/blob_write.html
c4:
This function is used to write data into an open BLOB handle from a
caller-supplied buffer. N bytes of data are copied from the buffer Z
into the open BLOB, starting at offset iOffset.

On success, sqlite3_blob_write() returns SQLITE_OK.
Otherwise, an  error code or an extended error code is returned.
Unless SQLITE_MISUSE is returned, this function sets the
database connection error code and message accessible via
sqlite3_errcode() and sqlite3_errmsg() and related functions.

If the BLOB handle passed as the first argument was not opened for
writing (the flags parameter to sqlite3_blob_open() was zero),
this function returns SQLITE_READONLY.

This function may only modify the contents of the BLOB; it is
not possible to increase the size of a BLOB using this API.
If offset iOffset is less than N bytes from the end of the BLOB,
SQLITE_ERROR is returned and no data is written. The size of the
BLOB (and hence the maximum value of N+iOffset) can be determined
using the sqlite3_blob_bytes() interface. If N or iOffset are less
than zero SQLITE_ERROR is returned and no data is written.

An attempt to write to an expired BLOB handle fails with an
error code of SQLITE_ABORT.  Writes to the BLOB that occurred
before the BLOB handle expired are not rolled back by the
expiration of the handle, though of course those changes might
have been overwritten by the statement that expired the BLOB handle
or by other independent statements.

This routine only works on a BLOB handle which has been created
by a prior successful call to sqlite3_blob_open() and which has not
been closed by sqlite3_blob_close().  Passing any other pointer in
to this routine results in undefined and probably undesirable behavior.

See also: sqlite3_blob_read().
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_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: 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: 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

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 used during testing and is only available when the SQLITE_TEST
compile-time option is used.



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.




Used by the cksmvfs VFS module only.

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 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_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.


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 metadata with argument values. If the same value is passed to
multiple invocations of the same SQL function during query execution, under
some circumstances the associated metadata may 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
metadata 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 metadata
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 metadata
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 metadata 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 metadata is still valid or
NULL if the metadata 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 metadata is discarded.
SQLite is free to discard the metadata 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. 

Note the last bullet 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.

In practice, metadata 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 lists of
  Objects,
  Constants, and
  Functions.


c2: C API: Status Parameters for prepared statements
c5: c3ref/c_stmtstatus_counter.html
c0:
SQLITE_STMTSTATUS_FULLSCAN_STEP, SQLITE_STMTSTATUS_SORT, SQLITE_STMTSTATUS_AUTOINDEX, SQLITE_STMTSTATUS_VM_STEP, SQLITE_STMTSTATUS_REPREPARE, SQLITE_STMTSTATUS_RUN, SQLITE_STMTSTATUS_FILTER_MISS, SQLITE_STMTSTATUS_FILTER_HIT, SQLITE_STMTSTATUS_MEMUSED

c4:
These preprocessor macros define integer codes that name counter
values associated with the sqlite3_stmt_status() interface.
The meanings of the various counters are as follows:



 SQLITE_STMTSTATUS_FULLSCAN_STEP
This is the number of times that SQLite has stepped forward in
a table as part of a full table scan.  Large numbers for this counter
may indicate opportunities for performance improvement through
careful use of indices.


 SQLITE_STMTSTATUS_SORT
This is the number of sort operations that have occurred.
A non-zero value in this counter may indicate an opportunity to
improvement performance through careful use of indices.


 SQLITE_STMTSTATUS_AUTOINDEX
This is the number of rows inserted into transient indices that
were created automatically in order to help joins run faster.
A non-zero value in this counter may indicate an opportunity to
improvement performance by adding permanent indices that do not
need to be reinitialized each time the statement is run.


 SQLITE_STMTSTATUS_VM_STEP
This is the number of virtual machine operations executed
by the prepared statement if that number is less than or equal
to 2147483647.  The number of virtual machine operations can be
used as a proxy for the total work done by the prepared statement.
If the number of virtual machine operations exceeds 2147483647
then the value returned by this statement status code is undefined.


 SQLITE_STMTSTATUS_REPREPARE
This is the number of times that the prepare statement has been
automatically regenerated due to schema changes or changes to
bound parameters that might affect the query plan.


 SQLITE_STMTSTATUS_RUN
This is the number of times that the prepared statement has
been run.  A single "run" for the purposes of this counter is one
or more calls to sqlite3_step() followed by a call to sqlite3_reset().
The counter is incremented on the first sqlite3_step() call of each
cycle.





SQLITE_STMTSTATUS_FILTER_HIT
SQLITE_STMTSTATUS_FILTER_MISS
SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
step was bypassed because a Bloom filter returned not-found.  The
corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
times that the Bloom filter returned a find, and thus the join step
had to be processed as normal.


 SQLITE_STMTSTATUS_MEMUSED
This is the approximate number of bytes of heap memory
used to store the prepared statement.  This value is not actually
a counter, and so the resetFlg parameter to sqlite3_stmt_status()
is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.


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: 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: 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_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 actuall 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: sqlite3_stmt_scanstatus()
c2: C API: Prepared Statement Scan Status
c5: c3ref/stmt_scanstatus.html
c4:
This interface returns 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.
Parameter "idx" identifies the specific loop to retrieve statistics for.
Loops are numbered starting from zero. If idx is out of range - less than
zero or greater than or equal to the total number of loops used to implement
the statement - a non-zero value is returned and the variable that pOut
points to is unchanged.

Statistics might not be available for all loops in all statements. In cases
where there exist loops with no available statistics, this function behaves
as if the loop did not exist - it returns non-zero and leave the variable
that pOut points to unchanged.

See also: sqlite3_stmt_scanstatus_reset()
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_exec(), sqlite3_step() and sqlite3_get_table() 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.

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.


c0: sqlite3_stmt_status()
c2: C API: Prepared Statement Status
c5: c3ref/stmt_status.html
c4:
Each prepared statement maintains various
SQLITE_STMTSTATUS counters that measure the number
of times it has performed specific operations.  These counters can
be used to monitor the performance characteristics of the prepared
statements.  For example, if the number of table steps greatly exceeds
the number of table searches or result rows, that would tend to indicate
that the prepared statement is using a full table scan rather than
an index.

This interface is used to retrieve and reset counter values from
a prepared statement.  The first argument is the prepared statement
object to be interrogated.  The second argument
is an integer code for a specific SQLITE_STMTSTATUS counter
to be interrogated.
The current value of the requested counter is returned.
If the resetFlg is true, then the counter is reset to zero after this
interface call returns.

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


c2: C API: Interrupt A Long-Running Query
c5: c3ref/interrupt.html
c4:
This function causes any pending database operation to abort and
return at its earliest opportunity. This routine is typically
called in response to a user action such as pressing "Cancel"
or Ctrl-C where the user wants a long query operation to halt
immediately.

It is safe to call this routine from a thread different from the
thread that is currently running the database operation.  But it
is not safe to call this routine with a database connection that
is closed or might close before sqlite3_interrupt() returns.

If an SQL operation is very nearly finished at the time when
sqlite3_interrupt() is called, then it might not have an opportunity
to be interrupted and might continue to completion.

An SQL operation that is interrupted will return SQLITE_INTERRUPT.
If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
that is inside an explicit transaction, then the entire transaction
will be rolled back automatically.

The sqlite3_interrupt(D) call is in effect until all currently running
SQL statements on database connection D complete.  Any new SQL statements
that are started after the sqlite3_interrupt() call and before the
running statement count reaches zero are interrupted as if they had been
running prior to the sqlite3_interrupt() call.  New SQL statements
that are started after the running statement count reaches zero are
not effected by the sqlite3_interrupt().
A call to sqlite3_interrupt(D) that occurs when there are no running
SQL statements is a no-op and has no effect on SQL statements
that are started after the sqlite3_interrupt() call returns.
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: sqlite3_sleep()
c2: C API: Suspend Execution For A Short Time
c5: c3ref/sleep.html
c4:
The sqlite3_sleep() function causes the current thread to suspend execution
for at least a number of milliseconds specified in its parameter.

If the operating system does not support sleep requests with
millisecond time resolution, then the time will be rounded up to
the nearest second. The number of milliseconds of sleep actually
requested from the operating system is returned.

SQLite implements this interface by calling the xSleep()
method of the default sqlite3_vfs object.  If the xSleep() method
of the default VFS is not implemented correctly, or not implemented at
all, then the behavior of sqlite3_sleep() may deviate from the description
in the previous paragraphs.
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: 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: sqlite3_blob_open()
1 Destructor: sqlite3_blob_close()
4 Methods:
 sqlite3_blob_bytes(),
sqlite3_blob_read(),
sqlite3_blob_reopen(),
sqlite3_blob_write()
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_db_config()
c2: C API: Configure database connections
c5: c3ref/db_config.html
c4:
The sqlite3_db_config() interface is used to make configuration
changes to a database connection.  The interface is similar to
sqlite3_config() except that the changes apply to a single
database connection (specified in the first argument).

The second argument to sqlite3_db_config(D,V,...)  is the
configuration verb - an integer code
that indicates what aspect of the database connection is being configured.
Subsequent arguments vary depending on the configuration verb.

Calls to sqlite3_db_config() return SQLITE_OK if and only if
the call is considered successful.
See also lists of
  Objects,
  Constants, and
  Functions.


c0: SQLITE_SERIALIZE_NOCOPY
c2: C API: Flags for sqlite3_serialize
c5: c3ref/c_serialize_nocopy.html
c4:
Zero or more of the following constants can be OR-ed together for
the F argument to sqlite3_serialize(D,S,P,F).

SQLITE_SERIALIZE_NOCOPY means that sqlite3_serialize() will return
a pointer to contiguous in-memory database that it is currently using,
without making a copy of the database.  If SQLite is not currently using
a contiguous in-memory database, then this option causes
sqlite3_serialize() to return a NULL pointer.  SQLite will only be
using a contiguous in-memory database if it has been initialized by a
prior call to sqlite3_deserialize().
See also lists of
  Objects,
  Constants, and
  Functions.


c0: sqlite3_reset()
c2: C API: Reset A Prepared Statement Object
c5: c3ref/reset.html
c4:
The sqlite3_reset() function is called to reset a prepared statement
object back to its initial state, ready to be re-executed.
Any SQL statement variables that had values bound to them using
the sqlite3_bind_*() API retain their values.
Use sqlite3_clear_bindings() to reset the bindings.

The sqlite3_reset(S) interface resets the prepared statement S
back to the beginning of its program.

If the most recent call to sqlite3_step(S) for the
prepared statement S returned SQLITE_ROW or SQLITE_DONE,
or if sqlite3_step(S) has never before been called on S,
then sqlite3_reset(S) returns SQLITE_OK.

If the most recent call to sqlite3_step(S) for the
prepared statement S indicated an error, then
sqlite3_reset(S) returns an appropriate error code.

The sqlite3_reset(S) interface does not change the values
of any bindings on the prepared statement S.
See also lists of
  Objects,
  Constants, and
  Functions.


c2: SQLite Developers
c5: crew.html
c4:
D. Richard Hipp
 began the SQLite project on 2000-05-29
and continues to serve as the project architect.  Richard was born,
lives, and works in 
Charlotte, North Carolina.  He holds degrees from
Georgia Tech (MSEE, 1984) and
Duke University (PhD, 1992) and is
the founder of the consulting firm
Hwaci.








Dan Kennedy is an Australian currently based in South-East Asia.
He holds a degree in Computer System Engineering from the University of
Queensland and has worked in a variety of fields, including industrial
automation, computer graphics and embedded software development.
Dan has been a key contributor to SQLite since 2002.







Joe Mistachkin
(pronounced "miss-tash-kin") is a software engineer and one
of the maintainers of Tcl/Tk.  He is also the author of the TclBridge
component and the Eagle scripting language.  He has been working in the
software industry since 1994.


c2: The Session Extension
c5: sessionintro.html
c4:
1. Introduction

The session extension provide a mechanism for recording changes
to some or all of the rowid tables in an SQLite database, and packaging
those changes into a "changeset" or "patchset" file that can later
be used to apply the same set of changes to another database with
the same schema and compatible starting data.  A "changeset" may
also be inverted and used to "undo" a session.

This document is an introduction to the session extension.
The details of the interface are in the separate
Session Extension C-language Interface document.

1.1. Typical Use Case

Suppose SQLite is used as the application file format for a
particular design application.  Two users, Alice and Bob, each start
with a baseline design that is about a gigabyte in size.  They work
all day, in parallel, each making their own customizations and tweaks
to the design.  At the end of the day, they would like to merge their
changes together into a single unified design.

The session extension facilitates this by recording all changes to
both Alice's and Bob's databases and writing those changes into
changeset or patchset files.  At the end of the day, Alice can send her
changeset to Bob and Bob can "apply" it to his database.  The result (assuming
there are no conflicts) is that Bob's database then contains both his
changes and Alice's changes.  Likewise, Bob can send a changeset of
his work over to Alice and she can apply his changes to her database.

In other words, the session extension provides a facility for
SQLite database files that is similar to the unix
patch utility program,
or to the "merge" capabilities of version control systems such
as Fossil, Git, 
or Mercurial.

1.2. Obtaining the Session Extension

 Since version 3.13.0 (2016-05-18), 
the session extension has been included in the SQLite
amalgamation source distribution. By default, the session extension is 
disabled. To enable it, build with the following compiler switches:

-DSQLITE_ENABLE_SESSION -DSQLITE_ENABLE_PREUPDATE_HOOK


 Or, if using the autoconf build system, pass the --enable-session option to the configure script.

1.3. Limitations



 Prior to SQLite version 3.17.0, the session extension only worked with
        rowid tables, not WITHOUT ROWID tables. As of 3.17.0, both
        rowid and WITHOUT ROWID tables are supported.

 There is no support for virtual tables. Changes to virtual tables are
        not captured.

 The session extension only works with tables that have a declared
        PRIMARY KEY. The PRIMARY KEY of a table may be an INTEGER PRIMARY KEY
        (rowid alias) or an external PRIMARY KEY.

 SQLite allows NULL values to be stored in
        PRIMARY KEY columns. However, the session extension ignores all
        such rows. No changes affecting rows with one or more NULL values
        in PRIMARY KEY columns are recorded by the sessions module.


2. Concepts



2.1. Changesets and Patchsets
 The sessions module revolves around creating and manipulating 
changesets. A changeset is a blob of data that encodes a series of 
changes to a database. Each change in a changeset is one of the 
following:


   An INSERT. An INSERT change contains a single row to add to 
       a database table. The payload of the INSERT change consists of the
       values for each field of the new row.

   A DELETE. A DELETE change represents a row, identified by
       its primary key values, to remove from a database table. The payload
       of a DELETE change consists of the values for all fields of the 
       deleted row.

   An UPDATE. An UPDATE change represents the modification of
       one or more non-PRIMARY KEY fields of a single row within a database 
       table, identified by its PRIMARY KEY fields. The payload for an UPDATE
       change consists of:
   
      The PRIMARY KEY values identifying the modified row, 
      The new values for each modified field of the row, and
      The original values for each modified field of the row.
   
        An UPDATE change does not contain any information regarding
       non-PRIMARY KEY fields that are not modified by the change. It is not
       possible for an UPDATE change to specify modifications to PRIMARY 
       KEY fields. 


 A single changeset may contain changes that apply to more than one 
database table. For each table that the changeset includes at least one change
for, it also encodes the following data:


   The name of the database table, 
   The number of columns the table has, and
   Which of those columns are PRIMARY KEY columns.


 Changesets may only be applied to databases that contain tables 
matching the above three criteria as stored in the changeset.

 A patchset is similar to a changeset. It is slightly more compact than
a changeset, but provides more limited conflict detection and resolution
options (see the next section for details). The differences between a 
patchset and a changeset are that:


   For a DELETE change, the payload consists of the PRIMARY KEY 
          fields only. The original values of other fields are not stored as
          part of a patchset.

   For an UPDATE change, the payload consists of the PRIMARY KEY 
          fields and the new values of modified fields only. The original
          values of modified fields are not stored as part of a patchset.


2.2. Conflicts

 When a changeset or patchset is applied to a database, an attempt is 
made to insert a new row for each INSERT change, remove a row for each
DELETE change and modify a row for each UPDATE change. If the target 
database is in the same state as the original database that the changeset
was recorded on, this is a simple matter. However, if the contents of the
target database is not in exactly this state, conflicts can occur when
applying the changeset or patchset.

When processing an INSERT change, the following conflicts can
occur:


   The target database may already contain a row with the same PRIMARY
       KEY values as specified by the INSERT change.

   Some other database constraint, for example a UNIQUE or CHECK 
       constraint, may be violated when the new row is inserted.


When processing a DELETE change, the following conflicts may be
detected:


   The target database may contain no row with the specified PRIMARY 
       KEY values to delete.

   The target database may contain a row with the specified PRIMARY
       KEY values, but the other fields may contain values that do not
       match those stored as part of the changeset. This type of conflict
       is not detected when using a patchset.


When processing an UPDATE change, the following conflicts may be
detected:


   The target database may contain no row with the specified PRIMARY 
       KEY values to modify.

   The target database may contain a row with the specified PRIMARY
       KEY values, but the current values of the fields that will be modified
       by the change may not match the original values stored within the
       changeset. This type of conflict is not detected when using a patchset.

   Some other database constraint, for example a UNIQUE or CHECK 
       constraint, may be violated when the row is updated.


 Depending on the type of conflict, a sessions application has a variety
of configurable options for dealing with conflicts, ranging from omitting the
conflicting change, aborting the entire changeset application or applying
the change despite the conflict. For details, refer to the documentation for
the sqlite3changeset_apply() API.

2.3. Changeset Construction

 After a session object has been configured, it begins monitoring for 
changes to its configured tables. However, it does not record an entire
change each time a row within the database is modified. Instead, it records
just the PRIMARY KEY fields for each inserted row, and just the PRIMARY KEY 
and all original row values for any updated or deleted rows. If a row is 
modified more than once by a single session, no new information is recorded.

 The other information required to create a changeset or patchset is
read from the database file when sqlite3session_changeset() or
sqlite3session_patchset() is called. Specifically,


   For each primary key recorded as a result of an INSERT operation, 
       the sessions module checks if there is a row with a matching primary
       key still in the table. If so, an INSERT change is added to the 
       changeset.

   For each primary key recorded as a result of an UPDATE or DELETE
       operation, the sessions module also checks for a row with a matching
       primary key within the table. If one can be found, but one or more
       of the non-PRIMARY KEY fields does not match the original recorded
       value, an UPDATE is added to the changeset. Or, if there is no row
       at all with the specified primary key, a DELETE is added to the 
       changeset. If the row does exist but none of the non-PRIMARY KEY
       fields have been modified, no change is added to the changeset.


 One implication of the above is that if a change is made and then 
unmade within a single session (for example if a row is inserted and then
deleted again), the sessions module does not report any change at all. Or
if a row is updated multiple times within the same session, all updates
are coalesced into a single update within any changeset or patchset blob.

3. Using The Session Extension

 This section provides examples that demonstrate how to use the sessions
    extension.

3.1. Capturing a Changeset

 The example code below demonstrates the steps involved in capturing a
changeset while executing SQL commands. In summary:


   A session object (type sqlite3_session*) is created by making a 
          call to the sqlite3session_create() API function.

       A single session object monitors changes made to a single database 
          (i.e. "main", "temp" or an attached database) via a single 
          sqlite3* database handle.

   The session object is configured with a set of tables to monitor
          changes on.

        By default a session object does not monitor changes on any 
           database table. Before it does so it must be configured. There 
           are three ways to configure the set of tables to monitor changes
           on:
       
          By explicitly specifying tables using one call to
              sqlite3session_attach() for each table, or

          By specifying that all tables in the database should be monitored
              for changes using a call to sqlite3session_attach() with a
              NULL argument, or

          By configuring a callback to be invoked the first time each table
              is written to that indicates to the session module whether or
              not changes on the table should be monitored.
       
         The example code below uses the second of the methods enumerated
            above - it monitors for changes on all database tables.

    Changes are made to the database by executing SQL statements. The
           session object records these changes.

    A changeset blob is extracted from the session object using a call
           to sqlite3session_changeset() (or, if using patchsets, a call to
           the sqlite3session_patchset() function).

    The session object is deleted using a call to the 
           sqlite3session_delete() API function.

        It is not necessary to delete a session object after extracting
           a changeset or patchset from it. It can be left attached to the
           database handle and will continue monitoring for changes on the
           configured tables as before. However, if 
           sqlite3session_changeset() or sqlite3session_patchset() is
           called a second time on a session object, the changeset or patchset
           will contain all changes that have taken place on the connection
           since the session was created. In other words,
           a session object is not reset or
           zeroed by a call to sqlite3session_changeset() or
           sqlite3session_patchset().


/*
** Argument zSql points to a buffer containing an SQL script to execute 
** against the database handle passed as the first argument. As well as
** executing the SQL script, this function collects a changeset recording
** all changes made to the "main" database file. Assuming no error occurs,
** output variables (*ppChangeset) and (*pnChangeset) are set to point
** to a buffer containing the changeset and the size of the changeset in
** bytes before returning SQLITE_OK. In this case it is the responsibility
** of the caller to eventually free the changeset blob by passing it to
** the sqlite3_free function.
**
** Or, if an error does occur, return an SQLite error code. The final
** value of (*pChangeset) and (*pnChangeset) are undefined in this case.
*/
int sql_exec_changeset(
  sqlite3 *db,                  /* Database handle */
  const char *zSql,             /* SQL script to execute */
  int *pnChangeset,             /* OUT: Size of changeset blob in bytes */
  void **ppChangeset            /* OUT: Pointer to changeset blob */
){
  sqlite3_session *pSession = 0;
  int rc;

  /* Create a new session object */
  rc = sqlite3session_create(db, "main", &pSession);

  /* Configure the session object to record changes to all tables */
  if( rc==SQLITE_OK ) rc = sqlite3session_attach(pSession, NULL);

  /* Execute the SQL script */
  if( rc==SQLITE_OK ) rc = sqlite3_exec(db, zSql, 0, 0, 0);

  /* Collect the changeset */
  if( rc==SQLITE_OK ){
    rc = sqlite3session_changeset(pSession, pnChangeset, ppChangeset);
  }

  /* Delete the session object */
  sqlite3session_delete(pSession);

  return rc;
}


3.2. Applying a Changeset to a Database

 Applying a changeset to a database is simpler than capturing a changeset.
Usually, a single call to sqlite3changeset_apply(), as depicted in the
example code below, suffices.

 In cases where it is complicated, the complications in applying a 
changeset lie in conflict resolution. Refer to the API documentation linked
above for details.

  /*
** Conflict handler callback used by apply_changeset(). See below.
*/
static int xConflict(void *pCtx, int eConflict, sqlite3_changset_iter *pIter){
  int ret = (int)pCtx;
  return ret;
}

/*
** Apply the changeset contained in blob pChangeset, size nChangeset bytes,
** to the main database of the database handle passed as the first argument.
** Return SQLITE_OK if successful, or an SQLite error code if an error
** occurs.
**
** If parameter bIgnoreConflicts is true, then any conflicting changes 
** within the changeset are simply ignored. Or, if bIgnoreConflicts is
** false, then this call fails with an SQLTIE_ABORT error if a changeset
** conflict is encountered.
*/
int apply_changeset(
  sqlite3 *db,                  /* Database handle */
  int bIgnoreConflicts,         /* True to ignore conflicting changes */
  int nChangeset,               /* Size of changeset in bytes */
  void *pChangeset              /* Pointer to changeset blob */
){
  return sqlite3changeset_apply(
      db, 
      nChangeset, pChangeset, 
      0, xConflict, 
      (void*)bIgnoreConflicts
  );
}


3.3. Inspecting the Contents of a Changeset

 The example code below demonstrates the techniques used to iterate 
through and extract the data related to all changes in a changeset. To
summarize:


   The sqlite3changeset_start() API is called to create and
          initialize an iterator to iterate through the contents of a
          changeset. Initially, the iterator points to no element at all.

   The first call to sqlite3changeset_next() on the iterator moves
          it to point to the first change  in the changeset (or to EOF, if 
          the changeset is completely empty). sqlite3changeset_next() returns
          SQLITE_ROW if it moves the iterator to point to a valid entry,
          SQLITE_DONE if it moves the iterator to EOF, or an SQLite error
          code if an error occurs.

   If the iterator points to a valid entry, the sqlite3changeset_op()
          API may be used to determine the type of change (INSERT, UPDATE or
          DELETE) that the iterator points to. Additionally, the same API 
          can be used to obtain the name of the table the change applies to
          and its expected number of columns and primary key columns.

   If the iterator points to a valid INSERT or UPDATE entry, the
          sqlite3changeset_new() API may be used to obtain the new.* values
          within the change payload.

   If the iterator points to a valid DELETE or UPDATE entry, the
          sqlite3changeset_old() API may be used to obtain the old.* values
          within the change payload.

   An iterator is deleted using a call to the 
          sqlite3changeset_finalize() API. If an error occured while
          iterating, an SQLite error code is returned (even if the same error
          code has already been returned by sqlite3changeset_next()). Or,
          if no error has occurred, SQLITE_OK is returned.


  /*
** Print the contents of the changeset to stdout.
*/
static int print_changeset(void *pChangeset, int nChangeset){
  int rc;
  sqlite3_changeset_iter *pIter = 0;

  /* Create an iterator to iterate through the changeset */
  rc = sqlite3changeset_start(&pIter, nChangeset, pChangeset);
  if( rc!=SQLITE_OK ) return rc;

  /* This loop runs once for each change in the changeset */
  while( SQLITE_ROW==sqlite3changeset_next(pIter) ){
    const char *zTab;           /* Table change applies to */
    int nCol;                   /* Number of columns in table zTab */
    int op;                     /* SQLITE_INSERT, UPDATE or DELETE */
    sqlite3_value *pVal;

    /* Print the type of operation and the table it is on */
    rc = sqlite3changeset_op(pIter, &zTab, &nCol, &op, 0);
    if( rc!=SQLITE_OK ) goto exit_print_changeset;
    printf("%s on table %s\n",
      op==SQLITE_INSERT?"INSERT" : op==SQLITE_UPDATE?"UPDATE" : "DELETE",
      zTab
    );

    /* If this is an UPDATE or DELETE, print the old.* values */
    if( op==SQLITE_UPDATE || op==SQLITE_DELETE ){
      printf("Old values:");
      for(i=0; i&lt;nCol; i++){
        rc = sqlite3changeset_old(pIter, i, &pVal);
        if( rc!=SQLITE_OK ) goto exit_print_changeset;
        printf(" %s", pVal ? sqlite3_value_text(pVal) : "-");
      }
      printf("\n");
    }

    /* If this is an UPDATE or INSERT, print the new.* values */
    if( op==SQLITE_UPDATE || op==SQLITE_INSERT ){
      printf("New values:");
      for(i=0; i&lt;nCol; i++){
        rc = sqlite3changeset_new(pIter, i, &pVal);
        if( rc!=SQLITE_OK ) goto exit_print_changeset;
        printf(" %s", pVal ? sqlite3_value_text(pVal) : "-");
      }
      printf("\n");
    }
  }

  /* Clean up the changeset and return an error code (or SQLITE_OK) */
 exit_print_changeset:
  rc2 = sqlite3changeset_finalize(pIter);
  if( rc==SQLITE_OK ) rc = rc2;
  return rc;
}


4. Extended Functionality

 Most applications will only use the session module functionality described
in the previous section. However, the following additional functionality is
available for the use and manipulation of changeset and patchset blobs:


   Two or more changeset/patchsets may be combined using the 
       sqlite3changeset_concat() or sqlite3_changegroup interfaces.

   A changeset may be "inverted" using the sqlite3changeset_invert()
       API function. An inverted changeset undoes the changes made by the
       original. If changeset C+ is the inverse of changeset C, then
       applying C and then C+ to a database should leave
       the database unchanged.


c2: The SQLITE_STMT Virtual Table
c5: stmt.html
c4:
1. Overview


The SQLITE_STMT extension implements an eponymous-only virtual table that
provides information about all prepared statements associated with
the database connection.



The SQLITE_STMT extension is included in the amalgamation though 
it is disabled
by default.  Use the SQLITE_ENABLE_STMTVTAB compile-time option to enable
the SQLITE_STMT extension.  The SQLITE_STMT extension can also be 
loaded at run-time
by compiling the extension into a shared library or DLL using the source
code at https://sqlite.org/src/file/ext/misc/stmt.c and following the
instructions for how to compile loadable extensions.



The SQLITE_STMT extension is enabled in default builds
of the command-line shell.

2. Usage


The SQLITE_STMT virtual table is a read-only table that can be directly
queried to access information about all prepared statements on the 
current database connection.  For example:

SELECT * FROM sqlite_stmt;



A statement such as the above can be run immediately prior to invoking
sqlite3_close() to confirm that all prepared statements have been 
finalized and to help identify and track down prepared
statements that have "leaked" and missed finalization.


The SQLITE_STMT virtual table can also be used to access performance
information about prepared statements, to aid in optimization an application.
For example,
to find out how much memory is being used by prepared statements that have
never been used, one could run:

SELECT sum(mem) FROM sqlite_stmt WHERE run=0;


2.1. Columns


The columns are provided by the SQLITE_STMT virtual table are summarized by
the hypothetical CREATE TABLE statement show here:

CREATE TABLE sqlite_stmt(
  sql    TEXT,    -- Original SQL text
  ncol   INT,     -- Number of output columns
  ro     BOOLEAN, -- True for "read only" statements
  busy   BOOLEAN, -- True if the statement is current running
  nscan  INT,     -- Number of full-scan steps
  nsort  INT,     -- Number of sort operations
  naidx  INT,     -- Number of automatic index inserts
  nstep  INT,     -- Number of byte-code engine steps
  reprep INT,     -- Number of reprepare operations
  run    INT,     -- Number of times this statement has been run
  mem    INT      -- Heap memory used by this statement
);


Future releases may add new output columns and may change the order
of legacy columns.
Further detail about the meaning of each column in the SQLITE_STMT virtual
table is provided below:


sql:
The original SQL text of the prepared statement.  If the prepared
statement is compiled using the sqlite3_prepare() interface, then
the SQL text might not have been saved, in which case this column
will be NULL.

ncol:
The number of columns in the result set of a query.
For DML statements, this column has a value of 0.

ro:
The "read only" column.  This column is true (non-zero) if the
SQL statement is a query and false (zero) if it is a DML statement.

busy:
This field is true if the prepared statement is currently running.
In other words, this field is true if sqlite3_step() has been called
on the prepared statement at least once but sqlite3_reset() has
not yet been called to reset it.

nscan:
This field is the number of times that the bytecode engine has stepped
through a table as part of a full-table scan.  A large number if this
field may indicate an opportunity to improve performance by adding an
index.  This field is equivalent to the SQLITE_STMTSTATUS_FULLSCAN_STEP
value.

nsort:
This field is the number of times that the bytecode engine had to sort.
A positive value in this field may indicate an opportunity to improve
performance by adding an index that will cause the query results to
appear naturally in the desired order.  
This field is equivalent to the SQLITE_STMTSTATUS_SORT value.

naidx:
This field is the number of rows that have been inserted into
automatic indexes.  A positive value in this field may indicate 
an opportunity to improve performance by adding a named index that
take the place of the automatic index.
This field is equivalent to the SQLITE_STMTSTATUS_AUTOINDEX value.

nstep:
This field is the number of bytecode engine operations that have
been performed for the prepared statement.  This field can be used
as a proxy for how much CPU time a statement has used.
This field is equivalent to the SQLITE_STMTSTATUS_VM_STEP value.

reprep:
This field is the number of times that the statement has had to be
reprepared due to schema changes or changes to parameter bindings.
This field is equivalent to the SQLITE_STMTSTATUS_REPREPARE value.

run:
This field is the number of times that the statement has been run.
This field is equivalent to the SQLITE_STMTSTATUS_RUN value.

mem:
This field is the number of bytes of heap storage used by the
prepared statement.
This field is equivalent to the SQLITE_STMTSTATUS_MEMUSED value.


c2: Long Term Support
c5: lts.html
c4:
The intent of the developers is to support SQLite through
the year 2050.


At this writing, 2050 is still 34 years in the future.
Nobody knows what will happen in that time, and we cannot
absolutely promise that SQLite will be viable or useful that
far out.
But we can promise this: we plan as if we will be
supporting SQLite until 2050.
That long-term outlook affects our
decisions in important ways.



Cross-platform Code &rarr;
SQLite runs on any platform with an 8-bit byte,
two's complement 32-bit and 64-bit integers, 
and a C compiler.  It is actively
tested on all currently popular CPUs and operating
systems.
The extreme portability of the SQLite code and file
format will help it remain viable on future platforms.


Stable, Cross-platform Database Files &rarr;
SQLite database files are bit-for-bit identical on
32-bit, 64-bit, big-endian, and little-endian platforms.  You
can copy an SQLite database file from one system to another
without having to translate or convert the database.
Furthermore, the file format is well documented and stable.
Database files created today will be readable and writable by
future versions of SQLite decades in the future.


Aviation-grade testing &rarr;
Every machine-code branch instruction is tested in both
directions.  Multiple times.  On multiple platforms and with
multiple compilers.  This helps make the code robust for
future migrations.  The intense testing also means that new
developers can make experimental enhancements to SQLite and,
assuming legacy tests all pass, be reasonably sure that the
enhancement does not break legacy.


Extensive, detailed documentation &rarr;
SQLite has candid, developer-friendly,
and open-source documentation.  Docs are written by and
for programmers.
(A few examples:
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8])
The extensive documentation helps new developers
come up to speed on SQLite very quickly.


Heavily commented source code &rarr;
The SQLite source code is over 35% comment.  Not boiler-plate
comments, but useful comments that explain the meaning of variables
and objects and the intent of methods and procedures.  
The code is designed
to be accessible to new programmers and maintainable over a span
of decades.


Disaster planning &rarr;
Every byte of source-code history for SQLite is cryptographically
protected and is automatically replicated to multiple
geographically separated servers, in datacenters 
owned by different companies.
Thousands of additional clones exist on private servers around the
world.
The primary developers of SQLite live in different regions of the world.
SQLite can survive a continental catastrophe.


Old school &rarr;
Nobody is completely immune to trends and fads, but the SQLite
developers work hard to avoid being sucked into the latest programming
fashion.  Our aim is to produce timeless code that will be
readable, understandable, and maintainable by programmers 
who have not yet been born.



In addition to "supporting" SQLite through the year 2050, the developers
also promise to keep the SQLite 
C-language API and on-disk format 
fully backwards compatible.
This means that application written to use SQLite today should be able to
link against and use future versions of SQLite released decades in the
future.


Our goal is to make the content you store in SQLite today as 
easily accessible to your grandchildren as it is to you.


Update on 2018-05-31:
Our goal of supporting SQLite long-term have apparently come to the
notice of the preservationist at the 
US Library Of Congress who have identified
SQLite as a recommended storage format for the preservation of
digital content.


c2: SQLite Over a Network, Caveats and Considerations
c5: useovernet.html
c4:
SQLite Over a Network,Caveats and Considerations


Introduction

  Users of the SQLite library, particularly application developers,
  who want to access a SQLite database
  from different systems connected by a network are often
  tempted to simply open a database connection by specifying
  a filename which references a database file somewhere within
  a network filesystem. ("remote database" here)
  This "file" is then accessed by means of
  OS API's which permit the illusion of I/O from/to a local file.
  The illusion is good but imperfect in important ways.

  This simple, "remote database" approach is usually not the best way
  to use a single SQLite database from multiple systems,
  (even if it appears to "work"),
  as it often leads to various kinds of trouble and grief.
  Because these problems are inevitable with some usages,
  but not frequent or repeatable,
  it behooves application developers to not rely
  on early testing success to decide
  that their remote database use will work as desired.

Issues Arising with Remote Database Files

This diagram shows components and their linkages
for reference in the discussion following:







  The issues arise from the properties and utilization
  of the two data/control channels between the above three blocks.


Channel Traffic Volume

  The "API Call" channel carries less information
  than the "File I/O" channel.
  API calls to submit queries or specify data modification
  normally require substantially fewer bits to be passed
  back and forth than are transferred to/from
  the database file to store or find the data.
  Query result retrieval will normally require much more file traffic
  than API traffic because the data to be returned is rarely
  to be found without reading unrequested data.

Channel Bandwidth

  The API Call channel operates at processor main memory speeds
  (Giga-words/second), with data often passed by reference (and so not copied.)
  In contrast, even the fastest File I/O channels are slower.
  They require the data to be copied, usually over a medium
  requiring bit-serialization. For spinning magnetic media,
  transfers await platter rotation and head movement, then
  are limited by spin velocity.


  When the File I/O channel includes a network connection,
  (in addition to some genuine File I/O at its far end),
  additional slowness is imposed. Even where raw transfer
  rate does not limit bandwidth, the traffic must still be
  packetized and buffered at both ends.
  Additional layers of I/O handlers add scheduling delays.
  However, slowed transfers are the least significant
  issue with network filesystems.

Channel Reliability

  The "API Call" channel is highly reliable, to the extent
  that error rates are unstated and ignored as negligible.
  The channel fails only when the system loses power
  (excepting meteorites, etc.)


  The "File I/O" channel, when it directly reaches a local storage device,
  is also highly reliable.
  (Spinning storage MTBF exceeds 1 million hours,
  and NVRAM lasts longer.)
  Local devices also have a characteristic
  which is critical for enabling database management software
  to be designed to ensure ACID behavior:
  When all process writes to the device have completed,
  (when POSIX fsync() or Windows FlushFileBuffers() calls return),
  the filesystem then either has
  stored the "written" data or will do so
  before storing any subsequently written data.


  When network filesystem apparatus and software layers are interposed
  between filesystem clients and a filesystem over an actual storage device,
  significant sources of failure and misbehavior are introduced.
  While network data transfers are error-checked well, transfer packets
  do not all reliably arrive at their destination once sent.
  Some packets are clobbered by other packets and must be resent.
  Under packet clobbering conditions, repeated retries
  can impose delays exceeding
  what is needed for similar data to reach local storage.
  Some portions of what a client writes can end up stored
  out of time order relative to other portions written.


  Because of the disordering and outright data loss
  which occur in network filesystem writes, it is critical
  that sets of file writes can be accurately known to be done
  before a subsequent set of file writes begins.
  This assurance is obtained by use of robustly designed
  and correctly implemented fsync() (or equivalent) OS functions.
  Unfortunately for some applications, network filesystem sync
  operation can be less robust than local filesystem sync.
  Attaining robust sync in the face of network packet transport errors
  is hard, and safeguards are sometimes relaxed in favor of performance.


  A similar hazard arises with file locking in network filesystems.
  SQLite relies on exclusive locks for write operations, and those have
  been known to operate incorrectly for some network filesystems. This
  has led to database corruption. That may happen again as the designers
  of such change their implementation to suit more common use cases.


  The bottom line is that network filesystem sync and locking reliability
  vary among implementations and installations. The design
  assumptions upon which it relies may hold more true where
  an application is tested than where it is relied upon.
  Rely upon it at your (and your customers') peril.
  See How To Corrupt Your Database Files.


Performance and Reliability Issues

  From the above diagram and discussion, it is obvious that
  performance (aka "speed") is degraded by insertion
  of a network link into one of the two channels.
  Consideration of relative traffic volumes between
  the API Call channel and the File I/O channel
  reveals that such insertion will have less performance
  impact at the API Call channel.


  Consideration of reliability impact is easier, with a clearer outcome:
  Inserting a network link into the API Call channel may also result
  in call failures at times. But if the Client Application
  has bothered to use SQL/SQLite transactions properly,
  such failures will only cause a transaction to fail
  and be rolled back, without compromising the integrity
  of the data. In contrast, if the network link is
  inserted into the File I/O channel, transactions may fail
  (as for the API Call insertion) but with the additional
  effect that the remote database is corrupted.


  These network unreliability issues can be mitigated,
  completely or to an acceptable degree,
  by using SQLite in rollback mode.
  However, the SQLite library is not tested in across-a-network
  scenarios, nor is that reasonably possible.
  Hence, use of a remote database is done at the user's risk.


Recommendations

  Generally, if your data is separated from the application
  by a network, you want to use a client/server database.
  This is due to the fact that the database engine acts
  as a bandwidth-reducing filter on the database traffic.

  If your data is separated from the application by a network,
  you want the low-traffic link to be across the network,
  not the high-traffic link. This means that the database engine
  needs to be on the same machine as the database itself.
  Such is the case with a client/server database like PostgreSQL.
  SQLite is different in that the database engine runs on
  the same machine as the application, which forces the
  higher-traffic link to traverse the network in remote
  database scenarios.  That normally results in lower performance.

  Network filesystems do not support the ability to do
  simultaneous reads and writes while at the same time
  keeping the database consistent.
  So if you have multiple clients on multiple different
  machines which need to do simultaneous database
  reads and writes, you have these choices:

  1.  Use a client/server database engine.
  PostgreSQL
  is an excellent choice. A variation of this is:

  2.  Host an SQLite database in WAL mode, but do
  all reads and writes from processes on the same machine
  that stores the database file.
  Implement a proxy that runs on the database machine that
  relays read/write requests from remote machines.

  3.  Use SQLite in rollback mode.
  This means you can have multiple simultaneous readers or one writer,
  but not simultaneous readers and writers.

  Application programmers should be cognizant of the possibility
  that their application's users will elect to use a remote database
  if they can do so. Unless one of the above choices
  has been effected, or one at a time, exclusive access is used,
  a programmer should consider blocking that
  election unless reliability is of little importance.

Summary

  Choose the technology that is right for you and your customers.
  If your data lives on a different machine from your application,
  then you should consider a client/server database.
  SQLite is designed for situations where the data and application
  coexist on the same machine.
  SQLite can still be made to work in many remote database
  situations, but a client/server solution will usually work
  better in that scenario.


c2: Pragma statements supported by SQLite
c5: pragma.html
c4:
PRAGMA Statements



The PRAGMA statement is an SQL extension specific to SQLite and used to 
modify the operation of the SQLite library or to query the SQLite library for 
internal (non-table) data. The PRAGMA statement is issued using the same
interface as other SQLite commands (e.g. SELECT, INSERT) but is
different in the following important respects:


The pragma command is specific to SQLite and is
    not compatible with any other SQL database engine.
Specific pragma statements may be removed and others added in future
    releases of SQLite. There is no guarantee of backwards compatibility.
No error messages are generated if an unknown pragma is issued.
    Unknown pragmas are simply ignored. This means if there is a typo in 
    a pragma statement the library does not inform the user of the fact.
Some pragmas take effect during the SQL compilation stage, not the
    execution stage. This means if using the C-language sqlite3_prepare(), 
    sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper 
    interface), the pragma may run during the sqlite3_prepare() call,
    not during the sqlite3_step() call as normal SQL statements do.
    Or the pragma might run during sqlite3_step() just like normal
    SQL statements.  Whether or not the pragma runs during sqlite3_prepare()
    or sqlite3_step() depends on the pragma and on the specific release
    of SQLite.
The EXPLAIN and EXPLAIN QUERY PLAN prefixes to SQL statements
    only affect the behavior of the statement during sqlite3_step().
    That means that PRAGMA statements that take effect during
    sqlite3_prepare() will behave the same way regardless of whether or
    not they are prefaced by "EXPLAIN".


The C-language API for SQLite provides the SQLITE_FCNTL_PRAGMA
file control which gives VFS implementations the
opportunity to add new PRAGMA statements or to override the meaning of
built-in PRAGMA statements.



PRAGMA command syntax
pragma-stmt:
hide
 
 

pragma-value:
hide
 
 

signed-number:
show
 
 







A pragma can take either zero or one argument.  The argument is may be either
in parentheses or it may be separated from the pragma name by an equal sign.
The two syntaxes yield identical results.
In many pragmas, the argument is a boolean.  The boolean can be one of:



1 yes true on0 no false off


Keyword arguments can optionally appear in quotes.  
(Example:  'yes' &#91;FALSE&#93;.) Some pragmas
takes a string literal as their argument.  When pragma takes a keyword
argument, it will usually also take a numeric equivalent as well.
For example, "0" and "no" mean the same thing, as does "1" and "yes".
When querying the value of a setting, many pragmas return the number
rather than the keyword.

A pragma may have an optional schema-name
before the pragma name.
The schema-name is the name of an ATTACH-ed database 
or "main" or "temp" for the main and the TEMP databases.  If the optional
schema name is omitted, "main" is assumed.  In some pragmas, the schema
name is meaningless and is simply ignored.  In the documentation below,
pragmas for which the schema name is meaningful are shown with a
"schema." prefix.



PRAGMA functions



PRAGMAs that return results and that have no side-effects can be 
accessed from ordinary SELECT statements as table-valued functions.
For each participating PRAGMA, the corresponding table-valued function
has the same name as the PRAGMA with a 7-character "pragma_" prefix.
The PRAGMA argument and schema, if any, are passed as arguments to the
table-valued function, with the schema as an optional, last argument.

For example, information about the columns in an index can be
read using the index_info pragma as follows:


PRAGMA index_info('idx52');


Or, the same content can be read using:


SELECT * FROM pragma_index_info('idx52');


The advantage of the table-valued function format is that the query
can return just a subset of the PRAGMA columns, can include a WHERE clause,
can use aggregate functions, and the table-valued function can be just
one of several data sources in a join.
For example, to get a list of all indexed columns in a schema, one
could query:


SELECT DISTINCT m.name || '.' || ii.name AS 'indexed-columns'
  FROM sqlite_schema AS m,
       pragma_index_list(m.name) AS il,
       pragma_index_info(il.name) AS ii
 WHERE m.type='table'
 ORDER BY 1;



Additional notes:


Table-valued functions exist only for built-in PRAGMAs, not for PRAGMAs
defined using the SQLITE_FCNTL_PRAGMA file control.

Table-valued functions exist only for PRAGMAs that return results and
that have no side-effects.

This feature could be used to implement
information schema
by first creating a separate schema using

ATTACH ':memory:' AS 'information_schema';

Then creating
VIEWs in that schema that implement the official information schema
tables using table-valued PRAGMA functions.

This feature is experimental and is subject to change.  Further documentation
will become available if and when the table-valued functions for PRAGMAs
feature becomes officially supported.

The table-valued functions for PRAGMA feature was added
in SQLite version 3.16.0 (2017-01-02).  Prior versions of SQLite
cannot use this feature.



List Of PRAGMAs


analysis_limit
application_id
auto_vacuum
automatic_index
busy_timeout
cache_size
cache_spill
case_sensitive_like
cell_size_check
checkpoint_fullfsync
collation_list
compile_options
count_changes&sup1;
data_store_directory&sup1;
data_version
database_list
default_cache_size&sup1;
defer_foreign_keys
empty_result_callbacks&sup1;
encoding
foreign_key_check
foreign_key_list
foreign_keys
freelist_count
full_column_names&sup1;
fullfsync
function_list
hard_heap_limit
ignore_check_constraints
incremental_vacuum
index_info
index_list
index_xinfo
integrity_check
journal_mode
journal_size_limit
legacy_alter_table
legacy_file_format
locking_mode
max_page_count
mmap_size
module_list
optimize
page_count
page_size
parser_trace&sup2;
pragma_list
query_only
quick_check
read_uncommitted
recursive_triggers
reverse_unordered_selects
schema_version&sup3;
secure_delete
short_column_names&sup1;
shrink_memory
soft_heap_limit
stats&sup3;
synchronous
table_info
table_list
table_xinfo
temp_store
temp_store_directory&sup1;
threads
trusted_schema
user_version
vdbe_addoptrace&sup2;
vdbe_debug&sup2;
vdbe_listing&sup2;
vdbe_trace&sup2;
wal_autocheckpoint
wal_checkpoint
writable_schema&sup3;



Notes:

Pragmas whose names are struck through
are deprecated. Do not use them. They exist
for historical compatibility.
These pragmas are only available in builds using non-standard
compile-time options.
These pragmas are used for testing SQLite and are not recommended
for use in application programs.

 PRAGMA analysis_limit
   PRAGMA analysis_limit;
        PRAGMA analysis_limit = N;
   Query or change a limit on the approximate ANALYZE setting.
      This is the approximate number of
      rows examined in each index by the ANALYZE command.
      If the argument N is omitted, then the analysis limit
      is unchanged.
      If the limit is zero, then the analysis limit is disabled and
      the ANALYZE command will examine all rows of each index.
      If N is greater than zero, then the analysis limit is set to N
      and subsequent ANALYZE commands will stop analyzing
      each index after it has examined approximately N rows.
      If N is a negative number or something other than an integer value,
      then the pragma behaves as if the N argument was omitted.
      In all cases, the value returned is the new analysis limit used
      for subsequent ANALYZE commands.
   This pragma can be used to help the ANALYZE command run faster
      on large databases.  The results of analysis are not as good
      when only part of each index is examined, but the results are
      usually good enough.  Setting N to 100 or 1000 allows the
      ANALYZE command to run very quickly, even on multi-gigabyte
      database files.  This pragma is particularly useful in combination
      with PRAGMA optimize.
   This pragma was added in SQLite version 3.32.0 (2020-05-22).
      The current implementation only uses the lower 31 bits of the
      N value - higher order bits are silently ignored.  Future versions
      of SQLite might begin using higher order bits.

 PRAGMA application_id
    PRAGMA schema.application_id;
     PRAGMA schema.application_id = integer ;
  
    The application_id PRAGMA is used to query or set the 32-bit
       signed big-endian "Application ID" integer located at offset
       68 into the database header.  Applications that use SQLite as their
       application file-format should set the Application ID integer to
       a unique integer so that utilities such as 
       file(1) can determine the specific
       file type rather than just reporting "SQLite3 Database".  A list of
       assigned application IDs can be seen by consulting the
       magic.txt file in the SQLite source repository.

   See also the user_version pragma.

 PRAGMA auto_vacuum
    PRAGMA schema.auto_vacuum;
          PRAGMA schema.auto_vacuum = 
           0 | NONE | 1 | FULL | 2 | INCREMENTAL;

    Query or set the auto-vacuum status in the database.

    The default setting for auto-vacuum is 0 or "none",
    unless the SQLITE_DEFAULT_AUTOVACUUM compile-time option is used.
    The "none" setting means that auto-vacuum is disabled.
    When auto-vacuum is disabled and data is deleted data from a database,
    the database file remains the same size.  Unused database file 
    pages are added to a "freelist" and reused for subsequent inserts.  So
    no database file space is lost.  However, the database file does not
    shrink.  In this mode the VACUUM
    command can be used to rebuild the entire database file and
    thus reclaim unused disk space.

    When the auto-vacuum mode is 1  or "full", the freelist pages are
    moved to the end of the database file and the database file is truncated
    to remove the freelist pages at every transaction commit.
    Note, however, that auto-vacuum only truncates the freelist pages
    from the file.  Auto-vacuum does not defragment the database nor
    repack individual database pages the way that the
    VACUUM command does.  In fact, because
    it moves pages around within the file, auto-vacuum can actually
    make fragmentation worse.

    Auto-vacuuming is only possible if the database stores some
    additional information that allows each database page to be
    traced backwards to its referrer.  Therefore, auto-vacuuming must
    be turned on before any tables are created.  It is not possible
    to enable or disable auto-vacuum after a table has been created.

    When the value of auto-vacuum is 2 or "incremental" then the additional
    information needed to do auto-vacuuming is stored in the database file
    but auto-vacuuming does not occur automatically at each commit as it
    does with auto_vacuum=full.  In incremental mode, the separate
    incremental_vacuum pragma must
    be invoked to cause the auto-vacuum to occur.

    The database connection can be changed between full and incremental
    autovacuum mode at any time.  However, changing from
    "none" to "full" or "incremental" can only occur when the database 
    is new (no tables
    have yet been created) or by running the VACUUM command.  To
    change auto-vacuum modes, first use the auto_vacuum pragma to set
    the new desired mode, then invoke the VACUUM command to 
    reorganize the entire database file.  To change from "full" or
    "incremental" back to "none" always requires running VACUUM even
    on an empty database.
    

    When the auto_vacuum pragma is invoked with no arguments, it
    returns the current auto_vacuum mode.

 PRAGMA automatic_index
    PRAGMA automatic_index;
     PRAGMA automatic_index = boolean;

    Query, set, or clear the automatic indexing capability.
    Automatic indexing is enabled by default as of 
    version 3.7.17 (2013-05-20),
    but this might change in future releases of SQLite.

 PRAGMA busy_timeout
    PRAGMA busy_timeout;
         PRAGMA busy_timeout = milliseconds;
    Query or change the setting of the
    busy timeout.
    This pragma is an alternative to the sqlite3_busy_timeout() C-language
    interface which is made available as a pragma for use with language
    bindings that do not provide direct access to sqlite3_busy_timeout().

    Each database connection can only have a single
    busy handler.  This PRAGMA sets the busy handler
    for the process, possibly overwriting any previously set busy handler.

 PRAGMA cache_size
    PRAGMA schema.cache_size;
       PRAGMA schema.cache_size = pages;
       PRAGMA schema.cache_size = -kibibytes;
    Query or change the suggested maximum number of database disk pages
    that SQLite will hold in memory at once per open database file.  Whether
    or not this suggestion is honored is at the discretion of the
    Application Defined Page Cache.
    The default page cache that is built into SQLite honors the request,
    however alternative application-defined page cache implementations
    may choose to interpret the suggested cache size in different ways
    or to ignore it all together.
    The default suggested cache size is -2000, which means the cache size
    is limited to 2048000 bytes of memory.
    The default suggested cache size can be altered using the
    SQLITE_DEFAULT_CACHE_SIZE compile-time options.
    The TEMP database has a default suggested cache size of 0 pages.

    If the argument N is positive then the suggested cache size is set 
    to N. If the argument N is negative, then the
    number of cache pages is adjusted to be a number of pages that would
    use approximately abs(N*1024) bytes of memory based on the current
    page size.  SQLite remembers the number of pages in the page cache,
    not the amount of memory used.  So if you set the cache size using
    a negative number and subsequently change the page size (using the
    PRAGMA page_size command) then the maximum amount of cache
    memory will go up or down in proportion to the change in page size.

    Backwards compatibility note:
    The behavior of cache_size with a negative N
    was different prior to version 3.7.10 (2012-01-16).  In
    earlier versions, the number of pages in the cache was set
    to the absolute value of N.

    When you change the cache size using the cache_size pragma, the
    change only endures for the current session.  The cache size reverts
    to the default value when the database is closed and reopened.

    The default page cache implemention does not allocate
    the full amount of cache memory all at once.  Cache memory
    is allocated in smaller chunks on an as-needed basis.  The page_cache
    setting is a (suggested) upper bound on the amount of memory that the
    cache can use, not the amount of memory it will use all of the time.
    This is the behavior of the default page cache implementation, but an
    application defined page cache is free
    to behave differently if it wants.

 PRAGMA cache_spill
    PRAGMA cache_spill;
         PRAGMA cache_spill=boolean;
         PRAGMA schema.cache_spill=N;

    The cache_spill pragma enables or disables the ability of the pager
    to spill dirty cache pages to the database file in the middle of a 
    transaction.  Cache_spill is enabled by default and most applications
    should leave it that way as cache spilling is usually advantageous.
    However, a cache spill has the side-effect of acquiring an
    EXCLUSIVE lock on the database file.  Hence, some applications that
    have large long-running transactions may want to disable cache spilling
    in order to prevent the application from acquiring an exclusive lock
    on the database until the moment that the transaction COMMITs.
    The "PRAGMA cache_spill=N" form of this pragma sets a minimum
    cache size threshold required for spilling to occur. The number of pages
    in cache must exceed both the cache_spill threshold and the maximum cache
    size set by the PRAGMA cache_size statement in order for spilling to
    occur.
    The "PRAGMA cache_spill=boolean" form of this pragma applies
    across all databases attached to the database connection.  But the
    "PRAGMA cache_spill=N" form of this statement only applies to
    the "main" schema or whatever other schema is specified as part of the
    statement.

 PRAGMA case_sensitive_like
    PRAGMA case_sensitive_like = boolean;
    The default behavior of the LIKE operator is to ignore case
    for ASCII characters. Hence, by default 'a' LIKE 'A' is
    true.  The case_sensitive_like pragma installs a new application-defined
    LIKE function that is either case sensitive or insensitive depending
    on the value of the case_sensitive_like pragma.
    When case_sensitive_like is disabled, the default LIKE behavior is
    expressed.  When case_sensitive_like is enabled, case becomes
    significant.  So, for example,
    'a' LIKE 'A' is false but 'a' LIKE 'a' is still true.

    This pragma uses sqlite3_create_function() to overload the
    LIKE and GLOB functions, which may override previous implementations
    of LIKE and GLOB registered by the application.  This pragma
    only changes the behavior of the SQL LIKE operator.  It does not
    change the behavior of the sqlite3_strlike() C-language interface,
    which is always case insensitive.

 PRAGMA cell_size_check
    PRAGMA cell_size_check
       PRAGMA cell_size_check = boolean;
    The cell_size_check pragma enables or disables additional sanity
    checking on database b-tree pages as they are initially read from disk.
    With cell size checking enabled, database corruption is detected earlier
    and is less likely to "spread".  However, there is a small performance
    hit for doing the extra checks and so cell size checking is turned off
    by default.

 PRAGMA checkpoint_fullfsync
    PRAGMA checkpoint_fullfsync
       PRAGMA checkpoint_fullfsync = boolean;
    Query or change the fullfsync flag for checkpoint operations.
    If this flag is set, then the F_FULLFSYNC syncing method is used
    during checkpoint operations on systems that support F_FULLFSYNC. 
    The default value of the checkpoint_fullfsync flag
    is off.  Only Mac OS-X supports F_FULLFSYNC.

    If the fullfsync flag is set, then the F_FULLFSYNC syncing
    method is used for all sync operations and the checkpoint_fullfsync
    setting is irrelevant.

 PRAGMA collation_list
    PRAGMA collation_list;
    Return a list of the collating sequences defined for the current
    database connection.

 PRAGMA compile_options
    PRAGMA compile_options;
    This pragma returns the names of compile-time options used when
    building SQLite, one option per row.  The "SQLITE_" prefix is omitted
    from the returned option names.  See also the
    sqlite3_compileoption_get() C/C++ interface and the
    sqlite_compileoption_get() SQL functions.

 PRAGMA count_changes
    PRAGMA count_changes;
       PRAGMA count_changes = boolean;

    Query or change the count-changes flag. Normally, when the
    count-changes flag is not set, INSERT, UPDATE and DELETE statements
    return no data. When count-changes is set, each of these commands 
    returns a single row of data consisting of one integer value - the
    number of rows inserted, modified or deleted by the command. The 
    returned change count does not include any insertions, modifications
    or deletions performed by triggers, any changes made automatically
    by foreign key actions, or updates caused by an upsert.

    Another way to get the row change counts is to use the
    sqlite3_changes() or sqlite3_total_changes() interfaces.
    There is a subtle different, though.  When an INSERT, UPDATE, or
    DELETE is run against a view using an INSTEAD OF trigger,
    the count_changes pragma reports the number of rows in the view
    that fired the trigger, whereas sqlite3_changes() and
    sqlite3_total_changes() do not.

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA data_store_directory
    PRAGMA data_store_directory;
      PRAGMA data_store_directory = 'directory-name';
    Query or change the value of the sqlite3_data_directory global
    variable, which windows operating-system interface backends use to
    determine where to store database files specified using a relative
    pathname.

    Changing the data_store_directory setting is not threadsafe.
    Never change the data_store_directory setting if another thread
    within the application is running any SQLite interface at the same time.
    Doing so results in undefined behavior.  Changing the data_store_directory
    setting writes to the sqlite3_data_directory global
    variable and that global variable is not protected by a mutex.

    This facility is provided for WinRT which does not have an OS
    mechanism for reading or changing the current working directory.
    The use of this pragma in any other context is discouraged and may
    be disallowed in future releases.

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA data_version
    PRAGMA schema.data_version;
    The "PRAGMA data_version" command provides an indication that the
    database file has been modified.
    Interactive programs that hold database content in memory or that
    display database content on-screen can use the PRAGMA data_version
    command to determine if they need to flush and reload their memory
    or update the screen display.

    The integer values returned by two
    invocations of "PRAGMA data_version" from the same connection
    will be different if changes were committed to the database 
    by any other connection in the interim.
    The "PRAGMA data_version" value is unchanged for commits made
    on the same database connection.
    The behavior of "PRAGMA data_version" is the same for all database
    connections, including database connections in separate processes
    and shared cache database connections.

    The "PRAGMA data_version" value is a local property of each
    database connection and so values returned by two concurrent invocations
    of "PRAGMA data_version" on separate database connections are 
    often different even though the underlying database is identical.
    It is only meaningful to compare the "PRAGMA data_version" values
    returned by the same database connection at two different points in
    time.

 PRAGMA database_list
    PRAGMA database_list;
    This pragma works like a query to return one row for each database
    attached to the current database connection.
    The second column is "main" for the main database file, "temp"
    for the database file used to store TEMP objects, or the name of the
    ATTACHed database for other database files.
    The third column is the name of the database file itself, or an empty
    string if the database is not associated with a file.

 PRAGMA default_cache_size
    PRAGMA schema.default_cache_size;
       PRAGMA schema.default_cache_size
            = Number-of-pages;

    This pragma queries or sets the suggested maximum number of pages
    of disk cache that will be allocated per open database file.
    The difference between this pragma and cache_size is that the
    value set here persists across database connections.
    The value of the default cache size is stored in the 4-byte
    big-endian integer located at offset 48 in the header of the
    database file.
    

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA defer_foreign_keys
    PRAGMA defer_foreign_keys
       PRAGMA defer_foreign_keys = boolean;
    When the defer_foreign_keys PRAGMA is on,
    enforcement of all foreign key constraints is delayed until the
    outermost transaction is committed.  The defer_foreign_keys pragma
    defaults to OFF so that foreign key constraints are only deferred if
    they are created as "DEFERRABLE INITIALLY DEFERRED".  The 
    defer_foreign_keys pragma is automatically switched off at each
    COMMIT or ROLLBACK.  Hence, the defer_foreign_keys pragma must be
    separately enabled for each transaction.  This pragma is
    only meaningful if foreign key constraints are enabled, of course.

    The sqlite3_db_status(db,SQLITE_DBSTATUS_DEFERRED_FKS,...)
    C-language interface can be used during a transaction to determine 
    if there are deferred and unresolved foreign key constraints.

 PRAGMA empty_result_callbacks
    PRAGMA empty_result_callbacks;
       PRAGMA empty_result_callbacks = boolean;

    Query or change the empty-result-callbacks flag.

    The empty-result-callbacks flag affects the sqlite3_exec() API only.
    Normally, when the empty-result-callbacks flag is cleared, the
    callback function supplied to the sqlite3_exec() is not invoked
    for commands that return zero rows of data.  When empty-result-callbacks
    is set in this situation, the callback function is invoked exactly once,
    with the third parameter set to 0 (NULL). This is to enable programs  
    that use the sqlite3_exec() API to retrieve column-names even when
    a query returns no data.

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA encoding
   PRAGMA encoding;
       PRAGMA encoding = 'UTF-8';
       PRAGMA encoding = 'UTF-16';
       PRAGMA encoding = 'UTF-16le';
       PRAGMA encoding = 'UTF-16be';
    In first form, if the main database has already been
    created, then this pragma returns the text encoding used by the
    main database, one of 'UTF-8', 'UTF-16le' (little-endian UTF-16
    encoding) or 'UTF-16be' (big-endian UTF-16 encoding).  If the main
    database has not already been created, then the value returned is the
    text encoding that will be used to create the main database, if 
    it is created by this session.

    The second through fifth forms of this pragma
    set the encoding that the main database will be created with if
    it is created by this session. The string 'UTF-16' is interpreted
    as "UTF-16 encoding using native machine byte-ordering".  It is not
    possible to change the text encoding of a database after it has been
    created and any attempt to do so will be silently ignored.

    If no encoding is first set with this pragma,
    then the encoding with which the main database will be created
    defaults to one determined by the
    API used to open the connection.

    Once an encoding has been set for a database, it cannot be changed.

    Databases created by the ATTACH command always use the same encoding
    as the main database.  An attempt to ATTACH a database with a different
    text encoding from the "main" database will fail.

 PRAGMA foreign_key_check
    PRAGMA schema.foreign_key_check;
        PRAGMA schema.foreign_key_check(table-name);

    The foreign_key_check pragma checks the database, or the table
    called "table-name", for 
    foreign key constraints that are violated.  The foreign_key_check
    pragma returns one row output for each foreign key violation.
    There are four columns in each result row.
    The first column is the name of the table that contains the REFERENCES
    clause.  The second column is the rowid of the row that
    contains the invalid REFERENCES clause, or NULL if the child table is a
    WITHOUT ROWID table.  The third column is the name
    of the table that is referred to. The fourth column is the index of
    the specific foreign key constraint that failed.  The fourth column
    in the output of the foreign_key_check pragma is the same integer as
    the first column in the output of the foreign_key_list pragma.
    When a "table-name" is specified, the only foreign key constraints
    checked are those created by REFERENCES clauses in the
    CREATE TABLE statement for table-name.

 PRAGMA foreign_key_list
    PRAGMA foreign_key_list(table-name);

    This pragma returns one row for each foreign key constraint
    created by a REFERENCES clause in the CREATE TABLE statement of
    table "table-name".

 PRAGMA foreign_keys
     PRAGMA foreign_keys;
       PRAGMA foreign_keys = boolean;
    Query, set, or clear the enforcement of foreign key constraints.

    This pragma is a no-op within a transaction; foreign key constraint
       enforcement may only be enabled or disabled when there is no pending
       BEGIN or SAVEPOINT.

    Changing the foreign_keys setting affects the execution of
       all statements prepared
       using the database connection, including those prepared before the
       setting was changed. Any existing statements prepared using the legacy 
       sqlite3_prepare() interface may fail with an SQLITE_SCHEMA error
       after the foreign_keys setting is changed.

    As of SQLite version 3.6.19, the default setting for foreign
       key enforcement is OFF.  However, that might change in a future
       release of SQLite.  The default setting for foreign key enforcement
       can be specified at compile-time using the SQLITE_DEFAULT_FOREIGN_KEYS
       preprocessor macro.  To minimize future problems, applications should
       set the foreign key enforcement flag as required by the application
       and not depend on the default setting.

 PRAGMA freelist_count
    PRAGMA schema.freelist_count;
    Return the number of unused pages in the database file.

 PRAGMA full_column_names
    PRAGMA full_column_names;
       PRAGMA full_column_names = boolean;

    Query or change the full_column_names flag. This flag together 
    with the short_column_names flag determine
    the way SQLite assigns names to result columns of SELECT statements.
    Result columns are named by applying the following rules in order:
    
    If there is an AS clause on the result, then the name of
        the column is the right-hand side of the AS clause.
    If the result is a general expression, not a just the name of
        a source table column,
        then the name of the result is a copy of the expression text.
    If the short_column_names pragma is ON, then the name of the
        result is the name of the source table column without the 
        source table name prefix:  COLUMN.
    If both pragmas short_column_names and full_column_names
        are OFF then case (2) applies.
        
    The name of the result column is a combination of the source table
        and source column name:  TABLE.COLUMN
    

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA fullfsync
    PRAGMA fullfsync
       PRAGMA fullfsync = boolean;
    Query or change the fullfsync flag. This flag
    determines whether or not the F_FULLFSYNC syncing method is used
    on systems that support it.  The default value of the fullfsync flag
    is off.  Only Mac OS X supports F_FULLFSYNC.

    See also checkpoint_fullfsync.

 PRAGMA function_list
    PRAGMA function_list;
    This pragma returns a list of SQL functions
    known to the database connection.  Each row of the result
    describes a single calling signature for a single SQL function.
    Some SQL functions will have multiple rows in the result set
    if they can (for example) be invoked with a varying number of
    arguments or can accept text in various encodings.

 PRAGMA hard_heap_limit
    PRAGMA hard_heap_limit
          PRAGMA hard_heap_limit=N

    This pragma invokes the sqlite3_hard_heap_limit64() interface with
    the argument N, if N is specified and N is a positive integer that
    is less than the current hard heap limit.
    The hard_heap_limit pragma always returns the same integer
    that would be returned by the sqlite3_hard_heap_limit64(-1) C-language
    function.  That is to say, it always returns the value of the hard
    heap limit that is set after any changes imposed by this PRAGMA.
    

    This pragma can only lower the heap limit, never raise it.
    The C-language interface sqlite3_hard_heap_limit64() must be used
    to raise the heap limit.

    See also the soft_heap_limit pragma.

 PRAGMA ignore_check_constraints
    PRAGMA ignore_check_constraints  = boolean;

    This pragma enables or disables the enforcement of CHECK constraints.
    The default setting is off, meaning that CHECK constraints are
    enforced by default.

 PRAGMA incremental_vacuum
    PRAGMA schema.incremental_vacuum(N);
      PRAGMA schema.incremental_vacuum;
    The incremental_vacuum pragma causes up to N pages to
    be removed from the freelist.  The database file is truncated by
    the same amount.  The incremental_vacuum pragma has no effect if
    the database is not in
    auto_vacuum=incremental mode
    or if there are no pages on the freelist.  If there are fewer than
    N pages on the freelist, or if N is less than 1, or
    if the "(N)" argument is omitted, then the entire
    freelist is cleared.

 PRAGMA index_info
    PRAGMA schema.index_info(index-name);
    This pragma returns one row for each key column in the named index.
    A key column is a column that is actually named in the CREATE INDEX
    index statement or UNIQUE constraint or PRIMARY KEY constraint that
    created the index.  Index entries also usually contain auxiliary
    columns that point back to the table row being indexed.  The auxiliary
    index-columns are not shown by the index_info pragma, but they are
    listed by the index_xinfo pragma.

    Output columns from the index_info pragma are as follows:
    
    The rank of the column within the index.  (0 means left-most.)
    The rank of the column within the table being indexed.
        A value of -1 means rowid and a value of -2 means that an
        expression is being used.
    The name of the column being indexed.  This columns is NULL
        if the column is the rowid or an expression.
    

    If there is no index named index-name but there is a
    WITHOUT ROWID table with that name, then (as of
    SQLite version 3.30.0 on 2019-10-04) this pragma returns the
    PRIMARY KEY columns of the WITHOUT ROWID table as they are used
    in the records of the underlying b-tree, which is to say with
    duplicate columns removed.

 PRAGMA index_list
    PRAGMA schema.index_list(table-name);
    This pragma returns one row for each index associated with the
    given table.
    Output columns from the index_list pragma are as follows:
    
    A sequence number assigned to each index for internal tracking
          purposes.
    The name of the index.
    "1" if the index is UNIQUE and "0" if not.
    "c" if the index was created by a CREATE INDEX statement,
          "u" if the index was created by a UNIQUE constraint, or
          "pk" if the index was created by a PRIMARY KEY constraint.
    "1" if the index is a partial index and "0" if not.
    
    

 PRAGMA index_xinfo
    PRAGMA schema.index_xinfo(index-name);
    This pragma returns information about every column in an index.
    Unlike this index_info pragma, this pragma returns information about
    every column in the index, not just the key columns.
    (A key column is a column that is actually named in the CREATE INDEX
    index statement or UNIQUE constraint or PRIMARY KEY constraint that
    created the index.  Auxiliary columns are additional columns needed to
    locate the table entry that corresponds to each index entry.)

    Output columns from the index_xinfo pragma are as follows:
    
    The rank of the column within the index. (0 means left-most.
         Key columns come before auxiliary columns.)
    The rank of the column within the table being indexed, or -1 if
         the index-column is the rowid of the table being indexed and -2
         if the index is on an expression.
    The name of the column being indexed, or NULL if the index-column
         is the rowid of the table being indexed or an
         expression.
    1 if the index-column is sorted in reverse (DESC) order by the
         index and 0 otherwise.
    The name for the collating sequence
         used to compare values in the index-column.
    1 if the index-column is a key column and 0 if the index-column
         is an auxiliary column.
    

    If there is no index named index-name but there is a
    WITHOUT ROWID table with that name, then (as of
    SQLite version 3.30.0 on 2019-10-04) this pragma returns the
    columns of the WITHOUT ROWID table as they are used
    in the records of the underlying b-tree, which is to say with
    de-duplicated PRIMARY KEY columns first followed by data columns.

 PRAGMA integrity_check
    PRAGMA schema.integrity_check;
      PRAGMA schema.integrity_check(N)
      PRAGMA schema.integrity_check(TABLENAME)
    This pragma does a low-level formatting and consistency check
    of the database.  The integrity_check pragma look for:
    
     Table or index entries that are out of sequence
     Misformatted records
     Missing pages
     Missing or surplus index entries
     UNIQUE, CHECK, and NOT NULL constraint errors
     Integrity of the freelist
     Sections of the database that are used more than once, or not at all
    
    If the integrity_check pragma finds problems, strings are returned
    (as multiple rows with a single column per row) which describe
    the problems.  Pragma integrity_check will return at most N
    errors before the analysis quits, with N defaulting
    to 100.  If pragma integrity_check finds no errors, a
    single row with the value 'ok' is returned.

    The usual case is that the entire database file is checked.  However,
    if the argument is TABLENAME, then checking is only performed for the
    the table named and its associated indexes.
    This is called a "partial integrity check".  Because only a subset of the
    database is checked, errors such as unused sections of the file or duplication
    use of the same section of the file by two or more tables cannot be detected.
    The freelist is only verified on a
    partial integrity check if TABLENAME is sqlite_schema or one of its
    aliases.  Support for partial integrity checks was added with
    version 3.33.0 (2020-08-14).

    PRAGMA integrity_check does not find
    FOREIGN KEY errors.  
    Use the PRAGMA foreign_key_check command to find errors in
    FOREIGN KEY constraints.

    See also the PRAGMA quick_check command which does most of the
    checking of PRAGMA integrity_check but runs much faster.

 PRAGMA journal_mode
    PRAGMA schema.journal_mode;
        PRAGMA schema.journal_mode
              = DELETE | TRUNCATE | PERSIST | MEMORY | WAL | OFF

    This pragma queries or sets the journal mode for databases
    associated with the current database connection.

    The first form of this pragma queries the current journaling
    mode for database.  When database is omitted, the
    "main" database is queried.

    The second form changes the journaling mode for "database"
    or for all attached databases if "database" is omitted.
    The new journal mode is returned.  If the journal mode
    could not be changed, the original journal mode is returned.

    The DELETE journaling mode is the normal behavior.  In the DELETE
    mode, the rollback journal is deleted at the conclusion of each
    transaction.  Indeed, the delete operation is the action that causes
    the transaction to commit.
    (See the document titled 
    Atomic Commit In SQLite for additional detail.)

    The TRUNCATE journaling mode commits transactions by truncating
    the rollback journal to zero-length instead of deleting it.  On many
    systems, truncating a file is much faster than deleting the file since
    the containing directory does not need to be changed.

    The PERSIST journaling mode prevents the rollback journal from
    being deleted at the end of each transaction.  Instead, the header
    of the journal is overwritten with zeros.  This will prevent other
    database connections from rolling the journal back.  The PERSIST
    journaling mode is useful as an optimization on platforms where
    deleting or truncating a file is much more expensive than overwriting
    the first block of a file with zeros.  See also:
    PRAGMA journal_size_limit and SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT.

    The MEMORY journaling mode stores the rollback journal in 
    volatile RAM.  This saves disk I/O but at the expense of database
    safety and integrity.  If the application using SQLite crashes in
    the middle of a transaction when the MEMORY journaling mode is set,
    then the database file will very likely 
    go corrupt.

    The WAL journaling mode uses a write-ahead log instead of a
    rollback journal to implement transactions.  The WAL journaling mode
    is persistent; after being set it stays in effect
    across multiple database connections and after closing and
    reopening the database.  A database in WAL journaling mode
    can only be accessed by SQLite version 3.7.0 (2010-07-21)
    or later.

    The OFF journaling mode disables the rollback journal completely.
    No rollback journal is ever created and hence there is never a rollback
    journal to delete.  The OFF journaling mode disables the atomic
    commit and rollback capabilities of SQLite. The ROLLBACK command
    no longer works; it behaves in an undefined way.  Applications must
    avoid using the ROLLBACK command when the journal mode is OFF.
    If the application crashes
    in the middle of a transaction when the OFF journaling mode is
    set, then the database file will very likely
    go corrupt. Without a journal, there is no way for
    a statement to unwind partially completed operations following
    a constraint error.  This might also leave the database in a corrupted
    state.  For example, if a duplicate entry causes a 
    CREATE UNIQUE INDEX statement to fail half-way through,
    it will leave behind a partially created, and hence corrupt, index.
    Because OFF journaling
    mode allows the database file to be corrupted using ordinary SQL,
    it is disabled when SQLITE_DBCONFIG_DEFENSIVE is enabled.

    Note that the journal_mode for an in-memory database
    is either MEMORY or OFF and can not be changed to a different value.
    An attempt to change the journal_mode of an in-memory database to
    any setting other than MEMORY or OFF is ignored.  Note also that
    the journal_mode cannot be changed while a transaction is active.

 PRAGMA journal_size_limit
    
    PRAGMA schema.journal_size_limit
    PRAGMA schema.journal_size_limit = N ;

  If a database connection is operating in
  exclusive locking mode or in
  persistent journal mode 
  (PRAGMA journal_mode=persist) then
  after committing a transaction the rollback journal file may remain in
  the file-system. This increases performance for subsequent transactions
  since overwriting an existing file is faster than append to a file,
  but it also consumes
  file-system space. After a large transaction (e.g. a VACUUM),
  the rollback journal file may consume a very large amount of space.

  Similarly, in WAL mode, the write-ahead log file is not truncated
  following a checkpoint.  Instead, SQLite reuses the existing file
  for subsequent WAL entries since overwriting is faster than appending.

  The journal_size_limit pragma may be used to limit the size of 
  rollback-journal and WAL files left
  in the file-system after transactions or checkpoints.
  Each time a transaction is committed or a WAL file resets, SQLite 
  compares the size of the rollback journal file or WAL file left in 
  the file-system to the size limit
  set by this pragma and if the journal or WAL file is larger 
  it is truncated to the limit.

  The second form of the pragma listed above is used to set a new limit
  in bytes for the specified database.  A negative number implies no limit.
  To always truncate rollback journals and WAL files to their minimum size, 
  set the journal_size_limit to zero.
  Both the first and second forms of the pragma listed above return a single
  result row containing a single integer column - the value of the journal
  size limit in bytes. The default journal size limit is -1 (no limit).  The
  SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT preprocessor macro can be used to change
  the default journal size limit at compile-time.

  This pragma only operates on the single database specified prior
  to the pragma name (or on the "main" database if no database is specified.)
  There is no way to change the journal size limit on all attached databases
  using a single PRAGMA statement.  The size limit must be set separately for
  each attached database.

 PRAGMA legacy_alter_table
   PRAGMA legacy_alter_table;
       PRAGMA legacy_alter_table = boolean
    This pragma sets or queries the value of the legacy_alter_table
    flag.  When this flag is on, the ALTER TABLE RENAME
    command (for changing the name of a table) works as it did
    in SQLite 3.24.0 (2018-06-04) and earlier.  More specifically,
    when this flag is on
    the ALTER TABLE RENAME command only rewrites the initial occurrence
    of the table name in its CREATE TABLE statement and in any associated
    CREATE INDEX and CREATE TRIGGER statements.  Other references to the
    table are unmodified, including:
    
     References to the table within the bodies of triggers and views.
     References to the table within CHECK constraints in the original
         CREATE TABLE statement.
     References to the table within the WHERE clauses of partial indexes.
    
    The default setting for this pragma is OFF, which means that all
    references to the table anywhere in the schema are converted to the new name.
    This pragma is provided as a work-around for older programs that
    contain code that expect the incomplete behavior
    of ALTER TABLE RENAME found in older versions of SQLite.
    New applications should leave this flag turned off.
    For compatibility with older virtual table implementations,
    this flag is turned on temporarily while the sqlite3_module.xRename
    method is being run.  The value of this flag is restored after the 
    sqlite3_module.xRename method finishes.
    The legacy alter table behavior can also be toggled on and off
    using the SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option to the
    sqlite3_db_config() interface.
    The legacy alter table behavior is a per-connection setting.  Turning
    this features on or off affects all attached database files within the
    database connection.
    The setting does not persist.  Changing this setting in one connection
    does not affect any other connections.

 PRAGMA legacy_file_format
   PRAGMA legacy_file_format;
    This pragma no longer functions.  It has become a no-op.
    The capabilities formerly provided by PRAGMA legacy_file_format
    are now available using the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
    option to the sqlite3_db_config() C-language interface.
    

 PRAGMA locking_mode
    PRAGMA schema.locking_mode;
    PRAGMA schema.locking_mode
                = NORMAL | EXCLUSIVE
    This pragma sets or queries the database connection locking-mode. 
    The locking-mode is either NORMAL or EXCLUSIVE.

    In NORMAL locking-mode (the default unless overridden at compile-time
    using SQLITE_DEFAULT_LOCKING_MODE), a database connection
    unlocks the database file at the conclusion of each read or
    write transaction. When the locking-mode is set to EXCLUSIVE, the
    database connection never releases file-locks. The first time the
    database is read in EXCLUSIVE mode, a shared lock is obtained and 
    held. The first time the database is written, an exclusive lock is
    obtained and held.

    Database locks obtained by a connection in EXCLUSIVE mode may be
    released either by closing the database connection, or by setting the
    locking-mode back to NORMAL using this pragma and then accessing the
    database file (for read or write). Simply setting the locking-mode to
    NORMAL is not enough - locks are not released until the next time
    the database file is accessed.

    There are three reasons to set the locking-mode to EXCLUSIVE.
    
    The application wants to prevent other processes from
        accessing the database file.
    The number of system calls for filesystem operations is reduced,
        possibly resulting in a small performance increase.
    WAL databases can be accessed in EXCLUSIVE mode without the
        use of shared memory. 
        (Additional information)
    
    

    When the locking_mode pragma specifies a particular database,
    for example:

    
PRAGMA main.locking_mode=EXCLUSIVE;
    

    then the locking mode applies only to the named database.  If no
    database name qualifier precedes the "locking_mode" keyword then
    the locking mode is applied to all databases, including any new
    databases added by subsequent ATTACH commands.

   The "temp" database (in which TEMP tables and indices are stored)
   and in-memory databases
   always uses exclusive locking mode.  The locking mode of temp and
   in-memory databases cannot
   be changed.  All other databases use the normal locking mode by default
   and are affected by this pragma.

   If the locking mode is EXCLUSIVE when first entering
   WAL journal mode, then the locking mode cannot be changed to
   NORMAL until after exiting WAL journal mode. 
   If the locking mode is NORMAL when first entering WAL
   journal mode, then the locking mode can be changed between NORMAL and
   EXCLUSIVE and back again at any time and without needing to exit
   WAL journal mode.

 PRAGMA max_page_count
    PRAGMA schema.max_page_count;
        PRAGMA schema.max_page_count = N;
    Query or set the maximum number of pages in the database file.
    Both forms of the pragma return the maximum page count.  The second
    form attempts to modify the maximum page count.  The maximum page
    count cannot be reduced below the current database size.
    

 PRAGMA mmap_size
    PRAGMA schema.mmap_size;
         PRAGMA schema.mmap_size=N

    Query or change the maximum number of bytes that are set
       aside for memory-mapped I/O on a single database.  The first form
       (without an argument) queries the current limit.  The second
       form (with a numeric argument) sets the limit for the specified
       database, or for all databases if the optional database name is
       omitted.  In the second form, if the database name is omitted, the
       limit that is set becomes the default limit for all databases that
       are added to the database connection by subsequent ATTACH
       statements.

    The argument N is the maximum number of bytes of the database file
       that will be accessed using memory-mapped I/O.  If N is zero then
       memory mapped I/O is disabled.  If N is negative, then the limit
       reverts to the default value determined by the most recent
       sqlite3_config(SQLITE_CONFIG_MMAP_SIZE), or to the compile
       time default determined by SQLITE_DEFAULT_MMAP_SIZE if not
       start-time limit has been set.

    The PRAGMA mmap_size statement will never increase the amount
       of address space used for memory-mapped I/O above the
       hard limit set by the SQLITE_MAX_MMAP_SIZE compile-time option,
       nor the hard limit set at startup-time by the second argument to
       sqlite3_config(SQLITE_CONFIG_MMAP_SIZE)

    The size of the memory-mapped I/O region cannot be changed while
       the memory-mapped I/O region is in active use, to avoid unmapping
       memory out from under running SQL statements.  For this reason,
       the mmap_size pragma may be a no-op if the prior mmap_size is non-zero
       and there are other SQL statements running concurrently on the same
       database connection.

 PRAGMA module_list
    PRAGMA module_list;
    This pragma returns a list of 
    virtual table modules registered with the database connection.

 PRAGMA optimize
  PRAGMA optimize;
       PRAGMA optimize(MASK);
       PRAGMA schema.optimize;
       PRAGMA schema.optimize(MASK);
  Attempt to optimize the database.  All schemas are optimized in the 
  first two forms, and only the specified schema is optimized in the latter
  two.
  To achieve the best long-term query performance without the need to
  do a detailed engineering analysis of the application schema and SQL,
  it is recommended that applications run "PRAGMA optimize" (with no arguments)
  just before closing each database connection.  Long-running applications
  might also benefit from setting a timer to run "PRAGMA optimize" every
  few hours.
  
  This pragma is usually a no-op or nearly so and is very fast.
  However if SQLite feels
  that performing database optimizations (such as running ANALYZE
  or creating new indexes) will improve the performance of future queries, then
  some database I/O may be done.  Applications that want to limit the amount
  of work performed can set a timer that will invoke
  sqlite3_interrupt() if the pragma goes on for too long.
  Or, since SQLite 3.32.0, the application can use 
  PRAGMA analysis_limit=N for some small
  value of N (a few hundred or a few thousand) to limit the depth
  of analyze.
  
  The details of optimizations performed by this pragma are expected
  to change and improve over time.  Applications should anticipate that
  this pragma will perform new optimizations in future releases.

  The optional MASK argument is a bitmask of optimizations to perform:
  
  
         Debugging mode.  Do not actually perform any optimizations
         but instead return one line of text for each optimization
         that would have been done.  Off by default.
  
         Run ANALYZE on tables that might benefit.  On by default.
         See below for additional information.
  
         (Not yet implemented)
         Record usage and performance 
         information from the current session in the
         database file so that it will be available to "optimize"
         pragmas run by future database connections.
  
         (Not yet implemented)
         Create indexes that might have been helpful to recent queries.
  
  The default MASK is and always shall be 0xfffe.  The 0xfffe mask means
  perform all of the optimizations listed above except Debug Mode.  If new
  optimizations are added in the future that should be off by default, those
  new optimizations will be given a mask of 0x10000 or larger.

  To see all optimizations that would have been done without actually
  doing them, run "PRAGMA optimize(-1)".  To use only the ANALYZE
  optimization, run "PRAGMA optimize(0x02)".
  
  Determination Of When To Run Analyze
   In the current implementation, a table is analyzed if and only if 
      all of the following are true:
  
  
    MASK bit 0x02 is set.
  
    The query planner used sqlite_stat1-style statistics for one or
    more indexes of the table at some point during the lifetime of
    the current connection.
  
    One or more indexes of the table are currently unanalyzed or
    the number of rows in the table has increased by 25 times or more
    since the last time ANALYZE was run.
  
   The rules for when tables are analyzed are likely to change in
      future releases.

 PRAGMA page_count
    PRAGMA schema.page_count;
    Return the total number of pages in the database file.

 PRAGMA page_size
   PRAGMA schema.page_size;
       PRAGMA schema.page_size = bytes;
    Query or set the page size of the database. The page
    size must be a power of two between 512 and 65536 inclusive.
    

    When a new database is created, SQLite assigns a page size to
    the database based on platform and filesystem.  For many years,
    the default page size was almost always 1024 bytes, but beginning
    with SQLite version 3.12.0 (2016-03-29), 
    the default page size increased to 4096.
    The default page size is recommended for most applications.

    Specifying a new page size does not change the page size
    immediately.  Instead, the new page size is remembered and is used
    to set the page size when the database is first created, if it does
    not already exist when the page_size pragma is issued, or at the
    next VACUUM command that is run on the same database connection
    while not in WAL mode.

    The SQLITE_DEFAULT_PAGE_SIZE compile-time option can be used
    to change the default page size assigned to new databases.

 PRAGMA parser_trace
    PRAGMA parser_trace = boolean; 

    If SQLite has been compiled with the SQLITE_DEBUG compile-time
    option, then the parser_trace pragma can be used to turn on tracing
    for the SQL parser used internally by SQLite.
    This feature is used for debugging SQLite itself.

    
    
    This pragma is intended for use when debugging SQLite itself.  It
    is only available when the SQLITE_DEBUG compile-time option
    is used.
  

 PRAGMA pragma_list
    PRAGMA pragma_list;
    This pragma returns a list of PRAGMA commands
    known to the database connection.

 PRAGMA query_only
    PRAGMA query_only;
      PRAGMA query_only = boolean;

    The query_only pragma prevents data changes on database files when
    enabled.  When this pragma is enabled, any attempt to CREATE, DELETE,
    DROP, INSERT, or UPDATE will result in an SQLITE_READONLY error.
    However, the database is not truly read-only.  You can still run
    a checkpoint or a COMMIT and the return value of the
    sqlite3_db_readonly() routine is not affected.
     

 PRAGMA quick_check
    PRAGMA schema.quick_check;
      PRAGMA schema.quick_check(N)
      PRAGMA schema.quick_check(TABLENAME)
    The pragma is like integrity_check except that it does not verify
    UNIQUE constraints and does not verify
    that index content matches table content.  By skipping UNIQUE
    and index consistency checks, quick_check is able to run faster.
    PRAGMA quick_check runs in O(N) time whereas PRAGMA integrity_check
    requires O(NlogN) time where N is the total number of rows in the 
    database. Otherwise the two pragmas are the same.
    

 PRAGMA read_uncommitted
    PRAGMA read_uncommitted;
       PRAGMA read_uncommitted = boolean;
    Query, set, or clear READ UNCOMMITTED isolation. The default isolation
    level for SQLite is SERIALIZABLE.  Any process or thread can select
    READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except
    between connections that share a common page and schema cache.
    Cache sharing is enabled using the sqlite3_enable_shared_cache() API.
    Cache sharing is disabled by default.
    

    See SQLite Shared-Cache Mode for additional information.

 PRAGMA recursive_triggers
    PRAGMA recursive_triggers;
       PRAGMA recursive_triggers = boolean;
    Query, set, or clear the recursive trigger capability.

    Changing the recursive_triggers setting affects the execution of
       all statements prepared
       using the database connection, including those prepared before the
       setting was changed. Any existing statements prepared using the legacy 
       sqlite3_prepare() interface may fail with an SQLITE_SCHEMA error
       after the recursive_triggers setting is changed.

    Prior to SQLite version 3.6.18 (2009-09-11), 
    recursive triggers were not supported.
    The behavior of SQLite was always as if this pragma was
    set to OFF.  Support for recursive triggers was added in version 3.6.18
    but was initially turned OFF by default, for compatibility.  Recursive
    triggers may be turned on by default in future versions of SQLite.
    

    The depth of recursion for triggers has a hard upper limit set by
    the SQLITE_MAX_TRIGGER_DEPTH compile-time option and a run-time
    limit set by sqlite3_limit(db,SQLITE_LIMIT_TRIGGER_DEPTH,...).

 PRAGMA reverse_unordered_selects
    PRAGMA reverse_unordered_selects;
       PRAGMA reverse_unordered_selects = boolean;
    When enabled, this PRAGMA causes many SELECT statements without
    an ORDER BY clause to emit their results in the reverse order from what
    they normally would.  This can help debug applications that are
    making invalid assumptions about the result order.  
    The reverse_unordered_selects pragma works for most SELECT statements,
    however the query planner may sometimes choose an algorithm that is
    not easily reversed, in which case the output will appear in the same
    order regardless of the reverse_unordered_selects setting.
    SQLite makes no
    guarantees about the order of results if a SELECT omits the ORDER BY
    clause.  Even so, the order of results does not change from one
    run to the next, and so many applications mistakenly come to depend
    on the arbitrary output order whatever that order happens to be.  However, 
    sometimes new versions of SQLite will contain optimizer enhancements
    that will cause the output order of queries without ORDER BY clauses
    to shift.  When that happens, applications that depend on a certain
    output order might malfunction.  By running the application multiple
    times with this pragma both disabled and enabled, cases where the
    application makes faulty assumptions about output order can be
    identified and fixed early, reducing problems
    that might be caused by linking against a different version of SQLite.
    

 PRAGMA schema_version
    PRAGMA schema.schema_version; 
      PRAGMA schema.schema_version = integer ;

   The schema_version pragma will get or set
       the value of the schema-version integer at offset 40 in the
       database header. 

    SQLite automatically increments the schema-version whenever the
       schema changes. As each SQL statement runs, the schema version is
       checked to ensure that the schema has not changed since the SQL
       statement was prepared.
       Subverting this mechanism by using "PRAGMA schema_version"
       may cause SQL statement to run using an obsolete schema,
       which can lead to incorrect answers and/or
       database corruption.

       
    
    Warning:
    Misuse of this pragma can result in database corruption.
    
  

    For the purposes of this pragma, the VACUUM command is considered
       a schema change, since VACUUM will usually alter the "rootpage"
       values for entries in the sqlite_schema table.


    See also the application_id pragma and user_version pragma.

 PRAGMA secure_delete
    PRAGMA schema.secure_delete;
     PRAGMA schema.secure_delete = boolean|FAST
    Query or change the secure-delete setting. When secure_delete is
    on, SQLite overwrites deleted content with zeros.  The default
    setting for secure_delete is determined by the SQLITE_SECURE_DELETE
    compile-time option and is normally off.  The off setting for
    secure_delete improves performance by reducing the number of CPU cycles
    and the amount of disk I/O.  Applications that wish to avoid leaving
    forensic traces after content is deleted or updated should enable the
    secure_delete pragma prior to performing the delete or update, or else
    run VACUUM after the delete or update.

    The "fast" setting for secure_delete (added circa 2017-08-01)
    is an intermediate setting in between "on" and "off".
    When secure_delete is set to "fast",
    SQLite will overwrite deleted content with zeros only if doing so
    does not increase the amount of I/O.  In other words, the "fast"
    setting uses more CPU cycles but does not use more I/O.
    This has the effect of purging all old content from b-tree pages,
    but leaving forensic traces on freelist pages.

    
    When there are attached databases and no database
    is specified in the pragma, all databases have their secure-delete
    setting altered.
    The secure-delete setting for newly attached databases is the setting
    of the main database at the time the ATTACH command is evaluated.

    
    When multiple database connections share the same cache, changing
    the secure-delete flag on one database connection changes it for them
    all.
    

 PRAGMA short_column_names
    PRAGMA short_column_names;
       PRAGMA short_column_names = boolean;

    Query or change the short-column-names flag. This flag affects
    the way SQLite names columns of data returned by SELECT statements.
    See the full_column_names pragma for full details.
    

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA shrink_memory
    PRAGMA shrink_memory

    This pragma causes the database connection on which it is invoked
    to free up as much memory as it can, by calling
    sqlite3_db_release_memory().
    

 PRAGMA soft_heap_limit
    PRAGMA soft_heap_limit
          PRAGMA soft_heap_limit=N

    This pragma invokes the sqlite3_soft_heap_limit64() interface with
    the argument N, if N is specified and is a non-negative integer.
    The soft_heap_limit pragma always returns the same integer
    that would be returned by the sqlite3_soft_heap_limit64(-1) C-language
    function.
    
    See also the hard_heap_limit pragma.

 PRAGMA stats
    PRAGMA stats; 
    This pragma returns auxiliary information about tables and
    indices.  The returned information is used during testing to help
    verify that the query planner is operating correctly.  The format
    and meaning of this pragma will likely change from one release
    to the next. Because of its volatility, the behavior and output
    format of this pragma are deliberately undocumented.

    
    
    The intended use of this pragma is only for testing and validation of
    SQLite.  This pragma is subject to change without notice and is not
    recommended for use by application programs.
  

 PRAGMA synchronous
    PRAGMA schema.synchronous;
        PRAGMA schema.synchronous = 
          0 | OFF | 1 | NORMAL | 2 | FULL | 3 | EXTRA;

    Query or change the setting of the "synchronous" flag.
    The first (query) form will return the synchronous setting as an 
    integer.  The second form changes the synchronous setting.
    The meanings of the various synchronous settings are as follows:
    
    EXTRA (3)
    
    EXTRA synchronous is like FULL with the addition that the directory
    containing a rollback journal is synced after that journal is unlinked
    to commit a transaction in DELETE mode.  EXTRA provides additional
    durability if the commit is followed closely by a power loss.
    FULL (2)
    
    When synchronous is FULL (2), the SQLite database engine will
    use the xSync method of the VFS to ensure that all content is safely
    written to the disk surface prior to continuing.
    This ensures that an operating system crash or power failure will
    not corrupt the database.
    FULL synchronous is very safe, but it is also slower.  FULL is the
    most commonly used synchronous setting when not in WAL mode.
    NORMAL (1)
    
    When synchronous is NORMAL (1), the SQLite database
    engine will still sync at the most critical moments, but less often
    than in FULL mode.  There is a very small (though non-zero) chance that
    a power failure at just the wrong time could corrupt the database in
    journal_mode=DELETE on an older filesystem.
    WAL mode is safe from corruption with synchronous=NORMAL, and probably
    DELETE mode is safe too on modern filesystems.  WAL mode is always consistent
    with synchronous=NORMAL, but WAL mode does lose durability.  A transaction
    committed in WAL mode with synchronous=NORMAL might roll back following
    a power loss or system crash.  Transactions are durable across application
    crashes regardless of the synchronous setting or journal mode.
    The synchronous=NORMAL setting is a good choice for most applications
    running in WAL mode.
    OFF (0)
    
    With synchronous OFF (0), SQLite continues without syncing
    as soon as it has handed data off to the operating system.
    If the application running SQLite crashes, the data will be safe, but
    the database might become corrupted if the operating system
    crashes or the computer loses power before that data has been written
    to the disk surface.  On the other hand, commits can be orders of
    magnitude faster with synchronous OFF.
    
    
 
    In WAL mode when synchronous is NORMAL (1), the WAL file is
    synchronized before each checkpoint and the database file is
    synchronized after each completed checkpoint and the WAL file
    header is synchronized when a WAL file begins to be reused after
    a checkpoint, but no sync operations occur during most transactions.
    With synchronous=FULL in WAL mode, an additional
    sync operation of the WAL file happens after each transaction commit.
    The extra WAL sync following each transaction helps ensure that 
    transactions are durable across a power loss.  Transactions are
    consistent with or without the extra syncs provided by
    synchronous=FULL.
    If durability is not a concern, then synchronous=NORMAL is normally
    all one needs in WAL mode.

    The TEMP schema always has synchronous=OFF since the content of
    of TEMP is ephemeral and is not expected to survive a power outage.
    Attempts to change the synchronous setting for TEMP are
    silently ignored.

    See also the fullfsync and checkpoint_fullfsync pragmas.

 PRAGMA table_info
    PRAGMA schema.table_info(table-name);
    This pragma returns one row for each column in the named table.
    Columns in the result set include the column name,
    data type, whether or not the column can be NULL, and the default
    value for the column.  The "pk" column in the result set is zero
    for columns that are not part of the primary key, and is the index of
    the column in the primary key for columns that are part of the primary
    key.
    The table named in the table_info pragma can also be a view.
    See also: PRAGMA table_xinfo

 PRAGMA table_list
     PRAGMA table_list;
         PRAGMA schema.table_list;
         PRAGMA table_list(table-name);
    This pragma returns information about the tables and views in the schema,
    one table per row of output.  The table_list pragma first appeared
    in SQLite version 3.37.0 (2021-11-27).  As of its initial release
    the columns returned by the table_list pragma include those listed below.
    Future versions of SQLite will probably add additional columns of
    output.
    
    
     schema: the schema in which the table or view appears
    (for example "main" or "temp").
     name: the name of the table or view.
     type: the type of object - one of "table", "view",
           "shadow" (for shadow tables), or "virtual" for
           virtual tables.
     ncol: the number of columns in the table, including
         generated columns and hidden columns.
     wr: 1 if the table is a WITHOUT ROWID table or 0 if is not.
     strict: 1 if the table is a STRICT table or 0 if it is not.
     Additional columns will likely be added in future releases.
    
    
    The default behavior is to show all tables in all schemas.  If the
    schema. name appears before the pragma, then only tables in that
    one schema are shown.  If a table-name argument is supplied, then
    only information about that one table is returned.

 PRAGMA table_xinfo
    PRAGMA schema.table_xinfo(table-name);
    This pragma returns one row for each column in the named table,
    including hidden columns in virtual tables.
    The output is the same as for PRAGMA table_info except that
    hidden columns are shown rather than being omitted.

 PRAGMA temp_store
    PRAGMA temp_store;
        PRAGMA temp_store = 
            0 | DEFAULT | 1 | FILE | 2 | MEMORY;

    Query or change the setting of the "temp_store" parameter.
    When temp_store is DEFAULT (0), the compile-time C preprocessor macro
    SQLITE_TEMP_STORE is used to determine where temporary tables and indices
    are stored.  When
    temp_store is MEMORY (2) temporary tables and indices are kept
    as if they were in pure in-memory databases.
    When temp_store is FILE (1) temporary tables and indices are stored
    in a file.  The temp_store_directory pragma can be used to specify
    the directory containing temporary files when
    FILE is specified.  When the temp_store setting is changed,
    all existing temporary tables, indices, triggers, and views are
    immediately deleted.

    It is possible for the library compile-time C preprocessor symbol
    SQLITE_TEMP_STORE to override this pragma setting.
    The following table summarizes
    the interaction of the SQLITE_TEMP_STORE preprocessor macro and the
    temp_store pragma:

    
    
    SQLITE_TEMP_STORE
        PRAGMAtemp_store
        Storage used forTEMP tables and indices
    0
        any
        file
    1
        0
        file
    1
        1
        file
    1
        2
        memory
    2
        0
        memory
    2
        1
        file
    2
        2
        memory
    3
        any
        memory
    
    

 PRAGMA temp_store_directory
    PRAGMA temp_store_directory;
      PRAGMA temp_store_directory = 'directory-name';
    Query or change the value of the sqlite3_temp_directory global
    variable, which many operating-system interface backends use to
    determine where to store temporary tables and indices.

    When the temp_store_directory setting is changed, all existing temporary
    tables, indices, triggers, and viewers in the database connection that
    issued the pragma are immediately deleted.  In
    practice, temp_store_directory should be set immediately after the first
    database connection for a process is opened.  If the temp_store_directory
    is changed for one database connection while other database connections
    are open in the same process, then the behavior is undefined and
    probably undesirable.

    Changing the temp_store_directory setting is not threadsafe.
    Never change the temp_store_directory setting if another thread
    within the application is running any SQLite interface at the same time.
    Doing so results in undefined behavior.  Changing the temp_store_directory
    setting writes to the sqlite3_temp_directory global
    variable and that global variable is not protected by a mutex.

    The value directory-name should be enclosed in single quotes.
    To revert the directory to the default, set the directory-name to
    an empty string, e.g., PRAGMA temp_store_directory = ''.  An
    error is raised if directory-name is not found or is not
    writable. 

    The default directory for temporary files depends on the OS.  Some
    OS interfaces may choose to ignore this variable and place temporary
    files in some other directory different from the directory specified
    here.  In that sense, this pragma is only advisory.

    
    
    This pragma is deprecated and exists
    for backwards compatibility only.  New applications
    should avoid using this pragma.  Older applications should discontinue
    use of this pragma at the earliest opportunity.  This pragma may be omitted
    from the build when SQLite is compiled using SQLITE_OMIT_DEPRECATED.
    
  

 PRAGMA threads
    PRAGMA threads;
      PRAGMA threads = N;
    Query or change the value of the 
    sqlite3_limit(db,SQLITE_LIMIT_WORKER_THREADS,...) limit for
    the current database connection.  This limit sets an upper bound
    on the number of auxiliary threads that a prepared statement is
    allowed to launch to assist with a query.  The default limit is 0
    unless it is changed using the SQLITE_DEFAULT_WORKER_THREADS
    compile-time option.  When the limit is zero, that means no
    auxiliary threads will be launched.

    This pragma is a thin wrapper around the
    sqlite3_limit(db,SQLITE_LIMIT_WORKER_THREADS,...) interface.
    

 PRAGMA trusted_schema
    PRAGMA trusted_schema;
      PRAGMA trusted_schema = boolean;
    The trusted_schema setting is a per-connection boolean that
    determines whether or not SQL functions and virtual tables that
    have not been security audited are allowed to be run by views,
    triggers, or in expressions of the schema such as CHECK constraints,
    DEFAULT clauses, generated columns, expression indexes, and/or
    partial indexes.  This setting can also be controlled using
    the sqlite3_db_config(db,SQLITE_DBCONFIG_TRUSTED_SCHEMA,...)
    C-language interface.
    In order to maintain backwards compatibility, this setting is
    ON by default.  There are advantages to turning it off, and most
    applications will be unaffected if it is turned off.  For that reason,
    all applications are encouraged to switch this setting off on every
    database connection as soon as that connection is opened.
    The -DSQLITE_TRUSTED_SCHEMA=0 compile-time option will cause
    this setting to default to OFF.

 PRAGMA user_version
      PRAGMA schema.user_version;
      PRAGMA schema.user_version = integer ;

  
    The user_version pragma will get or set
       the value of the user-version integer at offset 60 in the
       database header.  The user-version is an integer that is
       available to applications to use however they want.  SQLite
       makes no use of the user-version itself.

    See also the application_id pragma and schema_version pragma.

 PRAGMA vdbe_addoptrace
    PRAGMA vdbe_addoptrace = boolean;

    If SQLite has been compiled with the SQLITE_DEBUG compile-time
    option, then the vdbe_addoptrace pragma can be used to cause a complete
    VDBE opcodes to be displayed as they are created during code generation.
    This feature is used for debugging SQLite itself.  See the 
    VDBE documentation for more 
    information.

    
    
    This pragma is intended for use when debugging SQLite itself.  It
    is only available when the SQLITE_DEBUG compile-time option
    is used.
  

 PRAGMA vdbe_debug
    PRAGMA vdbe_debug = boolean;

    If SQLite has been compiled with the SQLITE_DEBUG compile-time
    option, then the vdbe_debug pragma is a shorthand for three other
    debug-only pragmas: vdbe_addoptrace, vdbe_listing, and vdbe_trace.
    This feature is used for debugging SQLite itself.  See the 
    VDBE documentation for more 
    information.

    
    
    This pragma is intended for use when debugging SQLite itself.  It
    is only available when the SQLITE_DEBUG compile-time option
    is used.
  

 PRAGMA vdbe_listing
    PRAGMA vdbe_listing = boolean;

    If SQLite has been compiled with the SQLITE_DEBUG compile-time
    option, then the vdbe_listing pragma can be used to cause a complete
    listing of the virtual machine opcodes to appear on standard output
    as each statement is evaluated.
    With listing is on, the entire content of a program is printed
    just prior to beginning execution.  The statement
    executes normally after the listing is printed.
    This feature is used for debugging SQLite itself.  See the 
    VDBE documentation for more 
    information.

    
    
    This pragma is intended for use when debugging SQLite itself.  It
    is only available when the SQLITE_DEBUG compile-time option
    is used.
  

 PRAGMA vdbe_trace
    PRAGMA vdbe_trace = boolean;

    If SQLite has been compiled with the SQLITE_DEBUG compile-time
    option, then the vdbe_trace pragma can be used to cause virtual machine
    opcodes to be printed on standard output as they are evaluated.
    This feature is used for debugging SQLite.  See the 
    VDBE documentation for more 
    information.

    
    
    This pragma is intended for use when debugging SQLite itself.  It
    is only available when the SQLITE_DEBUG compile-time option
    is used.
  

 PRAGMA wal_autocheckpoint
    PRAGMA wal_autocheckpoint;
          PRAGMA wal_autocheckpoint=N;

    This pragma queries or sets the write-ahead log 
    auto-checkpoint interval.
    When the write-ahead log is enabled (via the
    journal_mode pragma) a checkpoint will be run automatically whenever
    the write-ahead log equals or exceeds N pages in length.
    Setting the auto-checkpoint size to zero or a negative value
    turns auto-checkpointing off.
    
    This pragma is a wrapper around the
    sqlite3_wal_autocheckpoint() C interface.
    All automatic checkpoints are PASSIVE.

    Autocheckpointing is enabled by default with an interval
    of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT.


 PRAGMA wal_checkpoint
    PRAGMA schema.wal_checkpoint;
       PRAGMA schema.wal_checkpoint(PASSIVE);
       PRAGMA schema.wal_checkpoint(FULL);
       PRAGMA schema.wal_checkpoint(RESTART);
       PRAGMA schema.wal_checkpoint(TRUNCATE);
   

    If the write-ahead log is enabled (via the journal_mode pragma),
    this pragma causes a checkpoint operation to run on database
    database, or on all attached databases if database
    is omitted.  If write-ahead log mode is disabled, this pragma is a
    harmless no-op.

    Invoking this
    pragma without an argument is equivalent to calling the
    sqlite3_wal_checkpoint() C interface.
    Invoking this pragma with an argument is equivalent to calling the
    sqlite3_wal_checkpoint_v2() C interface with a 
    3rd parameter
    corresponding to the argument:

    
    PASSIVE
      Checkpoint as many frames as possible without waiting for any database 
      readers or writers to finish. Sync the db file if all frames in the log
      are checkpointed. This mode is the same as calling the
      sqlite3_wal_checkpoint() C interface. The
      busy-handler callback is never invoked in
      this mode.
   
    FULL
      This mode blocks 
      (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. FULL blocks concurrent writers while it is
      running, but readers can proceed.
   
    RESTART
      This mode works the same way as FULL with the addition that after 
      checkpointing the log file it blocks (calls the 
      busy-handler callback)
      until all readers are finished with the log file. This ensures 
      that the next client to write to the database file restarts the log file 
      from the beginning. RESTART blocks concurrent writers while it is
      running, but allowed readers to proceed.
   
    TRUNCATE
      This mode works the same way as RESTART with the 
      addition that the WAL file is truncated to zero bytes upon successful
      completion.
    


    The wal_checkpoint pragma returns a single row with three
    integer columns.  The first column is usually 0 but will be
    1 if a RESTART or FULL or TRUNCATE checkpoint was blocked from completing,
    for example because another thread or process was actively
    using the database.  In other words, the first column is 0 if the
    equivalent call to sqlite3_wal_checkpoint_v2() would have returned
    SQLITE_OK or 1 if the equivalent call would have returned SQLITE_BUSY.
    The second column is the number of modified pages that have been
    written to the write-ahead log file.
    The third column is the number of pages in the write-ahead log file
    that have been successfully moved back into the database file at
    the conclusion of the checkpoint.
   The second and third column are -1 if there is no
    write-ahead log, for example if this pragma is invoked on a database
    connection that is not in WAL mode.

 PRAGMA writable_schema
    PRAGMA writable_schema  = boolean;
         PRAGMA writable_schema = RESET

    When this pragma is on, and the SQLITE_DBCONFIG_DEFENSIVE flag
    is off, then the sqlite_schema table
    can be changed using ordinary UPDATE, INSERT, and DELETE
    statements.  If the argument is "RESET" then schema writing is
    disabled (as with "PRAGMA writable_schema=OFF") and, in addition, the
    schema is reloaded.  Warning:
    misuse of this pragma can easily result in
    a corrupt database file.


