1.Dd January 24, 2024 2.Dt SQLITE3_SQL 3 3.Os 4.Sh NAME 5.Nm sqlite3_sql , 6.Nm sqlite3_expanded_sql , 7.Nm sqlite3_normalized_sql 8.Nd retrieving statement SQL 9.Sh SYNOPSIS 10.In sqlite3.h 11.Ft const char * 12.Fo sqlite3_sql 13.Fa "sqlite3_stmt *pStmt" 14.Fc 15.Ft char * 16.Fo sqlite3_expanded_sql 17.Fa "sqlite3_stmt *pStmt" 18.Fc 19.Ft const char * 20.Fo sqlite3_normalized_sql 21.Fa "sqlite3_stmt *pStmt" 22.Fc 23.Sh DESCRIPTION 24The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 25SQL text used to create prepared statement P if P 26was created by 27.Fn sqlite3_prepare_v2 , 28.Fn sqlite3_prepare_v3 , 29.Fn sqlite3_prepare16_v2 , 30or 31.Fn sqlite3_prepare16_v3 . 32The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 33string containing the SQL text of prepared statement P with bound parameters 34expanded. 35The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8 36string containing the normalized SQL text of prepared statement P. 37The semantics used to normalize a SQL statement are unspecified and 38subject to change. 39At a minimum, literal values will be replaced with suitable placeholders. 40.Pp 41For example, if a prepared statement is created using the SQL text 42"SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 and 43parameter :xyz is unbound, then sqlite3_sql() will return the original 44string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() will return "SELECT 452345,NULL". 46.Pp 47The sqlite3_expanded_sql() interface returns NULL if insufficient memory 48is available to hold the result, or if the result would exceed the 49the maximum string length determined by the SQLITE_LIMIT_LENGTH. 50.Pp 51The SQLITE_TRACE_SIZE_LIMIT compile-time option 52limits the size of bound parameter expansions. 53The SQLITE_OMIT_TRACE compile-time option causes sqlite3_expanded_sql() 54to always return NULL. 55.Pp 56The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P) 57are managed by SQLite and are automatically freed when the prepared 58statement is finalized. 59The string returned by sqlite3_expanded_sql(P), on the other hand, 60is obtained from 61.Fn sqlite3_malloc 62and must be freed by the application by passing it to 63.Fn sqlite3_free . 64The sqlite3_normalized_sql() interface is only available if the SQLITE_ENABLE_NORMALIZE 65compile-time option is defined. 66.Sh IMPLEMENTATION NOTES 67These declarations were extracted from the 68interface documentation at line 4321. 69.Bd -literal 70SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); 71SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); 72#ifdef SQLITE_ENABLE_NORMALIZE 73SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt); 74#endif 75.Ed 76.Sh SEE ALSO 77.Xr sqlite3_malloc 3 , 78.Xr sqlite3_prepare 3 , 79.Xr sqlite3_stmt 3 , 80.Xr SQLITE_LIMIT_LENGTH 3 81