Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Compiling An SQL Statement

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.

The first argument, "db", is a database connection obtained from a prior call to sqlite3_open(), sqlite3_open_v2() or sqlite3_open16().

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() use UTF-16.

If the nByte argument is less than zero, then zSql is read up to the first zero terminator. If nByte is non-negative, then it is the maximum number of bytes read from zSql. When nByte is non-negative, the zSql string ends at either the first '\000' or '\u0000' character or the nByte-th byte, whichever comes first. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to be gained by passing an nByte parameter that is equal to the number of bytes in the input string including the nul-terminator bytes.

*pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compile the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.

*ppStmt is left pointing to a compiled prepared statement that can be executed using sqlite3_step(). If there is an error, *ppStmt is set to NULL. If the input text contains no SQL (if the input is an empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting the compiled SQL statement using sqlite3_finalize() after it has finished with it.

On success, SQLITE_OK is returned, otherwise an error code is returned.

The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are recommended for all new programs. The two older interfaces are retained for backwards compatibility, but their use is discouraged. In the "v2" interfaces, the prepared statement that is returned (the sqlite3_stmt object) contains a copy of the original SQL text. This causes the sqlite3_step() interface to behave a differently in two ways:

  1. If the database schema changes, instead of returning SQLITE_SCHEMA as it always used to do, sqlite3_step() will automatically recompile the SQL statement and try to run it again. If the schema has changed in a way that makes the statement no longer valid, sqlite3_step() will still return SQLITE_SCHEMA. But unlike the legacy behavior, SQLITE_SCHEMA is now a fatal error. Calling sqlite3_prepare_v2() again will not make the error go away. Note: use sqlite3_errmsg() to find the text of the parsing error that results in an SQLITE_SCHEMA return.
  2. When an error occurs, sqlite3_step() will return one of the detailed error codes or extended error codes. The legacy behavior was that sqlite3_step() would only return a generic SQLITE_ERROR result code and you would have to make a second call to sqlite3_reset() in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

Invariants:

H13011 The sqlite3_prepare(db,zSql,...) and sqlite3_prepare_v2(db,zSql,...) interfaces interpret the text in their zSql parameter as UTF-8.
H13012 The sqlite3_prepare16(db,zSql,...) and sqlite3_prepare16_v2(db,zSql,...) interfaces interpret the text in their zSql parameter as UTF-16 in the native byte order.
H13013 If the nByte argument to sqlite3_prepare_v2(db,zSql,nByte,...) and its variants is less than zero, the SQL text is read from zSql is read up to the first zero terminator.
H13014 If the nByte argument to sqlite3_prepare_v2(db,zSql,nByte,...) and its variants is non-negative, then at most nBytes bytes of SQL text is read from zSql.
H13015 In sqlite3_prepare_v2(db,zSql,N,P,pzTail) and its variants if the zSql input text contains more than one SQL statement and pzTail is not NULL, then *pzTail is made to point to the first byte past the end of the first SQL statement in zSql. (TODO: What does *pzTail point to if there is one statement?)
H13016 A successful call to sqlite3_prepare_v2(db,zSql,N,ppStmt,...) or one of its variants writes into *ppStmt a pointer to a new prepared statement or a pointer to NULL if zSql contains nothing other than whitespace or comments.
H13019 The sqlite3_prepare_v2() interface and its variants return SQLITE_OK or an appropriate error code upon failure.
H13021 Before sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail) or its variants returns an error (any value other than SQLITE_OK), they first set *ppStmt to NULL.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC