Documentation Source Text

<p>^When the EXPLAIN keyword appears by itself it causes the statement
to behave as a query that returns the sequence of 
[virtual machine instructions] it would have used to execute the command had
the EXPLAIN keyword not been present. ^When the EXPLAIN QUERY PLAN phrase
appears, the statement returns high-level information regarding the query
plan that would have been used.

<p>The EXPLAIN QUERY PLAN command is described in 
[explain query plan|more detail here].

<h3>EXPLAIN operates at run-time, not at prepare-time</h3>

<p>The EXPLAIN and EXPLAIN QUERY PLAN prefixes affect the behavior of
running a [prepared statement] using [sqlite3_step()].  The process of
generating a new prepared statement using [sqlite3_prepare()] or similar
is (mostly) unaffected by EXPLAIN.  (The exception to the previous sentence
is that some special opcodes used by EXPLAIN QUERY PLAN are omitted when
building an EXPLAIN QUERY PLAN prepared statement, as a performance
optimization.)

<p>This means that actions that occur during sqlite3_prepare() are
unaffected by EXPLAIN.

<ul>
<li><p>
Some [PRAGMA] statements do their work during sqlite3_prepare() rather
than during sqlite3_step().  Those PRAGMA statements are unaffected
by EXPLAIN.  They operate the same with or without the EXPLAIN prefix.
The set of PRAGMA statements that are unaffected by EXPLAIN can vary
from one release to the next.  Some PRAGMA statements operate during
sqlite3_prepare() depending on their arguments.  For consistent
results, avoid using EXPLAIN on PRAGMA statements.

<li><p>
The [authorizer callback] is invoked regardless of the presence of
EXPLAIN or EXPLAIN QUERY PLAN.
</ul>
<tcl>
##############################################################################
Section expression expr {*expression {expression syntax}}

RecursiveBubbleDiagram expr
</tcl>

<p>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:
</p>
<ul>
<li>The pragma command is specific to SQLite and is
    not compatible with any other SQL database engine.
<li>Specific pragma statements may be removed and others added in future
    releases of SQLite. There is no guarantee of backwards compatibility.
<li>^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.
<li>^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.
<li>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".
</ul>

<p>The C-language API for SQLite provides the [SQLITE_FCNTL_PRAGMA]
[sqlite3_file_control | file control] which gives [VFS] implementations the
opportunity to add new PRAGMA statements or to override the meaning of
built-in PRAGMA statements.</p>