diff --git a/zh-cn/device-dev/subsystems/Readme-CN.md b/zh-cn/device-dev/subsystems/Readme-CN.md index 3891de8b5c62980d5585105cd162223503912edb..339da88c4922fbf943411cda892dbb8594260a5a 100755 --- a/zh-cn/device-dev/subsystems/Readme-CN.md +++ b/zh-cn/device-dev/subsystems/Readme-CN.md @@ -40,6 +40,10 @@ - [唤醒词识别SDK的开发示例](subsys-aiframework-demo-sdk.md) - [唤醒词识别插件的开发示例](subsys-aiframework-demo-plugin.md) - [唤醒词识别配置文件的开发示例](subsys-aiframework-demo-conf.md) +- [数据管理](subsys-database.md) + - [关系型数据库](subsys-database-relational.md) + - [关系型数据库概述](subsys-database-relational-overview.md) + - [关系型数据库开发指导](subsys-database-relational-guide.md) - [Sensor服务](subsys-sensor.md) - [Sensor服务子系概述](subsys-sensor-overview.md) - [Sensor服务子系使用指导](subsys-sensor-guide.md) diff --git a/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001115980740.png b/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001115980740.png new file mode 100644 index 0000000000000000000000000000000000000000..4398ed073145d97228df055f4b6eb9137482619f Binary files /dev/null and b/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001115980740.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md b/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..26fe7bfc2c255d9c40e9bfc72236bbf30d7cf7b8 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md @@ -0,0 +1,202 @@ +# 关系型数据库开发指导 + +- [关系型数据库开发指导](#关系型数据库开发指导) + - [场景介绍](#场景介绍) + - [接口说明](#接口说明) + - [数据库的创建和删除](#数据库的创建和删除) + - [数据库的加密](#数据库的加密) + - [数据库谓词的使用](#数据库谓词的使用) + - [数据表的增删改查](#数据表的增删改查) + - [查询结果集的使用](#查询结果集的使用) + - [约束与限制](#约束与限制) + - [开发步骤](#开发步骤) + +## 场景介绍 + +关系型数据库是在SQLite基础上实现的本地数据操作机制，提供给用户无需编写原生SQL语句就能进行数据增删改查的方法，同时也支持原生SQL语句操作。 + +## 接口说明 +### 数据库的创建和删除 + +关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的API如下所示。 + +表1 数据库创建和删除API + +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStoreConfig | RdbStoreConfig(const std::string &path,
StorageMode storageMode = StorageMode::MODE_DISK,
bool readOnly = false,
const std::vector &encryptKey = std::vector(),
const std::string &journalMode = "",
const std::string &syncMode = "",
const std::string &databaseFileType = "",
const std::string &databaseFileSecurityLevel = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。 | +| RdbOpenCallback | int OnCreate(RdbStore &rdbStore) | 数据库创建时被回调，开发者可以在该方法中初始化表结构，并添加一些应用使用到的初始化数据。 | +| RdbOpenCallback | int OnUpgrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库升级时被回调。 | +| RdbOpenCallback | int OnDowngrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库降级时被回调。 | +| RdbHelper | std::shared_ptr\ GetRdbStore(const RdbStoreConfig &config, int version, RdbOpenCallback &openCallback, int &errCode) | 根据配置创建或打开数据库。 | +| RdbHelper | int DeleteRdbStore(const std::string &path) | 删除指定的数据库。 | + +### 数据库的加密 + +关系型数据库提供数据库加密的能力，在创建数据库时若指定了密钥，则会创建为加密数据库。再次使用此数据库时，需要指定该密钥，才能正确打开数据库。 + +表2 数据库修改密钥API +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | int ChangeEncryptKey(const std::vector &newKey) | 为数据库设置新的加密密钥。注：仅支持加密数据库更换加密密钥。 | + +### 数据库谓词的使用 + +关系型数据库提供了用于设置数据库操作条件的谓词AbsRdbPredicates，其中包括两个实现子类RdbPredicates和RawRdbPredicates： + +- RdbPredicates：开发者无需编写复杂的SQL语句，仅通过调用该类中条件相关的方法，如equalTo、notEqualTo、groupBy、orderByAsc、beginsWith等，就可自动完成SQL语句拼接，方便用户聚焦业务操作。 +- RawRdbPredicates：可满足复杂SQL语句的场景，支持开发者自己设置where条件子句和whereArgs参数。不支持equalTo等条件接口的使用。 + + 表7 数据库谓词API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值相等。 | + | RdbPredicates | AbsPredicates *NotEqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值不相等。 | + | RdbPredicates | AbsPredicates *BeginsWith(std::string field, std::string value) | 设置谓词条件，满足field字段以value值开头。 | + | RdbPredicates | AbsPredicates *Between(std::string field, std::string low, std::string high) | 设置谓词条件，满足field字段在最小值low和最大值high之间。 | + | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | 设置谓词条件，根据field字段升序排列。 | + | RdbPredicates | void SetWhereClause(std::string whereClause) | 设置where条件子句。 | + | RdbPredicates | void SetWhereArgs(std::vector\ whereArgs) | 设置whereArgs参数，该值表示where子句中占位符的值。 | + +### 数据表的增删改查 + +关系型数据库提供对本地数据增删改查操作的能力，相关API如下所示。 + +- 新增 + + 关系型数据库提供了插入数据的接口，通过ValuesBucket输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败时则返回-1。 + + 表3 数据表插入API + + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Insert(int64_t &outRowId, const std::string &table, const ValuesBucket &initialValues) | 向数据库插入数据。
  • table：待添加数据的表名。
  • initialValues：以ValuesBucket存储的待插入的数据。它提供一系列put方法，如PutString(const std::string &columnName, const std::string &value)，PutDouble(const std::string &columnName, double value)，用于向ValuesBucket中添加数据。
| + +- 删除 + + 调用删除接口，通过AbsRdbPredicates指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回0。 + + 表5 数据表删除API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Delete(int &deletedRows, const AbsRdbPredicates &predicates) | 删除数据。
  • deletedRows：删除的记录条数。
  • predicates：Rdb谓词，指定了删除操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + +- 更新 + + 调用更新接口，传入要更新的数据，并通过AbsRdbPredicates指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。 + + 表4 数据表更新API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | 更新数据库表中符合谓词指定条件的数据。
  • changedRows：更新的记录条数。
  • values：以ValuesBucket存储的要更新的数据。
  • predicates：指定了更新操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + +- 查询 + + 关系型数据库提供了两种查询数据的方式： + + - 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的SQL语句进行查询操作，无需用户传入原生的SQL语句。 + - 执行原生的SQL语句进行查询操作。 + + 表6 数据表查询API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | std::unique_ptr Query(const AbsRdbPredicates &predicates, const std::vector\ columns) | 查询数据。
  • predicates：谓词，可以设置查询条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
  • columns：规定查询返回的列。
| + | RdbStore | std::unique_ptr QuerySql(const std::string &sql, const std::vector\ &selectionArgs = std::vector\()) | 执行原生的用于查询操作的SQL语句。
  • sql：原生用于查询的sql语句。
  • selectionArgs：sql语句中占位符参数的值，若select语句中没有使用占位符，该参数可以设置为null。
| + +### 查询结果集的使用 + +关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 + + 表8 结果集API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | + | ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | + | ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | + | ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | + | ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | + | ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | + | ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | + | ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | + | ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | + | ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | + | ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | + | ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | 获取当前行指定列的值，以字节数组形式返回。 | + | ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | + +## 约束与限制 + +无。 + +## 开发步骤 + +1. 创建数据库。 + + a. 配置数据库相关信息，包括数据库的名称、存储模式、是否为只读模式等。 + + b. 初始化数据库表结构和相关数据。 + + c. 创建数据库。 + + 示例代码如下： + ``` + const std::string DATABASE_NAME = RDB_TEST_PATH + "RdbStoreTest.db"; + const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, salary REAL, blobType BLOB)"; + + class OpenCallback : public RdbOpenCallback { + public: + int OnCreate(RdbStore &rdbStore) override; + int OnUpgrade(RdbStore &rdbStore, int oldVersion, int newVersion) override; + }; + + int OpenCallback::OnCreate(RdbStore &store) + { + return store.ExecuteSql(CREATE_TABLE_TEST); + } + + RdbStoreConfig config(DATABASE_NAME); + OpenCallback callback; + + std::shared_ptr store = RdbHelper::GetRdbStore(config, 1, callback, 0); + ``` + +2. 插入数据。 + + a. 构造要插入的数据，以ValuesBucket形式存储。 + + b. 调用关系型数据库提供的插入接口。 + + c. 创建数据库。 + + 示例代码如下： + ``` + ValuesBucket values; + + values.PutInt("id", 1); + values.PutString("name", std::string("Tom")); + values.PutInt("age", 18); + values.PutDouble("salary", 100.5); + values.PutBlob("blobType", std::vector{ 1, 2, 3 }); + store->Insert(id, "test", values); + ``` + +3. 查询数据。 + + a. 构造用于查询的谓词对象，设置查询条件。 + + b. 指定查询返回的数据列。 + + c. 调用查询接口查询数据。 + + d. 调用结果集接口，遍历返回结果。 + + 示例代码如下： + ``` + std::vector columns = {"id", "name", "age", "salary"}; + + RdbPredicates predicates("test"); + predicates.EqualTo("age", "25")->OrderByAsc("salary"); + std::unique_ptr resultSet = store->Query(predicates, columns) + resultSet.goToNextRow(); + ``` + diff --git a/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md b/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..9cdfa7d1d3aed73df75331ad8ee19d2298cddd73 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md @@ -0,0 +1,45 @@ +# 关系型数据库概述 + +- [关系型数据库概述](#关系型数据库概述) + - [基本概念](#基本概念) + - [运作机制](#运作机制) + - [默认配置](#默认配置) + - [约束与限制](#约束与限制) + +关系型数据库（Relational Database，RDB）是一种基于关系模型来管理数据的数据库。OpenHarmony关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制，对外提供了一系列的增、删、改、查等接口，也可以直接运行用户输入的SQL语句来满足复杂的场景需要。 + +## 基本概念 + +- 关系型数据库 + + 基于关系模型来管理数据的数据库，以行和列的形式存储数据。 + +- 谓词 + + 数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。 + +- 结果集 + + 指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便的拿到用户想要的数据。 + +- SQLite数据库 + + 一款遵守ACID的轻型开源关系型数据库管理系统。 + +## 运作机制 +OpenHarmony关系型数据库对外提供通用的操作接口（即Rdb Store接口），底层使用第三方开源组件SQLite作为持久化存储引擎，支持SQLite具有的所有数据库特性。 + +**图1** 关系型数据库运作机制 + +![](figure/zh-cn_image_0000001115980740.png) + +## 默认配置 +- 如果不指定数据库的日志模式，那么系统默认日志方式是WAL（Write Ahead Log）模式。 +- 如果不指定数据库的落盘模式，那么系统默认落盘方式是FULL模式。 +- OpenHarmony数据库使用的共享内存默认大小是8MB，单次查询使用的共享内存默认大小是2MB。 + +## 约束与限制 +- 数据库中连接池的最大数量是4个，用以管理用户的读操作。 +- 为保证数据的准确性，数据库同一时间只能支持一个写操作。 + + diff --git a/zh-cn/device-dev/subsystems/subsys-database-relational.md b/zh-cn/device-dev/subsystems/subsys-database-relational.md new file mode 100644 index 0000000000000000000000000000000000000000..85fe45cec40241feb6e2c5272b8247549ebb0170 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-database-relational.md @@ -0,0 +1,7 @@ +# 关系型数据库 + +- **[关系型数据库概述](subsys-database-relational-overview.md)** + +- **[关系型数据库开发指导](subsys-database-relational-guide.md)** + + diff --git a/zh-cn/device-dev/subsystems/subsys-database.md b/zh-cn/device-dev/subsystems/subsys-database.md new file mode 100644 index 0000000000000000000000000000000000000000..149691099546d0f4e6b16dfe789a68fce6c7b1ca --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-database.md @@ -0,0 +1,5 @@ +# 数据管理 + +- **[关系型数据库](subsys-database-relational.md)** + +