HarmonyOS 应用开发之RelationalStore开发

场景介绍

RelationalStore提供了一套完整的对本地数据库进行管理的机制，对外提供了一系列的增、删、改、查等接口，也可以直接运行用户输入的SQL语句来满足复杂的场景需要。

基本概念

• 谓词：数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。

• 结果集：指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便地拿到用户想要的数据。

约束限制

• 系统默认日志方式是WAL（Write Ahead Log）模式，系统默认落盘方式是FULL模式。

• 数据库中连接池的最大数量是4个，用以管理用户的读操作。

• 为保证数据的准确性，数据库同一时间只能支持一个写操作。

• 当应用被卸载完成后，设备上的相关数据库文件及临时文件会被自动清除。

• 使用API11新增的端云同步等接口时，需要确保已实现云服务功能。

接口说明

接口名称	描述
OH_Rdb_GetOrOpen(const OH_Rdb_Config *config, int *errCode)	获得一个相关的OH_Rdb_Store实例，操作关系型数据库。
OH_Rdb_Execute(OH_Rdb_Store *store, const char *sql)	执行包含指定参数但不返回值的SQL语句。
OH_Rdb_Insert(OH_Rdb_Store *store, const char *table, OH_VBucket *valuesBucket)	向目标表中插入一行数据。
OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates)	根据OH_Predicates的指定实例对象更新数据库中的数据。
OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates)	根据OH_Predicates的指定实例对象从数据库中删除数据。
OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length)	根据指定条件查询数据库中的数据。
OH_Rdb_DeleteStore(const OH_Rdb_Config *config)	删除数据库。
OH_VBucket_PutAsset(OH_VBucket *bucket, const char *field, Rdb_Asset *value)	把Rdb_Asset类型的数据放到指定的OH_VBucket对象中。
OH_VBucket_PutAssets(OH_VBucket *bucket, const char *field, Rdb_Asset *value, uint32_t count)	把Rdb_Asset数组类型的数据放到指定的OH_VBucket对象中。
OH_Rdb_SetDistributedTables(OH_Rdb_Store *store, const char *tables[], uint32_t count, Rdb_DistributedType type, const Rdb_DistributedConfig *config)	设置分布式数据库表。
OH_Rdb_FindModifyTime(OH_Rdb_Store *store, const char *tableName, const char *columnName, OH_VObject *values)	获取数据库指定表中指定列的数据的最后修改时间。
OH_Rdb_CloudSync(OH_Rdb_Store *store, Rdb_SyncMode mode, const char *tables[], uint32_t count, const Rdb_ProgressObserver *observer)	手动执行对指定表的端云同步，使用该接口需要实现云服务功能。
int OH_Data_Asset_SetName(Data_Asset *asset, const char *name)	为资产类型数据设置名称。
int OH_Data_Asset_SetUri(Data_Asset *asset, const char *uri)	为资产类型数据设置绝对路径。
int OH_Data_Asset_SetPath(Data_Asset *asset, const char *path)	为资产类型数据设置应用沙箱里的相对路径。
int OH_Data_Asset_SetCreateTime(Data_Asset *asset, int64_t createTime)	为资产类型数据设置创建时间。
int OH_Data_Asset_SetModifyTime(Data_Asset *asset, int64_t modifyTime)	为资产类型数据设置最后修改时间。
int OH_Data_Asset_SetSize(Data_Asset *asset, size_t size)	为资产类型数据设置占用空间大小。
int OH_Data_Asset_SetStatus(Data_Asset *asset, Data_AssetStatus status)	为资产类型数据设置状态码。
int OH_Data_Asset_GetName(Data_Asset *asset, char *name, size_t *length)	获取资产类型数据的名称。
int OH_Data_Asset_GetUri(Data_Asset *asset, char *uri, size_t *length)	获取资产类型数据的绝对路径。
int OH_Data_Asset_GetPath(Data_Asset *asset, char *path, size_t *length)	获取资产类型数据在应用沙箱内的相对路径。
int OH_Data_Asset_GetCreateTime(Data_Asset *asset, int64_t *createTime)	获取资产类型数据的创建时间。
int OH_Data_Asset_GetModifyTime(Data_Asset *asset, int64_t *modifyTime)	获取资产类型数据的最后修改时间。
int OH_Data_Asset_GetSize(Data_Asset *asset, size_t *size)	获取资产类型数据的占用空间大小。
int OH_Data_Asset_GetStatus(Data_Asset *asset, Data_AssetStatus *status)	获取资产类型数据的状态码。
Data_Asset *OH_Data_Asset_CreateOne()	创造一个资产类型实例。使用完毕后需要调用OH_Data_Asset_DestroyOne释放内存。
int OH_Data_Asset_DestroyOne(Data_Asset *asset)	销毁一个资产类型实例并回收内存。
Data_Asset **OH_Data_Asset_CreateMultiple(uint32_t count)	创造指定数量的资产类型实例。使用完毕后需要调用OH_Data_Asset_DestroyMultiple释放内存。
int OH_Data_Asset_DestroyMultiple(Data_Asset **assets, uint32_t count)	销毁指定数量的资产类型实例并回收内存。
int OH_Rdb_Subscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer)	为数据库注册观察者, 当分布式数据库中的数据发生更改时，将调用回调。
int OH_Rdb_Unsubscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer)	从数据库中删除指定类型的指定观察者。
int OH_Rdb_SubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer)	订阅RDB存储的自动同步进程, 当收到自动同步进度的通知时，将调用回调。
int OH_Rdb_UnsubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer)	取消订阅RDB存储的自动同步进程。

开发步骤

添加动态链接库

CMakeLists.txt中添加以下lib。

libnative_rdb_ndk.z.so

头文件

#include <database/data/data_asset.h>
#include <database/rdb/oh_cursor.h>
#include <database/rdb/oh_predicates.h>
#include <database/rdb/oh_value_object.h>
#include <database/rdb/oh_values_bucket.h>
#include <database/rdb/relational_store.h>
#include <database/rdb/relational_store_error_code.h>

1. 获取OH_Rdb_Store实例，创建数据库文件。其中dataBaseDir变量为应用沙箱路径，Stage模式下建议使用数据库目录，参考 Context 的databaseDir属性。FA模式下，由于没有接口获取数据库沙箱路径，可使用应用程序的文件目录，可参考 Context 的getFilesDir接口。area为数据库文件存放的安全区域，详见 contextConstant ，开发时需要实现由AreaMode枚举值对Rdb_SecurityArea枚举值的转换。示例代码如下所示：

   // 创建OH_Rdb_Config对象
   OH_Rdb_Config config;
   // 该路径为应用沙箱路径
   config.dataBaseDir = "xxx";
   // 数据库文件名
   config.storeName = "RdbTest.db";
   // 应用包名
   config.bundleName = "xxx";
   // 应用模块名
   config.moduleName = "xxx";
   // 数据库文件安全等级
   config.securityLevel = OH_Rdb_SecurityLevel::S1;
   // 数据库是否加密
   config.isEncrypt = false;
   // config所占内存大小
   config.selfSize = sizeof(OH_Rdb_Config);
   // 数据库文件存放的安全区域
   config.area = RDB_SECURITY_AREA_EL1;
   
   int errCode = 0;
   // 获取获取OH_Rdb_Store实例
   OH_Rdb_Store *store_ = OH_Rdb_GetOrOpen(&config, &errCode);
   

2. 获取到OH_Rdb_Store后，调用OH_Rdb_Execute接口创建表，并调用OH_Rdb_Insert接口插入数据。示例代码如下所示：

   char createTableSql[] = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, "
                           "AGE INTEGER, SALARY REAL, CODES BLOB)";
   // 执行建表语句
   OH_Rdb_Execute(store_, createTableSql);
   
   // 创建键值对实例
   OH_VBucket *valueBucket = OH_Rdb_CreateValuesBucket();
   valueBucket->putText(valueBucket, "NAME", "Lisa");
   valueBucket->putInt64(valueBucket, "AGE", 18);
   valueBucket->putReal(valueBucket, "SALARY", 100.5);
   uint8_t arr[] = {
        1, 2, 3, 4, 5};
   int len = sizeof(arr) / sizeof(arr[0