SQLite剖析之C/C++接口

SQLite剖析之C/C++接口

前言

　　SQLite3是SQLite一个全新的版本，它虽然是在SQLite2的代码基础之上开发的，但是使用了和之前的版本不兼容的数据库格式和API。SQLite3是为了满足以下的需求而开发的：支持UTF-16编码、用户自定义的文本比较方法、可以对BLOBs字段建立索引。SQLite 3.X版的和SQLite 2.X版的API非常相似，但是有一些重要的改变需要注意。3.X版的API增加到超过185个，所有API接口函数和数据结构的前缀都由"sqlite_"改为了"sqlite3_"，这是为了避免同时使用SQLite 2.X和SQLite 3.X这两个版本的时候发生链接冲突。这里概要地介绍一下SQLite的核心API，详细的API指南参考http://sqlite.com/capi3ref.html。
　　由于对于C语言应用什么数据类型来存放UTF-16编码的字符串并没有一致的规范，因此SQLite使用了普通的void*类型来指向UTF-16编码的字符串。客户端使用过程中可以把void*映射成适合他们的系统的任何数据类型。

　　一个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。

　　数据库连接对象和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()等等，用于提取结果集中各种类型的列数据。　　

核心对象和接口：
1. 核心对象：
　　在SQLite中最主要的两个对象是：database_connection和prepared_statement。database_connection对象是由sqlite3_open()接口函数创建并返回的，在应用程序使用任何其他SQLite接口函数之前，必须先调用该函数以便获得database_connnection对象，在随后的其他API调用中，都需要该对象作为输入参数以完成相应的工作。至于prepare_statement，我们可以简单地将它视为编译后的SQL语句，因此，所有和SQL语句执行相关的函数也都需要该对象作为输入参数以完成指定的SQL操作。
2. 核心接口：
    1). sqlite3_open
    上面已经提到过这个函数了，它是操作SQLite数据库的入口函数。该函数返回的database_connection对象是很多其他SQLite API的句柄参数。注意，我们通过该函数既可以打开已经存在的数据库文件，也可以创建新的数据库文件。对于该函数返回的database_connection对象，我们可以在多个线程之间共享该对象的指针，以便完成和数据库相关的任意操作。然而在多线程情况下，更为推荐的使用方式是，为每个线程创建独立的database_connection对象。对于该函数还有一点也需额外说明，我们没有必要为了访问多个数据库而创建多个数据库连接对象，因为通过SQLite自带的ATTACH命令可以在一个连接中方便的访问多个数据库。
    2). sqlite3_prepare
    该函数将SQL文本转换为prepared_statement对象，并在函数执行后返回该对象的指针。事实上，该函数并不会评估参数指定SQL语句，它仅仅是将SQL文本初始化为待执行的状态。最后需要指出的，对于新的应用程序，可以使用sqlite3_prepare_v2接口函数来替代该函数以完成相同的工作。
    3). sqlite3_step
    该函数用于评估sqlite3_prepare函数返回的prepared_statement对象，在执行完该函数之后，prepared_statement对象的内部指针将指向其返回的结果集的第一行。如果打算进一步迭代其后的数据行，就需要不断的调用该函数，直到所有的数据行都遍历完毕。然而对于INSERT、UPDATE和DELETE等DML语句，该函数执行一次即可完成。
    4). sqlite3_column
    该函数用于获取当前行指定列的数据，然而严格意义上讲，此函数在SQLite的接口函数中并不存在，而是由一组相关的接口函数来完成该功能，其中每个函数都返回不同类型的数据，如：
    sqlite3_column_blob
    sqlite3_column_bytes
    sqlite3_column_bytes16
    sqlite3_column_double
    sqlite3_column_int
    sqlite3_column_int64
    sqlite3_column_text
    sqlite3_column_text16
    sqlite3_column_type
    sqlite3_column_value
    sqlite3_column_count
    其中，sqlite3_column_count函数用于获取当前结果集中的字段数目。下面是使用sqlite3_step和sqlite3_column函数迭代结果集中每行数据的伪代码(注意这里作为示例代码简化了对字段类型的判断)：　

int fieldCount = sqlite3_column_count(...);
while (sqlite3_step(...) <> EOF) {
    for (int i = 0; i < fieldCount; ++i) {
        int v = sqlite3_column_int(...,i);
    }
}

　 5). sqlite3_finalize
    该函数用于销毁prepared statement对象，否则将会造成内存泄露。
    6). sqlite3_close
    该函数用于关闭之前打开的database_connection对象，其中所有和该对象相关的prepared_statements对象都必须在此之前先被销毁。

参数绑定：
　　和大多数关系型数据库一样，SQLite的SQL文本也支持变量绑定，以便减少SQL语句被动态解析的次数，从而提高数据查询和数据操作的效率。要完成该操作，我们需要使用SQLite提供的另外两个接口API，sqlite3_reset和sqlite3_bind。见如下示例：

void test_parameter_binding() {
　　//1. 不带参数绑定的情况下插入多条数据。
　　char strSQL[128];
　　for (int i = 0; i < MAX_ROWS; ++i) {
　　　　sprintf(strSQL,"insert into testtable values(%d)",i);
　　　　sqlite3_prepare_v2(..., strSQL);
　　　　sqlite3_step(prepared_stmt);
　　　　sqlite3_finalize(prepared_stmt);
　　}
　　//2. 参数绑定的情况下插入多条数据。
　　string strSQLWithParameter = "insert into testtable values(?)";
　　sqlite3_prepare_v2(..., strSQLWithParameter);
　　for (int i = 0; i < MAX_ROWS; ++i) {
　　　　sqlite3_bind(...,i);
　　　　sqlite3_step(prepared_stmt);
　　　　sqlite3_reset(prepared_stmt);
　　}
　　sqlite3_finalize(prepared_stmt);
}

　　这里首先需要说明的是，SQL语句"insert into testtable values(?)"中的问号(?)表示参数变量的占位符，该规则在很多关系型数据库中都是一致的，因此这对于数据库移植操作还是比较方便的。

　　通过上面的示例代码，明显可以看出参数绑定写法的执行效率要高于每次生成不同的SQL语句的写法，即(2)在效率上要明显优于(1)，下面是针对这两种写法的具体比较：
　　 1.单单从程序表面来看，前者在for循环中执行了更多的任务，比如字符串的填充、SQL语句的prepare，以及prepared_statement对象的释放。
　　 2.在SQLite的官方文档中明确的指出，sqlite3_prepare_v2的执行效率往往要低于sqlite3_step的效率。
　　 3.当插入的数据量较大时，后者带来的效率提升还是相当可观的。

一、打开和关闭数据库连接

int sqlite3_open(  
  const char *filename,   /* Database filename (UTF-8) */  
  sqlite3 **ppDb          /* OUT: SQLite db handle */  
);  
int sqlite3_open16(  
  const void *filename,   /* Database filename (UTF-16) */  
  sqlite3 **ppDb          /* OUT: SQLite db handle */  
);  
int sqlite3_open_v2(  
  const char *filename,   /* Database filename (UTF-8) */  
  sqlite3 **ppDb,         /* OUT: SQLite db handle */  
  int flags,              /* Flags */  
  const char *zVfs        /* Name of VFS module to use */  
);  
int sqlite3_close(sqlite3*);  
int sqlite3_close_v2(sqlite3*);  
int sqlite3_errcode(sqlite3 *db);  
int sqlite3_extended_errcode(sqlite3 *db);  
const char *sqlite3_errmsg(sqlite3*);  
const void *sqlite3_errmsg16(sqlite3*); 

　　建立到一个SQLite数据库文件的连接，返回连接对象。如果数据库文件不存在，则创建这个文件，函数返回一个整数错误代码。许多SQLite接口需要一个指向连接对象的指针作为第一个参数，这个函数用来创建一个数据库连接对象。sqlite3_open()和sqlite3_open16()的不同之处在于sqlite3_open16()使用UTF-16编码（使用本地主机字节顺序）传递数据库文件名。如果要创建新数据库，sqlite3_open16()将内部文本转换为UTF-16编码，反之sqlite3_open()将文本转换为UTF-8编码。打开或者创建数据库的命令会被缓存，直到这个数据库真正被调用的时候才会被执行。而且允许使用PRAGMA声明来设置如本地文本编码或默认内存页面大小等选项和参数。
　　sqlite3_close()关闭数据库连接，在关闭之前所有准备好的SQL语句对象都要被销毁。
　　sqlite3_errcode()通常用来获取最近调用的API接口返回的错误代码。sqlite3_errmsg()则用来得到这些错误代码所对应的文字说明。这些错误信息将以UTF-8的编码返回，并且在下一次调用任何SQLiteAPI函数的时候被清除。sqlite3_errmsg16()和sqlite3_errmsg()大体上相同，除了返回的错误信息将以UTF-16本机字节顺序编码。
　　SQLite的返回码定义如下:

#define SQLITE_OK           0   /* Successful result */  
/* beginning-of-error-codes */