Sqlite3 浅析

前言：

Android中sqlite最终调用的是底层的Sqlite3库，Sqlite3 中接口比较多，这里先简单列举几个常用的，后续进行不断的补充。

 

1. sqlite3_open

 原型：

SQLITE_API int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);

意义：

通过sqlite3_open打开db 文件。如果该db文件不存在，会创建一个新的db文件，db的名字就是filename。

sqlite3_open不是sqlite操作的第一个接口，还有version，source id等接口，下面会介绍。

参数：

第一个参数：要打开的db的详细路径名；

第二个参数：sqlite3 的handle；将sqlite3 指针的地址传入。

返回值：

返回值int 前面的SQLITE_API 不用太在意，就是一个标志，代表sqlite的接口，没其他意义。

如果db被成功打开，返回SQLITE_OK，否则返回错误码。错误码信息看函数sqlite3_errmsg()，下面会说明。

 

类似的open接口还有：

SQLITE_API int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
SQLITE_API 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 */
);

sqlite3_open_v2 同sqlite3_open接口，采用的编码格式为UTF-8，而sqlite_open16采用的编码格式为UTF-16。

sqlite3_open_v2较sqlite3_open接口多了两个控制选项，flags 可以是（前面3个与后面5个结合使用）：

• SQLITE_OPEN_READONLY
• SQLITE_OPEN_READWRITE
• SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE（sqlite3_open 和sqlite3_open16默认的方式）
• SQLITE_OPEN_NOMUTEX
• SQLITE_OPEN_FULLMUTEX
• SQLITE_OPEN_SHAREDCACHE
• SQLITE_OPEN_PRIVATECACHE
• SQLITE_OPEN_URI

 

2. sqlite3_close

原型：

SQLITE_API int sqlite3_close(sqlite3*);
SQLITE_API int sqlite3_close_v2(sqlite3*);

意义：

析构前面使用sqlite3_open打开的数据库sqlite3对象，任何与这个连接相关的准备语句必须在调用这个关闭函数之前被释放

参数：

sqlite3_open 时候的sqlite3 指针。传入NULL代表不做任何操作。

返回值：

如果在close的时候prepare或backup还没有完成，会返回SQLITE_BUSY；

返回 SQLITE_OK 表示对象被成功析构, 以及所有相关的资源被成功回收应用程序必须在关闭之前 "完成(finalize)" 所有的 "预编译语句(prepared statements)",并且关闭所有的 "二进制句柄绑定(BLOB handle)"；

 

3. sqlite3_exec

原型：

SQLITE_API int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

意义：

用于执行多条语句，以分号隔开；

该函数包裹了sqlite3_prepare(), sqlte3_step() 和 sqlite3_finalize() 函数, 这样,用户就可以执行简单的代码执行多条 SQL 语句；

当在执行该SQL语句发生错误时, 执行将发生中断, 并且后面的语句也全部被忽略；

当sqlite3_exec执行的时候，无法再次使用sqlite3_exec调用sql 语句（加锁了）。

参数：

第一个参数：sqlite3的handle；

第二个参数：sql 语句；如果为NULL，不做任何处理；

第三个参数：回调函数。如果设置不为NULL，会将每一行结果通过回调返回，如果设置为NULL，会忽略查询结果；

第四个参数：callback的第一个参数；

第五个参数：存放查询过程的所有error信息。如果 errmsg参数不为空任何错误信息将会被写进由 sqlite3_malloc() 得到的的内存空间中, 即 errmsg 指向的内存.为了避免内存泄漏, 应用程序应该在不需要该错误信息后立即调用 sqlite3_free() 释放该内存空间. 如果 errmsg参数不为 NULL, 并且没有错误发生, errmsg 被设置为 NULL。

返回值：

如果sqlite3_exec返回非0（SQLITE_OK），sqlite3_exec不会再调用callback，并且不会处理后面的语句，最后sqlite3_exec会返回SQLIET_ABORT。

 

5. sqlite3_callback

typedef int (*sqlite3_callback)(void*,int,char**, char**);

第 4 节中的callback 在sqlite3中有定义。

第一个参数：sqlite3_exec的第四个参数；

第二个参数：查询的column的数量；

第三个参数：字符串数组，每一列一个值；

第四个参数：字符串数组，每一个column的名字

 

6. sqlite3_get_table

原型：

SQLITE_API int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);

意义：

sqlite3用于查询的接口；

这个接口是为了向后兼容而遗留的接口，不推荐使用；

若查出来的results table 行数N，列数M，那么这张表实际大小为(N+1)*M，因为第一行为column 的name；

第三个参数为一个指针指向result table，在不使用的时候使用sqlite3_free_table() 函数来释放，sqlite3_free() 不安全；

参数：

第一个参数：sqlite3的handle

第二个参数：需要执行的sql 语句；

第三个参数：查询出来的results table地址

第四个参数：行数

第五个参数：列数

第六个参数：查询中遇到的error信息存放点

 

7. sqlite3_version

SQLITE_API SQLITE_EXTERN const char sqlite3_version[];

返回宏SQLITE_VERSION

例如：

#define SQLITE_VERSION        "3.25.2"

 

8. sqlite3_libversion_number

SQLITE_API int sqlite3_libversion_number(void);

返回宏QLITE_VERSION_NUMBER

例如：

#define SQLITE_VERSION_NUMBER 3025002

 

9. sqlite3_sourceid

SQLITE_API const char *sqlite3_sourceid(void);

返回宏SQLITE_SOURCE_ID
 

10.sqlite3_errmsg

SQLITE_API int sqlite3_errcode(sqlite3 *db);
SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
SQLITE_API const char *sqlite3_errmsg(sqlite3*);
SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
SQLITE_API const char *sqlite3_errstr(int);

sqlite3针对错误信息的函数还是比较多的。

sqlite3_errcode：返回result code 或者extended result code

sqlite3_extended_errcode：返回extended result code

sqlite3_errmsg：返回时字符描述错误码，UTF-8编码格式

sqlite3_errmsg16：同sqlite3_errmsg，不过是UTF-16的编码

sqlite3_errstr：同sqlite3_errmsg，