.Dd January 24, 2024
.Dt SQLITE3_SQL 3
.Os
.Sh NAME
.Nm sqlite3_sql ,
.Nm sqlite3_expanded_sql ,
.Nm sqlite3_normalized_sql
.Nd retrieving statement SQL
.Sh SYNOPSIS
.In sqlite3.h
.Ft const char *
.Fo sqlite3_sql
.Fa "sqlite3_stmt *pStmt"
.Fc
.Ft char *
.Fo sqlite3_expanded_sql
.Fa "sqlite3_stmt *pStmt"
.Fc
.Ft const char *
.Fo sqlite3_normalized_sql
.Fa "sqlite3_stmt *pStmt"
.Fc
.Sh DESCRIPTION
The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
SQL text used to create prepared statement P if P
was created by
.Fn sqlite3_prepare_v2 ,
.Fn sqlite3_prepare_v3 ,
.Fn sqlite3_prepare16_v2 ,
or
.Fn sqlite3_prepare16_v3 .
The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
string containing the SQL text of prepared statement P with bound parameters
expanded.
The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
string containing the normalized SQL text of prepared statement P.
The semantics used to normalize a SQL statement are unspecified and
subject to change.
At a minimum, literal values will be replaced with suitable placeholders.
.Pp
For example, if a prepared statement is created using the SQL text
"SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 and
parameter :xyz is unbound, then sqlite3_sql() will return the original
string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() will return "SELECT
2345,NULL".
.Pp
The sqlite3_expanded_sql() interface returns NULL if insufficient memory
is available to hold the result, or if the result would exceed the
the maximum string length determined by the SQLITE_LIMIT_LENGTH.
.Pp
The SQLITE_TRACE_SIZE_LIMIT compile-time option
limits the size of bound parameter expansions.
The SQLITE_OMIT_TRACE compile-time option causes sqlite3_expanded_sql()
to always return NULL.
.Pp
The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
are managed by SQLite and are automatically freed when the prepared
statement is finalized.
The string returned by sqlite3_expanded_sql(P), on the other hand,
is obtained from
.Fn sqlite3_malloc
and must be freed by the application by passing it to
.Fn sqlite3_free .
The sqlite3_normalized_sql() interface is only available if the SQLITE_ENABLE_NORMALIZE
compile-time option is defined.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 4321.
.Bd -literal
SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
#ifdef SQLITE_ENABLE_NORMALIZE
SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
#endif
.Ed
.Sh SEE ALSO
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_prepare 3 ,
.Xr sqlite3_stmt 3 ,
.Xr SQLITE_LIMIT_LENGTH 3