diff --git a/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md b/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md index 41f7d9ab731c6abd0e193c9fa038d22fe4142297..48e4e3308988701b30ec362e50962abf50e80e52 100644 --- a/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-database-relational-guide.md @@ -3,6 +3,11 @@ - [关系型数据库开发指导](#关系型数据库开发指导) - [场景介绍](#场景介绍) - [接口说明](#接口说明) + - [数据库的创建和删除](#数据库的创建和删除) + - [数据库的加密](#数据库的加密) + - [数据库谓词的使用](#数据库谓词的使用) + - [数据库的增删改查](#数据库的增删改查) + - [查询结果集的使用](#查询结果集的使用) - [约束与限制](#约束与限制) - [开发步骤](#开发步骤) @@ -11,7 +16,7 @@ 关系型数据库是在SQLite基础上实现的本地数据操作机制，提供给用户无需编写原生SQL语句就能进行数据增删改查的方法，同时也支持原生SQL语句操作。 ## 接口说明 -**数据库的创建和删除** +### 数据库的创建和删除 关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的API如下所示。 @@ -19,14 +24,14 @@ | 类名 | 接口名 | 描述 | | ---- | ---- | ---- | -| 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 = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。 | +| 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 = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。
  • path：数据库路径；
  • readOnly：是否只读；
  • storageMode：存储模式；
  • encryptKey：加密密钥;
  • journalMode：日志模式；
  • syncMode：同步模式；
  • databaseFileType：数据库类型；
  • 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) | 删除指定的数据库。 | -**数据库的加密** +### 数据库的加密 关系型数据库提供数据库加密的能力，在创建数据库时若指定了密钥，则会创建为加密数据库。再次使用此数据库时，需要指定该密钥，才能正确打开数据库。 @@ -35,7 +40,25 @@ | ---- | ---- | ---- | | 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如下所示。 @@ -49,15 +72,6 @@ | ---- | ---- | ---- | | 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。 - - 表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等接口调用。
| - - 删除 调用删除接口，通过AbsRdbPredicates指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回0。 @@ -67,6 +81,15 @@ | ---- | ---- | ---- | | 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等接口调用。
| + - 查询 关系型数据库提供了两种查询数据的方式： @@ -80,25 +103,7 @@ | 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。
| -**数据库谓词的使用** - -关系型数据库提供了用于设置数据库操作条件的谓词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子句中占位符的值。 | - -**查询结果集的使用** +### 查询结果集的使用 关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 @@ -110,7 +115,7 @@ | ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | | ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | | ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | - | ResultSet | int IsEnded(bool &result) | 判断结果集当前位置是否在最后一行之后。 | + | ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | | ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | | ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | | ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | @@ -168,7 +173,7 @@ ValuesBucket values; values.PutInt("id", 1); - values.PutString("name", std::string("zhangsan")); + values.PutString("name", std::string("Tom")); values.PutInt("age", 18); values.PutDouble("salary", 100.5); values.PutBlob("blobType", std::vector{ 1, 2, 3 }); diff --git a/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md b/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md index 319a67266252e492363afb3e83be3fafe469f5b3..01e2b9fd00d537d074c9f059524f3ac9a1d9c038 100644 --- a/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md +++ b/zh-cn/device-dev/subsystems/subsys-database-relational-overview.md @@ -6,7 +6,7 @@ - [默认配置](#默认配置) - [约束与限制](#约束与限制) -关系型数据库（Relational Database，RDB）是一种基于关系模型来管理数据的数据库。OpenHarmony关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制，对外提供了一系列的增、删、改、查等接口，也可以直接运行用户输入的SQL语句来满足复杂的场景需要。OpenHarmony提供的关系型数据库功能更加完善，查询效率更加高效。 +关系型数据库（Relational Database，RDB）是一种基于关系模型来管理数据的数据库。OpenHarmony关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制，对外提供了一系列的增、删、改、查等接口，也可以直接运行用户输入的SQL语句来满足复杂的场景需要。 ## 基本概念 @@ -27,7 +27,7 @@ 一款轻型的数据库，是遵守ACID的关系型数据库管理系统。它是一个开源的项目。 ## 运作机制 -OpenHarmony关系型数据库对外提供通用的操作接口，底层使用SQLite作为持久化存储引擎，支持SQLite具有的所有数据库特性。 +OpenHarmony关系型数据库对外提供通用的操作接口（即Rdb Store接口），底层使用第三方开源组件SQLite作为持久化存储引擎，支持SQLite具有的所有数据库特性。 **图1** 关系型数据库运作机制