SQLITE3_STMT_EXPLAIN(3)

SQLITE3_STMT_EXPLAIN(3) | Library Functions Manual | SQLITE3_STMT_EXPLAIN(3)

# NAME

`sqlite3_stmt_explain` — change the EXPLAIN setting for a prepared statement

# SYNOPSIS

`#include <sqlite3.h>`

int
`sqlite3_stmt_explain`(sqlite3_stmt *pStmt, int eMode);

# 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".

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

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

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

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

# IMPLEMENTATION NOTES

These declarations were extracted from the interface documentation at line 4429.

    SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);

# SEE ALSO

sqlite3_prepare(3), sqlite3_stmt(3)

January 24, 2024 | NetBSD 11.0