小巧。快速。可靠。
三选二。

SQLite C 接口

编译 SQL 语句

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 为零，则不会生成任何预备语句。如果调用者知道提供的字符串是空终止的，那么传递一个 nByte 参数，该参数是输入字符串（包括空终止符）的字节数，将具有一定的性能优势。

如果 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() 接口的行为在三个方面有所不同

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

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

  3. 如果绑定到 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() 完全相同。

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