SQLite接口函数

SQLite核心源代码由C语言写就，同时提供了很多的扩展包可应用于其他编程语言和类库，如Python、Ruby、Java、Perl、.Net/C#、Qt和ODBC。在很多情况下，针对一种语言有很多扩展包可供选择，诸多的扩展包为不同的程序员满足不同的需求而设计开发。

由于笔者目前从事嵌入式开发相关的工作，所以从C语言的角度对SQLite的api进行探索和实践，本文主要从实例出发，结合代码在实践中学习与理解C API的使用，关于C/C++ 接口函数更细节的部分本文不再详细赘述，请具体请参考官方文件 An Introduction To The SQLite C/C++ Interface或者《SQLite 权威指南》。

C/C++ 接口函数概述

数据库连接对象和SQL语句对象由下面几个核心的C/C++接口来控制：sqlite3_open()、sqlite3_prepare()、sqlite3_step()、sqlite3_column()、sqlite3_finalize()、sqlite3_close()。

使用SQLite3时根据以上函数大概分为几个过程，这几个过程是概念上的说法，而不完全是程序运行的过程，如sqlite3_column()表示的是对查询获得一行里面的数据的列的各个操作统称，实际上在sqlite中并不存在这个函数。在SQLite提供的C/C++接口中，其中5个API属于核心接口。相比于其它数据库引擎提供的API，如OCI、MySQL API等，SQLite提供的接口易于理解和掌握。

以上六个C/C++接口及上面的两个对象构成SQLite的核心功能。注意这些接口有些有多个版本，例如sqlite3_open()有三个独立的版本：sqlite3_open(), sqlite3_open16()和sqlite3_open_v2()，它们以稍微不同的方式完成同样的事情。sqlite3_column()代表一个家族系列：sqlite_column_int(), sqlite_column_blob()等等，用于提取结果集中各种类型的列数据。

一个SQL数据库引擎的首要任务是执行SQL语句以获得我们想要的数据。为了完成这个任务，开发需要知道两个对象：数据库连接对象sqlite3和SQL预处理语句对象sqlite3_stmt，定义如下：

 　　　　typedef struct sqlite3 sqlite3;
　　　 　typedef struct sqlite3_stmt sqlite3_stmt;

严格地说，SQL预处理语句对象不是必需的，因为有使用方便的包装函数sqlite3_exec或sqlite3_get_table，它们封装并且隐藏了SQL语句对象。不过理解SQL语句对象能更好地使用SQLite。

代码实践

以下为具体的实践代码，相关总结与心得以注释的形式插入在代码，在执行代码前，请先下载SQLite源码并存储在同一路径下，按照以下方式执行编译即可：（也可将sqlite3编译成函数库再调用，具体请参照笔者另一篇文章sqlite 安装与编译)

gcc sqlite3.c test_api.c -lpthread -ldl -o testapi -I.

具体实践代码如下： 

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sqlite3.h>

int main( int argc, char **argv )
{
    sqlite3 *db;
    sqlite3_stmt * stmt;
    const char *zTail;
    int rc = -1;
    char *sql;
    
    /*1. 连接数据库*/
    /*int sqlite3_open(  
     *const char *filename,        // 数据库文件名 (UTF-8)   
     *sqlite3 **ppDb,            // OUT: SQLite数据库句柄
     *int flags,                  // 数据库文件操作标志
     *const char *zVfs            // 用于重写默认操作系统接口sqlite3_vfs的方法
     *);  
     */
    rc = sqlite3_open_v2("mysqlite.db", &db, SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE, NULL);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }
    
    /*2. 创建Table*/
    /*sqlite3_prepare_v2()将SQL语句编译为sqlite内部一个结构体(sqlite3_stmt)，
     *该结构体中包含了将要执行的SQL语句的信息
     *第四个参数用来指向输入参数中下一个需要编译的SQL语句存的 SQLite statement 对象的指针
     *注意现在sqlite3_prepare()已经不被推荐使用了，目前官司方推荐使用sqlite3_prepare_v2()
     *SQLITE_API int sqlite3_prepare_v2(
     *sqlite3 *db,            // SQLite数据库句柄 
     *const char *zSql,       // SQL 语句, UTF-8 编码 
     *int nByte,              // zSql的字节长度 
     *sqlite3_stmt **ppStmt,  // OUT: sql语句句柄(statement handle) 
     *const char **pzTail     // OUT: 指向zSql未使用的部分
     *);
     */
    sql = "CREATE TABLE players ( 

            id       INTEGER PRIMARY KEY, 

            name     TEXT, 

            age     INTEGER);";
    rc = sqlite3_prepare_v2(db, sql, -1, &stmt, &zTail);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }
    
    /*调用sqlite3_step()，此时SQL语句才真正执行，执行成功，返回SQLITE_DONE或SQLITE_ROW.
     *每次调用sqlite3_step()，只返回一行数据，使用sqlite3_column_XXX()函数来取出这些数据
     *要取出全部的数据，则需要反复调用sqlite3_step()
     */
    rc = sqlite3_step(stmt);
    if(rc != SQLITE_DONE){
        printf("%s
", sqlite3_errmsg(db));
    }

    /*调用sqlite3_finalize()，释放stmt占用的内存，该内存是在sqlite3_prepare()时分配的
     *如果SQL语句要重复使用，可以调用sqlite3_reset()来清除已经绑定的参数
     */
    rc = sqlite3_finalize(stmt);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }
    
    /*3.1 插入数据*/
    sql = "INSERT INTO players (name,age) VALUES(?,?);";
    rc = sqlite3_prepare_v2(db, sql, -1, &stmt, &zTail);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }

    /*sqlite3_bind_xxx的第四个参数为负，则字符串长度由第一个0终的位数决定
     *SQLITE_STATIC表示命令执行完后的信息为static类型，不能被改动,而且不需要被free
     */
    char str[] = "Kevin";
    int n = 23;
    sqlite3_bind_text(stmt,1,str,-1,SQLITE_STATIC);
    sqlite3_bind_int(stmt,2,n);
    rc = sqlite3_step(stmt);
    if( rc != SQLITE_DONE){
        printf("%s",sqlite3_errmsg(db));
    }

    //清除已经绑定的参数
    sqlite3_reset(stmt);
    //插入第二个数据
    char str2[] = "Jack";
    int n2 = 16;
    sqlite3_bind_text(stmt,1,str2,-1,SQLITE_STATIC);
    sqlite3_bind_int(stmt,2,n2);
    rc = sqlite3_step(stmt);
    if( rc != SQLITE_DONE){
        printf("%s",sqlite3_errmsg(db));
    }
    sqlite3_finalize(stmt); //释放stmt所占的内存

    /*3.2 插入数据*/
    char **pz_err_msg = NULL;
    sql = "INSERT INTO players(name, age) VALUES('Rose', 24);";
    rc = sqlite3_exec(db, sql, NULL, NULL, pz_err_msg);
    if (SQLITE_OK != rc) {
        printf("%s:sqlite3_exec insert "%s" failed
", __FUNCTION__, sql);
        if (NULL != pz_err_msg)    {
            printf("%s: error: %s
", __FUNCTION__, *pz_err_msg);
            sqlite3_free(pz_err_msg);
            pz_err_msg = NULL;    
        }
    }

    /*4. 查询所有数据*/
    sql = "SELECT id, name, age FROM players ORDER BY age";
    rc = sqlite3_prepare_v2(db, sql, -1, &stmt, &zTail);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }

    int number, id;
    const unsigned char * name;
    /*
    ** 执行SQL语句之后会,sqlite3_step()会返回不同的参数，如[SQLITE_BUSY],[SQLITE_DONE], 
    ** [SQLITE_ROW], [SQLITE_ERROR], [SQLITE_MISUSE].
    ** 当该函数完成一次类似查询（select）的SQL语句执行后，将返回[SQLITE_ROW]，每执行一次
    ** sqlite3_step()，都将准备好一行新的查询数据结果，该结果可通过sqlite3_column()系列函
    ** 数获取；要查询下一行的数据，只需重复执行sqlite3_step()即可。
     */
    rc = sqlite3_step(stmt);
    while( rc == SQLITE_ROW ){
        id = sqlite3_column_int( stmt, 0 );  //该函数用于获取当前行指定列(id)的数据(int类型)
        name = sqlite3_column_text( stmt, 1 );
        number = sqlite3_column_int( stmt, 2 );
        printf("ID: %d Name: %s Age: %d 
",id,name,number);
        sleep(1);
        rc = sqlite3_step(stmt);
    }
    rc = sqlite3_finalize(stmt);
    if(rc != SQLITE_OK){
        printf("%s
", sqlite3_errmsg(db));
    }

    /*5. 删除数据*/
    sql = "DELETE FROM players WHERE age < 24;";
    rc = sqlite3_exec(db, sql, NULL, NULL, pz_err_msg);
    if (SQLITE_OK != rc) {
        printf("%s:sqlite3_exec insert "%s" failed
", __FUNCTION__, sql);
        if (NULL != pz_err_msg)    {
            printf("%s: error: %s
", __FUNCTION__, *pz_err_msg);
            sqlite3_free(pz_err_msg);
            pz_err_msg = NULL;    
        }
    }

    /*6. 查询所有数据2*/
    int nrow = 0, ncol = 0;
    int i, j;
    char **result;
    sql = "SELECT id, age, name FROM players;";
    rc = sqlite3_get_table(db, sql, &result, &nrow, &ncol, pz_err_msg);
    if (SQLITE_OK != rc)
    {
        printf("%s:sqlite3_get_table "%s" failed
", __FUNCTION__, sql);
        if (NULL != pz_err_msg)
        {
            printf("%s: error: %s
", __FUNCTION__, *pz_err_msg);
            sqlite3_free(pz_err_msg);
            pz_err_msg = NULL;
        }
    }
    for(i=0; i < nrow+1; i++) {
        for(j=0; j < ncol; j++) {
            printf("%s  ", result[i * ncol + j]);
        }
        printf("
");
    }

    /*5. 关闭数据库*/
    sqlite3_close(db);
    return 0;
}