SQlite数据库的C编程接口（三） 预处理语句（Prepared Statements） ——《Using SQlite》读书笔记 .

SQlite数据库的C编程接口（三） 预处理语句（Prepared Statements）  by斜风细雨QQ：253786989    2012-02-04

  SQlite3数据库连接完成之后，就可以执行SQL命令了。下面将要介绍的prepare和step函数都是用来操作和执行SQL命令的。

  典型的函数操作流程（伪代码）：

/* create a statement from an SQL string */
sqlite3_stmt *stmt = NULL;
sqlite3_prepare_v2( db, sql_str, sql_str_len, &stmt, NULL );

/* use the statement as many times as required */
while( ... )
{
    /* bind any parameter values */
    sqlite3_bind_xxx( stmt, param_idx, param_value... );
    ...
    /* execute statement and step over each row of the result set */
    while ( sqlite3_step( stmt ) == SQLITE_ROW )
    {
        /* extract column values from the current result row */
        col_val = sqlite3_column_xxx( stmt, col_index );
        ...
    }

    /* reset the statement so it may be used again */
    sqlite3_reset( stmt );
    sqlite3_clear_bindings( stmt );  /* optional */
}

/* destroy and release the statement */
sqlite3_finalize( stmt );
stmt = NULL;

/* create a statement from an SQL string */
sqlite3_stmt *stmt = NULL;
sqlite3_prepare_v2( db, sql_str, sql_str_len, &stmt, NULL );

/* use the statement as many times as required */
while( ... )
{
    /* bind any parameter values */
    sqlite3_bind_xxx( stmt, param_idx, param_value... );
    ...
    /* execute statement and step over each row of the result set */
    while ( sqlite3_step( stmt ) == SQLITE_ROW )
    {
        /* extract column values from the current result row */
        col_val = sqlite3_column_xxx( stmt, col_index );
        ...
    }

    /* reset the statement so it may be used again */
    sqlite3_reset( stmt );
    sqlite3_clear_bindings( stmt );  /* optional */
}

/* destroy and release the statement */
sqlite3_finalize( stmt );
stmt = NULL;

  这段程序首先调用sqlite3_prepare_v2函数，将一个SQL命令字符串转换成一条prepared语句，存储在sqlite3_stmt类型结构体中。随后调用sqlite3_bind_xxx函数给这条prepared语句绑定参数。然后不停的调用sqlite3_step函数执行这条prepared语句，获取结果集中的每一行数据，从每一行数据中调用qlite3_column_xxx函数获取有用的列数据，直到结果集中所有的行都被处理完毕。

  prepared语句可以被重置（调用sqlite3_reset函数），然后可以重新绑定参数之后重新执行。sqlite3_prepare_v2函数代价昂贵，所以通常尽可能的重用prepared语句。最后，这条prepared语句确实不在使用时，调用sqlite3_finalize函数释放所有的内部资源和sqlite3_stmt数据结构，有效删除prepared语句。

预处理（Prepare）

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 */
);

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 */
);

  这些函数的作用是将SQL命令字符串转换为prepared语句。参数db是由sqlite3_open函数返回的指向数据库连接的指针。参数zSql是UTF-8或者UTF-16编码的SQL命令字符串，参数nByte是zSql的字节长度。如果nByte为负值，则prepare函数会自动计算出zSql的字节长度，不过要确保zSql传入的是以NULL结尾的字符串。如果SQL命令字符串中只包含一条SQL语句，那么它没有必要以“;”结尾。参数ppStmt是一个指向指针的指针，用来传回一个指向新建的sqlite3_stmt结构体的指针，sqlite3_stmt结构体里面保存有转换好的SQL语句。如果SQL命令字符串包含多条SQL语句，同时参数pzTail不为NULL，那么它将指向SQL命令字符串中的下一条SQL语句。上面4个函数中的v2版本是加强版，与原始版函数参数相同，不同的是函数内部对于sqlite3_stmt结构体的表现上。细节不去理会，尽量使用v2版本。

  在sqlite3_prepare函数转换一条语句完毕之后，可以给这条语句绑定参数。语句参数允许我们插入一个特殊的占位符，然后给这个参数占位符绑定指定的值，然后再执行它。执行完成之后，还可以重置语句，绑定新的参数值，再重新执行该语句。像INSERT操作，每次执行INSERT命令，绑定不同的值，插入不同的数据。参数绑定是一个有点复杂的深入话题，在下一节中学习。

步进（Step）

int sqlite3_step(sqlite3_stmt*);

int sqlite3_step(sqlite3_stmt*);

  sqlite3_prepare函数将SQL命令字符串解析并转换为一系列的命令字节码，这些字节码最终被传送到SQlite3的虚拟数据库引擎（VDBE: Virtual Database Engine）中执行，完成这项工作的是sqlite3_step函数。比如一个SELECT查询操作，sqlite3_step函数的每次调用都会返回结果集中的其中一行，直到再没有有效数据行了。每次调用sqlite3_step函数如果返回SQLITE_ROW，代表获得了有效数据行，可以通过sqlite3_column函数提取某列的值。如果调用sqlite3_step函数返回SQLITE_DONE，则代表prepared语句已经执行到终点了，没有有效数据了。很多命令第一次调用sqlite3_step函数就会返回SQLITE_DONE，因为这些SQL命令不会返回数据。对于INSERT，UPDATE，DELETE命令，会返回它们所修改的行号——一个单行单列的值。

结果列（Result Columns）

int sqlite3_column_count(sqlite3_stmt *pStmt);

int sqlite3_column_count(sqlite3_stmt *pStmt);

  返回结果集的列数。

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

  返回结果集中指定列的列名，列的序号以0开始。比如一条SQL语句：SELECT pid AS person_id...，那么调用sqlite3_column_name函数返回结果集中第0列的列名就是person_id。返回的字符串指针将一直有效，直到再次调用sqlite3_column_name函数并再次读取该列的列名时失效。

int sqlite3_column_type(sqlite3_stmt*, int iCol);

int sqlite3_column_type(sqlite3_stmt*, int iCol);

  该函数返回结果集中指定列的本地存储类型，如SQLITE_INTEGER，SQLITE_FLOAT，SQLITE_TEXT，SQLITE_BLOB，SQLITE_NULL。为了获取正确的类型，该函数应该在任何试图提取数据的函数调用之前被调用。SQlite3数据库允许不同类型的数据存储在同一列中，所以对于不同行的相同索引的列调用该函数获取的列类型可能会不同。

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);

  返回一个指针，指向给定列的BLOB类型值。

double sqlite3_column_double(sqlite3_stmt*, int iCol);

double sqlite3_column_double(sqlite3_stmt*, int iCol);

  从给定列返回一个64位浮点值。

int sqlite3_column_int(sqlite3_stmt*, int iCol);

int sqlite3_column_int(sqlite3_stmt*, int iCol);

  从给定列返回一个32位有符号整数，如果该列中包含的整型值无法用32位数值表示，那它将会在没有任何警告的情况下被截断。

sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);

sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);

  从给定列返回一个64位有符号整数。

const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);

const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);

  返回一个指针，指向给定列的UTF-8或者UTF-16编码的字符串，该字符串以NULL结尾。

sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

  返回一个指针，指向一个无保护的sqlite3_value结构，该结构无法进行安全的数据类型转换，所以无法调用sqlite3_value_xxx函数从这个结构体中提取原始数值。如果想提取原始数值，只能调用其它的sqlite3_column_xxx函数。对于该函数返回的指针，安全的用法是以它为参数调用sqlite3_bind_value函数给一个prepared语句绑定参数，或者以它为参数调用sqlite3_result_value函数得到一个用户自定义的SQL函数的返回值。

  对于这些sqlite3_column_xxx函数返回的指针，当再次调用sqlite3_column_xxx函数并操作相同的列的时失效，或者在sqlite3_step、sqlite3_reset、sqlite3_finalize等函数调用之后失效。

  如果提取列值时使用的sqlite3_column_xxx函数版本与原始值的本地数据类型不同，SQlite数据库将进行转换。转换原则：

int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);

int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);

  对于BLOB和text类型，sqlite3_column_blob和sqlite3_column_text函数将会返回一个buffer指针。通过sqlite3_value_bytes函数可以得到buffer字节长度，对于text类型，这个字节长度将包括一个字符串结尾符。

  需要注意的是：假如先调用sqlite3_column_text函数获取一个指向UTF-8编码的字符串指针，之后又调用了sqlite3_column_bytes16在相同的列上获取buffer大小，那么该列的字符串将会从UTF-8编码转换为UTF-16编码，导致之前由sqlite3_column_text函数返回的指针失效。

  正确做法是提取值时的函数和获取值buffer大小的函数，以相同类型匹配使用，如：

/* correctly extract a blob */
buf_ptr = sqlite3_column_blob( stmt, n );
buf_len = sqlite3_column_bytes( stmt, n );

/* correctly extract a UTF-8 encoded string */
buf_ptr = sqlite3_column_text( stmt, n );
buf_len = sqlite3_column_bytes( stmt, n );

/* correctly extract a UTF-16 encoded string */
buf_ptr = sqlite3_column_text16( stmt, n );
buf_len = sqlite3_column_bytes16( stmt, n );

/* correctly extract a blob */
buf_ptr = sqlite3_column_blob( stmt, n );
buf_len = sqlite3_column_bytes( stmt, n );

/* correctly extract a UTF-8 encoded string */
buf_ptr = sqlite3_column_text( stmt, n );
buf_len = sqlite3_column_bytes( stmt, n );

/* correctly extract a UTF-16 encoded string */
buf_ptr = sqlite3_column_text16( stmt, n );
buf_len = sqlite3_column_bytes16( stmt, n );

重置与完成（Reset and Finalize）

int sqlite3_reset(sqlite3_stmt *pStmt);

int sqlite3_reset(sqlite3_stmt *pStmt);

  当sqlite3_step函数调用返回SQLITE_DONE时，则代表这条语句已经完成执行，这时如果还想重用这条prepared语句，就需要调用sqlite3_reset函数进行重置。或者，比如我们只想提取结果集的前六行数据，那么我们就可以连续调用6次sqlite3_step函数，之后调用sqlite3_reset函数重置prepared语句，以备下一次使用。

int sqlite3_finalize(sqlite3_stmt *pStmt);

int sqlite3_finalize(sqlite3_stmt *pStmt);

  销毁prepared语句，释放资源。在关闭数据库连接之前，对于不再使用的prepared语句，一定要调用sqlite3_finalize函数进行销毁，

语句（状态）转换（Statement Transitions）

  一条语句可以处于不同状态，对于一条新的或者刚刚被reset的语句，它们处于“ready”状态，代表它们已经准备好执行，但还没有开始执行。一条语句也有可能处于“running”状态，表明这条语句已经开始执行，但还没有完成。还有一种状态叫做“done”，表明一条语句已经执行完成。

  对于有些API函数，只能在某条语句处于特定状态下才可以执行，比如sqlite3_bind_xxx函数，只有在一条语句处于“ready”状态时才可以被调用，否则函数将会返回SQLITE_MISUSE错误码。下图展示了一条语句所处于的不同状态，以及不同状态之间是如何转换的。

示例代码

（1）

sqlite3_stmt *stmt = NULL;
/* ... open database ... */

sqlite3_stmt *stmt = NULL;
/* ... open database ... */

rc = sqlite3_prepare_v2( db, "CREATE TABLE tbl ( str TEXT )", -1, &stmt, NULL );
if ( rc != SQLITE_OK) exit( -1 );

rc = sqlite3_prepare_v2( db, "CREATE TABLE tbl ( str TEXT )", -1, &stmt, NULL );
if ( rc != SQLITE_OK) exit( -1 );

rc = sqlite3_step( stmt );
if ( rc != SQLITE_DONE ) exit ( -1 );

sqlite3_finalize( stmt );
/* ... close database ... */

rc = sqlite3_step( stmt );
if ( rc != SQLITE_DONE ) exit ( -1 );

sqlite3_finalize( stmt );
/* ... close database ... */

  CREATE TABLE语句没有返回值，调用sqlite3_step函数执行这条语句，最后在关闭数据库之前调用sqlite3_finalize销毁这条语句。

（2）

const char *data = NULL;
sqlite3_stmt *stmt = NULL;
/* ... open database ... */

const char *data = NULL;
sqlite3_stmt *stmt = NULL;
/* ... open database ... */

rc = sqlite3_prepare_v2( db, "SELECT str FROM tbl ORDER BY 1", -1, &stmt, NULL );
if ( rc != SQLITE_OK) exit( -1 );

while( sqlite3_step( stmt ) == SQLITE_ROW ) {
    data = (const char*)sqlite3_column_text( stmt, 0 );
    printf( "%s\n", data ? data : "[NULL]" );
}

sqlite3_finalize( stmt );
/* ... close database ... */

rc = sqlite3_prepare_v2( db, "SELECT str FROM tbl ORDER BY 1", -1, &stmt, NULL );
if ( rc != SQLITE_OK) exit( -1 );

while( sqlite3_step( stmt ) == SQLITE_ROW ) {
    data = (const char*)sqlite3_column_text( stmt, 0 );
    printf( "%s\n", data ? data : "[NULL]" );
}

sqlite3_finalize( stmt );
/* ... close database ... */

  这段代码循环提取表tbl的所有行，并把每一行第0列值打印出来。

SQlite数据库的C编程接口（三） 预处理语句（Prepared Statements）  by斜风细雨QQ：253786989    2012-02-04