Enhance the sqlite3_stmt_explain() interface so that avoids unnecessary

reprepare operations.

FossilOrigin-Name: 050f773addd605f6690348c98e9000a9a3663bbc26288a71973fd7b40468e8ab

1 files changed, 17 insertions, 13 deletions

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 9e165c1e5..668cfa54b 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -4425,24 +4425,28 @@ int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
 ** CAPI3REF: Change The EXPLAIN Setting For A Prepared Statement
 ** METHOD: sqlite3_stmt
 **
-** ^The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN
+** 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) causes prepared statement S
-** to be reprepared.  A call to sqlite3_stmt_explain(S,E) will fail
-** with SQLITE_ERROR if S cannot be re-prepared because it was created
-** using sqlite3_prepare() instead of the newer sqlite_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 still appear in the sqlite3_sql(S) output, even though
-** the statement now acts like a normal SQL statement.
+** 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 sqlite_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.