1.Dd January 24, 2024 2.Dt SQLITE3_STMT_EXPLAIN 3 3.Os 4.Sh NAME 5.Nm sqlite3_stmt_explain 6.Nd change the EXPLAIN setting for a prepared statement 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_stmt_explain 11.Fa "sqlite3_stmt *pStmt" 12.Fa "int eMode" 13.Fc 14.Sh DESCRIPTION 15The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN setting 16for prepared statement S. 17If E is zero, then S becomes a normal prepared statement. 18If E is 1, then S behaves as if its SQL text began with "EXPLAIN". 19If E is 2, then S behaves as if its SQL text began with "EXPLAIN QUERY PLAN". 20.Pp 21Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared. 22SQLite tries to avoid a reprepare, but a reprepare might be necessary 23on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode. 24.Pp 25Because of the potential need to reprepare, a call to sqlite3_stmt_explain(S,E) 26will fail with SQLITE_ERROR if S cannot be reprepared because it was 27created using 28.Fn sqlite3_prepare 29instead of the newer 30.Fn sqlite3_prepare_v2 31or 32.Fn sqlite3_prepare_v3 33interfaces and hence has no saved SQL text with which to reprepare. 34.Pp 35Changing the explain setting for a prepared statement does not change 36the original SQL text for the statement. 37Hence, if the SQL text originally began with EXPLAIN or EXPLAIN QUERY 38PLAN, but sqlite3_stmt_explain(S,0) is called to convert the statement 39into an ordinary statement, the EXPLAIN or EXPLAIN QUERY PLAN keywords 40will still appear in the sqlite3_sql(S) output, even though the statement 41now acts like a normal SQL statement. 42.Pp 43This routine returns SQLITE_OK if the explain mode is successfully 44changed, or an error code if the explain mode could not be changed. 45The explain mode cannot be changed while a statement is active. 46Hence, it is good practice to call sqlite3_reset(S) 47immediately prior to calling sqlite3_stmt_explain(S,E). 48.Sh IMPLEMENTATION NOTES 49These declarations were extracted from the 50interface documentation at line 4429. 51.Bd -literal 52SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode); 53.Ed 54.Sh SEE ALSO 55.Xr sqlite3_prepare 3 , 56.Xr sqlite3_stmt 3 57