.Dd January 24, 2024
.Dt SQLITE3_STMT_EXPLAIN 3
.Os
.Sh NAME
.Nm sqlite3_stmt_explain
.Nd change the EXPLAIN setting for a prepared statement
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_stmt_explain
.Fa "sqlite3_stmt *pStmt"
.Fa "int eMode"
.Fc
.Sh DESCRIPTION
The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN setting
for prepared statement S.
If E is zero, then S becomes a normal prepared statement.
If E is 1, then S behaves as if its SQL text began with "EXPLAIN".
If E is 2, then S behaves as if its SQL text began with "EXPLAIN QUERY PLAN".
.Pp
Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.
SQLite tries to avoid a reprepare, but a reprepare might be necessary
on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.
.Pp
Because of the potential need to reprepare, a call to sqlite3_stmt_explain(S,E)
will fail with SQLITE_ERROR if S cannot be reprepared because it was
created using
.Fn sqlite3_prepare
instead of the newer
.Fn sqlite3_prepare_v2
or
.Fn sqlite3_prepare_v3
interfaces and hence has no saved SQL text with which to reprepare.
.Pp
Changing the explain setting for a prepared statement does not change
the original SQL text for the statement.
Hence, if the SQL text originally began with EXPLAIN or EXPLAIN QUERY
PLAN, but sqlite3_stmt_explain(S,0) is called to convert the statement
into an ordinary statement, the EXPLAIN or EXPLAIN QUERY PLAN keywords
will still appear in the sqlite3_sql(S) output, even though the statement
now acts like a normal SQL statement.
.Pp
This routine returns SQLITE_OK if the explain mode is successfully
changed, or an error code if the explain mode could not be changed.
The explain mode cannot be changed while a statement is active.
Hence, it is good practice to call sqlite3_reset(S)
immediately prior to calling sqlite3_stmt_explain(S,E).
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 4429.
.Bd -literal
SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
.Ed
.Sh SEE ALSO
.Xr sqlite3_prepare 3 ,
.Xr sqlite3_stmt 3