SQLite for RT-Thread

简介

SQLite 是一个小型，快速，独立的高可靠性全功能 SQL 数据库引擎。SQLite 是全世界部署最广泛的 SQL 数据库引擎。它内置在几乎所有的移动电话、大多数计算机以及部分嵌入式设备中，并被捆绑在人们每天使用的无数其他应用程序中。

文件说明

| 名称 | 说明 | | ------------------------ | ---------------------------------------------------------------- | | sqlite3.c | sqlite3源文件 | | sqlite3.h | sqlite3头文件 | | sqlite_config_rtthread.h | sqlite3在rt-thread上的配置文件 | | rtthread_io_methods.c | rt-thread为sqlite提供的底层文件IO接口 | | rtthread_mutex.c | rt-thread为sqlite提供的互斥量操作接口 | | rtthread_vfs.c | rt-thread为sqlite提供的VFS(虚拟文件系统)接口 | | dbhelper.c | sqlite3操作接口封装，简化应用 | | dbhelper.h | dbhelper头文件，向外部声明封装后的接口，供用户调用 | | student_dao.c | 简单的DAO层例程，简单展示了对dbhelper的使用方法 | | student_dao.h | 数据访问对象对外接口声明，线程可通过调用这些接口完成对该表的操作 |

获取

在ENV中配置如下

RT-Thread online packages  ---> 
    system packages  ---> 
        --- SQLite: a self-contained, high-reliability, embedded, full-featured, public-domain, SQL database engine.
        (1024) SQL statements max length
        [*]   Enable example

配置项说明：

| 名称 | 说明 | | ------------------------- | --------------------------------------------------- | | SQL statements max length | SQL语句最大长度，请根据实际业务需求设置。 | | Enable example | 选择是否使能DAO层例程，例程是模拟了学生成绩录入查询 |

依赖

• RT-Thread 3.X+
• DFS组件

dbhelp接口说明

dbhelp是对sqlite3操作接口的封装，目的是使用户更加简单地操作sqlite。

数据库文件完整路径

数据库文件的默认存放完整路径是"/rt.db"，用户可根据实际需求在dbhelper.h中修改。

#define DB_NAME "/rt.db"

初始化

dbhelp初始化，其中包含了sqlite的初始化及互斥量创建。用户无需再对数据库及锁初始化。

int db_helper_init(void);

| 参数 | 说明 | | --------- | ---------- | | void | | | 返回 | | | RT_EOK | 初始化成功 | | -RT_ERROR | 初始化失败 |

数据库创建

int db_create_database(const char *sqlstr);

| 参数 | 说明 | | ------ | --------------- | | sqlstr | 创建表的SQL语句 | | 返回 | | | 0 | 成功 | | 非0 | 失败 | 输入形参sqlstr应当是一条创建表的SQL语句，例：

const char *sql = "CREATE TABLE student(id INTEGER PRIMARY KEY AUTOINCREMENT,name varchar(32) NOT NULL,score INT NOT NULL);";
return db_create_database(sql);

可进行数据绑定的非查询操作

用于非查询的操作，可通过回调进行数据绑定，db_nonquery_operator中开启了事务功能，支持操作失败后回滚。

int db_nonquery_operator(const char *sqlstr, int (*bind)(sqlite3_stmt *, int index, void *arg), void *param);

| 参数 | 说明 | | ------ | ------------------------------------------------------------ | | sqlstr | 非查询类SQL语句，如果有多个SQL语句要执行，请用;将SQL语句分开 | | bind | 数据绑定回调 | | param | 在内部将赋值给bind的输入参数void *arg | | 返回 | | | 0 | 成功 | | 非0 | 失败 | 注：该接口请勿用于查询类操作。 bind需要用户实现： | 参数 | 说明 | | ---------------------- | -------------------------------------------------------------------- | | stmt | sqlite3_stmt预备语句对象 | | index | 如果有多条SQL语句要执行，index表示第index条SQL语句，注意index从1开始 | | arg | 即db_nonquery_operator的四三个形参void *param | | 返回 | | | SQLITE_OK或SQLITE_DONE | 成功 | | 其他 | 失败(如果用户提供的bind返回失败，db_nonquery_operator将执行回滚操作) |

普通SQL语句在执行时是需要解析、编译、执行的，而sqlite3_stmt结构是已经通过sqlite3_prepare函数对sql语句解析和编译了的，而在SQL语句中在要绑定数据的位置放置?作为占位符，即可通过数据绑定接口sqlite3_bind_(此处为通配符，取值为int，double，text等，详情请见sqlite文档)。这种在批量操作时，由于绕开了解释编译的过程，直接在sqlite3_stmt的基础上对绑定值进行修改，因而会使整体操作效率势大大提升。具体应用请见student_dao.c

带可变参数的非查询操作

int db_nonquery_by_varpara(const char *sql, const char *fmt, ...);

| 参数 | 说明 | | ---- | ----------------------------------------------------------------- | | sql | 非查询类SQL语句 | | fmt | 格式符，配合后面的可变参数使用，用法类似printf，只支持%d,%f,%s,%x | | ... | 可变形参 | | 返回 | | | 0 | 成功 | | 非0 | 失败 | 注：该接口请勿用于查询类操作。 例：

int student_del(int id)
{
    return db_nonquery_by_varpara("delete from student where id=?;", "%d", id);
}

SQL语句"delete from student where id=?;"中，“?”为占位符，id将会按照%d的格式被绑定到通过对前述SQL语句解释编译后的sqlite3_stmt中。

开启事务的非查询操作

db_nonquery_transaction开启了事务功能，支持操作失败后回滚。

int db_nonquery_transaction(int (*exec_sqls)(sqlite3 *db, void *arg), void *arg);

| 参数 | 说明 | | --------- | ---------------------------------------------- | | exec_sqls | SQL执行回调 | | arg | 内部赋值给exec_sqls的void *arg形参作为输入参数 | | 返回 | | | 0 | 成功 | | 非0 | 失败 |

exec_sqls： | 参数 | 说明 | | ---------------------- | ---------------------------------------------------------------------------- | | db | 数据库描述符 | | arg | 来自于db_nonquery_transaction的形参void *arg | | 返回 | | | SQLITE_OK或SQLITE_DONE | 成功 | | 其他 | 失败(如果用户提供的exec_sqls返回失败，db_nonquery_transaction将执行回滚操作) | 注：该接口请勿用于查询类操作。 db_nonquery_transaction的自由度比较大，内部开启事务后就开始执行exec_sqls，用户可在exec_sqls通过调用SQLite的接口进行相关的数据库操作。执行完exec_sqls后提交事务。如果有失败情况会回滚。

带变参的查询操作

用户可通过sql语句及变参进行查询操作

int db_query_by_varpara(const char *sql, int (*create)(sqlite3_stmt *stmt, void *arg), void *arg, const char *fmt, ...);

| 参数 | 说明 | | ---------------------- | ----------------------------------------------------------------- | | sql | SQL语句 | | create | 创建用来接收查询结果的数据对象 | | arg | 将赋值给create的void *arg作为输入参数 | | fmt | 格式符，配合后面的可变参数使用，用法类似printf，只支持%d,%f,%s,%x | | ... | 变参 | | 返回（creat!=NULL） | | | 返回create的返回值 | | | 返回（create==NULL时） | | | 0 | |

create回调： | 参数 | 说明 | | --------------------------------- | ---------------------------------------------------- | | stmt | sqlite3_stmt预备语句对象 | | arg | 接收来由db_query_by_varpara的void *arg传递进来的形参 | | 返回 | | | 返回值将被db_query_by_varpara返回 | |

用户可通过调用在通过调用db_stmt_get_int，db_stmt_get_text等接口配合sqlite3_step获取查询结果，回调接收不定数量的条目时请注意内存用量，或在查询前先通过db_query_count_result确定条符合条件的条目数量。

获取符合条件的结果数量

调用此接口返回结果条目数量，注意，如的SQL语句应为SELECT COUNT为前缀的查询数量的语句。接口中只会获取第一行第一列。

int db_query_count_result(const char *sql);

| 参数 | 说明 | | ------ | ----------------------------------------------------------------- | | sql | SQL语句，仅限查询数量语句，如：select count(*) from sqlite_master | | 返回 | | | 非负值 | 符合条件的条目的数量 | | 负数 | 查询失败 | 例如，查询数据库中表的数量：

nums = db_query_count_result("select count(*) from sqlite_master where type = 'table';");

在查询结果中获取blob型数据

在查询时获取blob类型数据，blob类型在SQLite 中指二进制大对象，完全根据其输入值存储。

int db_stmt_get_blob(sqlite3_stmt *stmt, int index, unsigned char *out)

| 参数 | 说明 | | ------ | ---------------------------------------------- | | stmt | sqlite3_stmt预备语句对象 | | index | 数据索引 | | out | 输出参数，获取到的数据将存入该指针指向的地址中 | | 返回 | | | 非负值 | 获取的数据长度 | | 负数 | 查询失败 | |

在查询结果中获取text型数据

在查询时获取文本类型数据，text类型值是一个文本字符串。

int db_stmt_get_text(sqlite3_stmt *stmt, int index, char *out)

| 参数 | 说明 | | ------ | ---------------------------------------------- | | stmt | sqlite3_stmt预备语句对象