编译 SQL 语句

SQLite C 接口

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_prepare_v3(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  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 */
);
int sqlite3_prepare16_v3(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

要执行 SQL 语句，必须首先使用这些例程之一将其编译成字节代码程序。或者，换句话说，这些例程是准备好的语句对象的构造函数。

首选例程是sqlite3_prepare_v2()。sqlite3_prepare()接口是遗留的，应该避免。 sqlite3_prepare_v3()有一个额外的“prepFlags”选项，用于特殊目的。

首选使用 UTF-8 接口，因为 SQLite 目前使用 UTF-8 进行所有解析。UTF-16 接口是为方便起见而提供的。UTF-16 接口的工作方式是将输入文本转换为 UTF-8，然后调用相应的 UTF-8 接口。

第一个参数“db”是从先前成功调用sqlite3_open()、sqlite3_open_v2()或 sqlite3_open16()获得的数据库连接。数据库连接一定没有关闭。

第二个参数“zSql”是要编译的语句，编码为 UTF-8 或 UTF-16。sqlite3_prepare()、sqlite3_prepare_v2()和sqlite3_prepare_v3()接口使用UTF-8，sqlite3_prepare16()、sqlite3_prepare16_v2()和sqlite3_prepare16_v3()使用UTF-16。

如果 nByte 参数为负数，则读取 zSql 直到第一个零终止符。如果 nByte 为正数，则它是从 zSql 读取的字节数。如果 nByte 为零，则不会生成准备好的语句。如果调用者知道提供的字符串以 nul 终止，则传递一个 nByte 参数会有一个小的性能优势，该参数是输入字符串中的字节数，包括 nul 终止符。

如果 pzTail 不为 NULL，则 *pzTail 指向 zSql 中第一个 SQL 语句结束后的第一个字节。这些例程仅编译 zSql 中的第一条语句，因此 *pzTail 仍指向未编译的部分。

*ppStmt 指向编译好的准备语句，可以使用sqlite3_step()执行。如果出现错误，*ppStmt 将设置为 NULL。如果输入文本不包含 SQL（如果输入是空字符串或注释），则 *ppStmt 设置为 NULL。调用过程负责在完成后使用sqlite3_finalize()删除已编译的 SQL 语句。ppStmt 不能为 NULL。

成功时，sqlite3_prepare() 例程系列返回SQLITE_OK；否则返回错误代码。

建议所有新程序使用 sqlite3_prepare_v2()、sqlite3_prepare_v3()、sqlite3_prepare16_v2() 和 sqlite3_prepare16_v3() 接口。保留旧接口（sqlite3_prepare() 和 sqlite3_prepare16()）是为了向后兼容，但不鼓励使用它们。在“vX”接口中，返回的准备好的语句（sqlite3_stmt对象）包含原始 SQL 文本的副本。这导致sqlite3_step()接口以三种方式表现不同：

如果数据库模式发生变化，sqlite3_step()将自动重新编译 SQL 语句并尝试再次运行，而不是像往常一样返回SQLITE_SCHEMA 。在 sqlite3_step() 放弃并返回错误之前，将发生与SQLITE_MAX_SCHEMA_RETRY一样多的重试。

当发生错误时，sqlite3_step()将返回详细错误代码或扩展错误代码之一。遗留行为是 sqlite3_step()只会返回一个通用的SQLITE_ERROR结果代码，应用程序必须再次调用sqlite3_reset() 才能找到问题的根本原因。使用“v2”准备接口，会立即返回错误的根本原因。

如果 WHERE 子句中绑定到主机参数的特定值可能会影响语句查询计划的选择，那么语句将自动重新编译，就好像在任何之后的第一个sqlite3_step()调用中发生了模式更改一样更改为该参数的绑定。如果参数是LIKE 或GLOB运算符的左侧，或者如果参数与索引列进行比较并且启用了SQLITE_ENABLE_STAT4编译时选项，则WHERE 子句参数的特定值可能会影响查询计划的选择.

sqlite3_prepare_v3() 与 sqlite3_prepare_v2() 的不同之处仅在于具有额外的 prepFlags 参数，该参数是由零个或多个SQLITE_PREPARE_*标志组成的位数组。sqlite3_prepare_v2() 接口的工作方式与带有零 prepFlags 参数的 sqlite3_prepare_v3() 完全相同。

另请参阅对象、常量和函数的列表。