SQLite3 C语言API入门



本文转载自http://www.blogjava.net/xylz/archive/2012/09/25/388519.html

SQLite3 C语言API入门

 

下载SQLite3

 

我们下载sqlite源码包，只需要其中的sqlite3.c、sqlite.h即可。

 

 

最简单的一个创建表操作

 

#include <stdio.h>

 #include "sqlite3.h"

 

int main(int argc,char *argv[]){

    const char *sql_create_table="create table t(id int primary key,msgvarchar(128))";

    char *errmsg = 0;

    int ret = 0;

 

    sqlite3 *db = 0;

    ret = sqlite3_open("./sqlite3-demo.db",&db);

    if(ret != SQLITE_OK){

        fprintf(stderr,"Cannot open db: %s\n",sqlite3_errmsg(db));

        return 1;

    }

    printf("Open database\n");

 

    ret = sqlite3_exec(db,sql_create_table,NULL,NULL,&errmsg);

    if(ret != SQLITE_OK){

        fprintf(stderr,"create table fail: %s\n",errmsg);

    }

    sqlite3_free(errmsg);

    sqlite3_close(db);

 

    printf("Close database\n");

 

    return 0;

 }

 

 

 

在这个操作中我们执行了如下操作：

•打开数据库

•执行SQL语句

•关闭数据库

 

当然这中间会有一些状态的判断以及内存指针的释放等。

 

打开数据库的API如下：

 

 

int sqlite3_open(

  const char *filename,  /*Database filename (UTF-8) */

  sqlite3 **ppDb         /* OUT:SQLite db handle */

 );

这里会引入一个非常复杂的sqlite3的数据结构。这个根据需要以后酌情了解些。

 

 

打开数据库除了这种形式意外，还有sqlite3_open、sqlite3_open16、sqlite3_open_v2几种形式，基本上类似。

 

大部分sql操作都可以通过sqlite3_exec来完成，它的API形式如下：

 

 

int sqlite3_exec(

  sqlite3*,                                 /* An opendatabase */

  const char *sql,                          /* SQL to beevaluated */

  int (*callback)(void*,int,char**,char**), /* Callback function */

  void *,                                   /* 1stargument to callback */

  char **errmsg                             /* Error msgwritten here */

 );

 

 

 

各个参数的意义为：

•sqlite3描述的是数据库句柄

•sql要执行的SQL语句

•callback回调函数

•void *回调函数的第一个参数

•errmsg错误信息，如果没有SQL问题则值为NULL

 

回调函数式一个比较复杂的函数。它的原型是这样的:

 

 

int callback(void *params,intcolumn_size,char **column_value,char **column_name){

 

 

 

每一个参数意义如下：

•params是sqlite3_exec传入的第四个参数

•column_size是结果字段的个数

•column_value是返回记录的一位字符数组指针

•column_name是结果字段的名称

 

通常情况下callback在select操作中会使用到，尤其是处理每一行记录数。返回的结果每一行记录都会调用下“回调函数”。如果回调函数返回了非0，那么sqlite3_exec将返回SQLITE_ABORT，并且之后的回调函数也不会执行，同时未执行的子查询也不会继续执行。

 

对于更新、删除、插入等不需要回调函数的操作，sqlite3_exec的第三、第四个参数可以传入0或者NULL。

 

通常情况下sqlite3_exec返回SQLITE_OK=0的结果，非0结果可以通过errmsg来获取对应的错误描述。

 

Windows下编译：

D:\home\dev\c>cl /nologo /TCsqlite3-demo.c sqlite3.c

 

GCC下编译:

$ gcc -o sqlite3-demo.bin sqlite3-demo.csqlite3.c

 

 

删除表操作

 

为了防止垃圾数据，我们在加载数据库的时候删除表操作。

 

简单的删除操作可以直接使用sqlite3_exec即可。这里不需要回调函数以及回调函数的参数。当然需要可以关注sqlite3_exec返回的结果是否为SQLITE_OK的值。

 

 

   const char *sql_drop_table="drop table if exists t";

    const char *sql_create_table="create table t(id int primary key,msgvarchar(128))";

 

    sqlite3_exec(db,sql_drop_table,0,0,&errmsg);

    sqlite3_exec(db,sql_create_table,0,0,&errmsg);

 

 

 

插入数据

 

插入第一条数据

 

 

   ret = sqlite3_exec(db,"insert into t(id,msg) values(1,'AdyLiu')",NULL,NULL,&errmsg);

    printf("Insert a record %s\n",ret == SQLITE_OK ?"OK":"FAIL");

 

 

 

返回值ret为SQLITE_OK即操作成功。

 

 

插入多条数据，并删除数据

 

 

   ret = sqlite3_exec(db,"insert into t(id,msg) values(1,'AdyLiu')",NULL,NULL,&errmsg);

    printf("Insert a record %s\n",ret == SQLITE_OK ?"OK":"FAIL");

    ret = sqlite3_exec(db,"insert into t(id,msg)values(2,'IMXYLZ')",NULL,NULL,&errmsg);

    printf("Insert a record %s\n",ret == SQLITE_OK ?"OK":"FAIL");

    ret = sqlite3_exec(db,"delete from t where id <3",NULL,NULL,&errmsg);

    printf("Delete records: %s\n",ret == SQLITE_OK ?"OK":"FAIL");

插入多条数据，简单的使用sqlite3_exec进行SQL执行即可。当然这里是完整的SQL字符串。

 

 

预编译操作

 

   int i = 0;

   sqlite3_stmt *stmt;

   char ca[255];

 

   //prepare statement

   sqlite3_prepare_v2(db,"insert into t(id,msg)values(?,?)",-1,&stmt,0);

   for(i=10;i<20;i++){

       sprintf(ca,"HELLO#%i",i);

       sqlite3_bind_int(stmt,1,i);

       sqlite3_bind_text(stmt,2,ca,strlen(ca),NULL);

       sqlite3_step(stmt);

       sqlite3_reset(stmt);

   }

   sqlite3_finalize(stmt);

预编译操作比较麻烦的，完整的预编译操作的流程是： 1.通过sqlite3_prepare_v2()创建一个sqlite3_stmt对象

2.通过sqlite3_bind_*()绑定预编译字段的值

3.通过sqlite3_step()执行SQL语句

4.通过sqlite3_reset()重置预编译语句，重复操作2多次

5.通过sqlite3_finalize()销毁资源

 

sqlite3_prepare_v2()有个多种类似的形式，完整的API语法是：

 

 

int sqlite3_prepare(

  sqlite3*db,            /* Database handle */

  const char *zSql,      /* SQLstatement, UTF-8 encoded */

  int nByte,             /* Maximumlength of zSql in bytes. */

  sqlite3_stmt **ppStmt, /* OUT:Statement handle */

  const char **pzTail    /* OUT:Pointer to unused portion of zSql */

 );

 

 

 

各个参数的定义为：

•db为sqlite3的句柄

•zSql为要执行的SQL语句

•nByte为要执行语句在zSql中的最大长度，如果是负数，那么就需要重新自动计算

•ppStmt为预编译后的句柄

•pzTail预编译后剩下的字符串（未预编译成功或者多余的）的指针，通常没什么用，传入0或者NULL即可。

 

 

 绑定参数sqlite3_bind_*有多种形式，分别对应不同的数据类型:

 

 

int sqlite3_bind_blob(sqlite3_stmt*, int,const void*, int n, void(*)(void*));

int sqlite3_bind_double(sqlite3_stmt*, int,double);

int sqlite3_bind_int(sqlite3_stmt*, int,int);

int sqlite3_bind_int64(sqlite3_stmt*, int,sqlite3_int64);

int sqlite3_bind_null(sqlite3_stmt*, int);

int sqlite3_bind_text(sqlite3_stmt*, int,const char*, int n, void(*)(void*));

int sqlite3_bind_text16(sqlite3_stmt*, int,const void*, int, void(*)(void*));

int sqlite3_bind_value(sqlite3_stmt*, int,const sqlite3_value*);

int sqlite3_bind_zeroblob(sqlite3_stmt*,int, int n);

 

 

 

 

预编译SQL语句中可以包含如下几种形式：

•?

•?NNN

•:VVV

•@VVV

•$VVV

 

NNN代表数字，VVV代表字符串。

 

如果是?或者?NNN，那么可以直接sqlite3_bind_*()进行操作，如果是字符串，还需要通过sqlite3_bind_parameter_index()获取对应的index，然后再调用sqlite3_bind_*()操作。这通常用于构造不定条件的SQL语句（动态SQL语句）。

 

 

查询操作

 

回调函数的解释参考最上面的描述。首先声明一个回调函数。

int print_record(void *,int,char **,char**);

 

 

查询代码

 

 

   //select data

   ret = sqlite3_exec(db,"select * fromt",print_record,NULL,&errmsg);

    if(ret != SQLITE_OK){

        fprintf(stderr,"query SQL error: %s\n",errmsg);

    }

 

 

 

现在定义回调函数，只是简单的输出字段值。

 

 

int print_record(void *params,intn_column,char **column_value,char **column_name){

    int i;

    for(i=0;i<n_column;i++){

        printf("\t%s",column_value[i]);

    }

    printf("\n");

    return 0;

 }

 

 

 

不使用回调的查询操作

 

定义使用的变量

 char**dbresult; int j,nrow,ncolumn,index;

 

查询操作

 

 

   //select table

   ret = sqlite3_get_table(db,"select * fromt",&dbresult,&nrow,&ncolumn,&errmsg);

    if(ret == SQLITE_OK){

        printf("query %i records.\n",nrow);

        index=ncolumn;

        for(i=0;i<nrow;i++){

            printf("[%2i]",i);

            for(j=0;j<ncolumn;j++){

                printf("%s",dbresult[index]);

                index++;

            }

            printf("\n");

        }

    }

    sqlite3_free_table(dbresult);

 

 

 

sqlite3_get_table的API语法：

 

 

int sqlite3_get_table(

  sqlite3 *db,         /* An opendatabase */

  const char *zSql,    /* SQL to beevaluated */

  char ***pazResult,   /* Resultsof the query */

  int *pnRow,          /* Number ofresult rows written here */

  int *pnColumn,       /* Number ofresult columns written here */

  char **pzErrmsg      /* Error msgwritten here */

 );

void sqlite3_free_table(char **result);

 

 

 

其中：

•db是sqlite3的句柄

•zSql是要执行的sql语句

•pazResult是执行查询操作的返回结果集

•pnRow是记录的行数

•pnColumn是记录的字段个数

•pzErrmsg是错误信息

 

由于sqlite3_get_table是sqlite3_exec的包装，因此返回的结果和sqlite3_exec类似。

 

pazResult是一个(pnRow+1)*pnColumn结果集的字符串数组，其中前pnColumn个结果是字段的名称，后pnRow行记录是真实的字段值，如果某个字段为空，则对应值为NULL。

 

最后需要通过sqlite3_free_table()释放完整的结果集。

 

 

更新操作

 sqlite3_exec(db,"update t setmsg='MESSAGE#10' where id=10",NULL,NULL,&errmsg);

 

当然了，我们也可以使用预编译方法进行更新操作。

 

 

受影响的记录数

 

我们可以使用sqlite3_change(sqlite3 *)的API来统计上一次操作受影响的记录数。

 ret= sqlite3_exec(db,"delete from t",NULL,NULL,&errmsg);

 

if(ret == SQLITE_OK){

 

printf("delete records:%i\n",sqlite3_changes(db));

 

}

 

 

总结

 

这里我们接触了SQLITE3的13个API：

•sqlite3_open()

•sqlite3_exec()

•sqlite3_close()

•sqlite3_prepare_v2

•sqlite3_bind_*()

•sqlite3_bind_parameter_index()

•sqlite3_step()

•sqlite3_reset()

•sqlite3_finalize()

•sqlite3_get_table

•sqlite3_change()

•sqlite3_free()

•sqlite3_free_table()

 

事实上截止到SQLITE3.7.14(2012/09/03)一共提供了204个API函数（http://www.sqlite.org/c3ref/funclist.html）。

 

但最精简的API函数大概有6个：

•sqlite3_open()

•sqlite3_prepare()

•sqlite3_step()

•sqlite3_column()

•sqlite3_finalize()

•sqlite3_close()

 

核心API也就10个（在精简API基础上增加4个）：

•sqlite3_exec()

•sqlite3_get_table()

•sqlite3_reset()

•sqlite3_bind()

 

因此掌握起来还是比较容易的。

 

 完整的源码地址：https://gist.github.com/3780669