1.Dd January 24, 2024 2.Dt SQLITE3_STMT_READONLY 3 3.Os 4.Sh NAME 5.Nm sqlite3_stmt_readonly 6.Nd determine if an SQL statement writes the database 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_stmt_readonly 11.Fa "sqlite3_stmt *pStmt" 12.Fc 13.Sh DESCRIPTION 14The sqlite3_stmt_readonly(X) interface returns true (non-zero) if and 15only if the prepared statement X makes no direct 16changes to the content of the database file. 17.Pp 18Note that application-defined SQL functions 19or virtual tables might change the database indirectly 20as a side effect. 21For example, if an application defines a function "eval()" that calls 22.Fn sqlite3_exec , 23then the following SQL statement would change the database file through 24side-effects: 25.Bd -ragged 26.Bd -literal 27SELECT eval('DELETE FROM t1') FROM t2; 28.Ed 29.Pp 30.Ed 31.Pp 32But because the SELECT statement does not change the database 33file directly, sqlite3_stmt_readonly() would still return true. 34.Pp 35Transaction control statements such as BEGIN, COMMIT, ROLLBACK, 36SAVEPOINT, and RELEASE cause sqlite3_stmt_readonly() 37to return true, since the statements themselves do not actually modify 38the database but rather they control the timing of when other statements 39modify the database. 40The ATTACH and DETACH statements also cause sqlite3_stmt_readonly() 41to return true since, while those statements change the configuration 42of a database connection, they do not make changes to the content of 43the database files on disk. 44The sqlite3_stmt_readonly() interface returns true for BEGIN since 45BEGIN merely sets internal flags, but the BEGIN IMMEDIATE 46and BEGIN EXCLUSIVE commands do touch the database and 47so sqlite3_stmt_readonly() returns false for those commands. 48.Pp 49This routine returns false if there is any possibility that the statement 50might change the database file. 51A false return does not guarantee that the statement will change the 52database file. 53For example, an UPDATE statement might have a WHERE clause that makes 54it a no-op, but the sqlite3_stmt_readonly() result would still be false. 55Similarly, a CREATE TABLE IF NOT EXISTS statement is a read-only no-op 56if the table already exists, but sqlite3_stmt_readonly() still returns 57false for such a statement. 58.Pp 59If prepared statement X is an EXPLAIN or EXPLAIN QUERY PLAN 60statement, then sqlite3_stmt_readonly(X) returns the same value as 61if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted. 62.Sh IMPLEMENTATION NOTES 63These declarations were extracted from the 64interface documentation at line 4368. 65.Bd -literal 66SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); 67.Ed 68.Sh SEE ALSO 69.Xr sqlite3_exec 3 , 70.Xr sqlite3_stmt 3 71