!5567 【RDB】增加backup/restore 开发文档资料

Merge pull request !5567 from Cap_W/master

zh-cn/application-dev/database/database-relational-guidelines.md

@@ -32,8 +32,8 @@
   
   | 类名 | 接口名 | 描述 |
   | -------- | -------- | -------- |
-  | RdbStore | insert(name:&nbsp;string,&nbsp;values:&nbsp;ValuesBucket,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 向目标表中插入一行数据，结果以callback形式返回。<br/>-&nbsp;name：指定的目标表名。<br/>-&nbsp;values：表示要插入到表中的数据行。<br/>-&nbsp;callback：指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 |
-  | RdbStore | insert(name:&nbsp;string,&nbsp;values:&nbsp;ValuesBucket):&nbsp;Promise&lt;number&gt; | 向目标表中插入一行数据，结果以Promise形式返回。<br/>-&nbsp;name：指定的目标表名。<br/>-&nbsp;values：表示要插入到表中的数据行。 |
+  | RdbStore | insert(table:&nbsp;string,&nbsp;values:&nbsp;ValuesBucket,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 向目标表中插入一行数据，结果以callback形式返回。<br/>-&nbsp;table：指定的目标表名。<br/>-&nbsp;values：表示要插入到表中的数据行。<br/>-&nbsp;callback：指定callback回调函数。如果操作成功，返回行ID；否则返回-1。 |
+  | RdbStore | insert(table:&nbsp;string,&nbsp;values:&nbsp;ValuesBucket):&nbsp;Promise&lt;number&gt; | 向目标表中插入一行数据，结果以Promise形式返回。<br/>-&nbsp;table：指定的目标表名。<br/>-&nbsp;values：表示要插入到表中的数据行。 |
   
 - **更新**
   
@@ -43,8 +43,8 @@
   
   | 类名 | 接口名 | 描述 |
   | -------- | -------- | -------- |
-  | RdbStore | update(values:&nbsp;ValuesBucket,&nbsp;rdbPredicates:&nbsp;RdbPredicates,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 根据RdbPredicates的指定实例对象更新数据库中的数据，结果以callback形式返回。<br/>-&nbsp;values：以ValuesBucket存储的要更新的数据。<br/>-&nbsp;rdbPredicates：表示RdbPredicates的实例对象指定的更新条件。<br/>-&nbsp;callback：指定的callback回调方法。返回受影响的行数。 |
-  | RdbStore | update(values:&nbsp;ValuesBucket,&nbsp;rdbPredicates:&nbsp;RdbPredicates):&nbsp;Promise\<number> | 根据RdbPredicates的指定实例对象更新数据库中的数据，结果以Promise形式返回。<br/>-&nbsp;values：以ValuesBucket存储的要更新的数据。<br/>-&nbsp;rdbPredicates：表示RdbPredicates的实例对象指定的更新条件。 |
+  | RdbStore | update(values:&nbsp;ValuesBucket,&nbsp;predicates:&nbsp;RdbPredicates,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 根据RdbPredicates的指定实例对象更新数据库中的数据，结果以callback形式返回。<br/>-&nbsp;values：以ValuesBucket存储的要更新的数据。<br/>-&nbsp;predicates：表示RdbPredicates的实例对象指定的更新条件。<br/>-&nbsp;callback：指定的callback回调方法。返回受影响的行数。 |
+  | RdbStore | update(values:&nbsp;ValuesBucket,&nbsp;predicates:&nbsp;RdbPredicates):&nbsp;Promise&lt;number&gt; | 根据RdbPredicates的指定实例对象更新数据库中的数据，结果以Promise形式返回。<br/>-&nbsp;values：以ValuesBucket存储的要更新的数据。<br/>-&nbsp;predicates：表示RdbPredicates的实例对象指定的更新条件。 |
   
 - **删除** 
   
@@ -54,8 +54,8 @@
   
   | 类名 | 接口名 | 描述 |
   | -------- | -------- | -------- |
-  | RdbStore | delete(rdbPredicates:&nbsp;RdbPredicates,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 根据rdbPredicates的指定实例对象从数据库中删除数据，结果以callback形式返回。<br/>-&nbsp;rdbPredicates：RdbPredicates的实例对象指定的删除条件。<br/>-&nbsp;callback：指定callback回调函数。返回受影响的行数。 |
-  | RdbStore | delete(rdbPredicates:&nbsp;RdbPredicates):&nbsp;Promise\<number> | 根据rdbPredicates的指定实例对象从数据库中删除数据，结果以Promise形式返回。<br/>-&nbsp;rdbPredicates：RdbPredicates的实例对象指定的删除条件。 |
+  | RdbStore | delete(predicates:&nbsp;RdbPredicates,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):void | 根据RdbPredicates的指定实例对象从数据库中删除数据，结果以callback形式返回。<br/>-&nbsp;predicates：RdbPredicates的实例对象指定的删除条件。<br/>-&nbsp;callback：指定callback回调函数。返回受影响的行数。 |
+  | RdbStore | delete(predicates:&nbsp;RdbPredicates):&nbsp;Promise&lt;number&gt; | 根据RdbPredicates的指定实例对象从数据库中删除数据，结果以Promise形式返回。<br/>-&nbsp;predicates：RdbPredicates的实例对象指定的删除条件。 |
   
 - **查询** 
 
@@ -68,8 +68,8 @@
 
   | 类名 | 接口名 | 描述 |
   | -------- | -------- | -------- |
-  | RdbStore | query(rdbPredicates:&nbsp;RdbPredicates,&nbsp;columns:&nbsp;Array,&nbsp;callback:&nbsp;AsyncCallback&lt;ResultSet&gt;):&nbsp;void | 根据指定条件查询数据库中的数据，结果以callback形式返回。<br/>-&nbsp;rdbPredicates：表示RdbPredicates的实例对象指定的查询条件。<br/>-&nbsp;columns：表示要查询的列。如果值为空，则查询应用于所有列。<br/>-&nbsp;callback：指定callback回调函数。如果操作成功，则返回ResultSet对象。 |
-  | RdbStore | query(rdbPredicates:&nbsp;RdbPredicates,&nbsp;columns:&nbsp;Array):&nbsp;Promise&lt;ResultSet&gt; | 根据指定条件查询数据库中的数据，结果以Promise形式返回。<br/>-&nbsp;rdbPredicates：表示RdbPredicates的实例对象指定的查询条件。<br/>-&nbsp;columns：表示要查询的列。如果值为空，则查询应用于所有列。 |
+  | RdbStore | query(predicates:&nbsp;RdbPredicates,&nbsp;columns:&nbsp;Array,&nbsp;callback:&nbsp;AsyncCallback&lt;ResultSet&gt;):&nbsp;void | 根据指定条件查询数据库中的数据，结果以callback形式返回。<br/>-&nbsp;predicates：表示RdbPredicates的实例对象指定的查询条件。<br/>-&nbsp;columns：表示要查询的列。如果值为空，则查询应用于所有列。<br/>-&nbsp;callback：指定callback回调函数。如果操作成功，则返回ResultSet对象。 |
+  | RdbStore | query(predicates:&nbsp;RdbPredicates,&nbsp;columns:&nbsp;Array):&nbsp;Promise&lt;ResultSet&gt; | 根据指定条件查询数据库中的数据，结果以Promise形式返回。<br/>-&nbsp;predicates：表示RdbPredicates的实例对象指定的查询条件。<br/>-&nbsp;columns：表示要查询的列。如果值为空，则查询应用于所有列。 |
   | RdbStore | querySql(sql:&nbsp;string,&nbsp;bindArgs:&nbsp;Array&lt;ValueType&gt;,&nbsp;callback:&nbsp;AsyncCallback&lt;ResultSet&gt;):void | 根据指定SQL语句查询数据库中的数据，结果以callback形式返回。<br/>-&nbsp;sql：指定要查询的SQL语句。<br/>-&nbsp;bindArgs：SQL语句中参数的值。<br/>-&nbsp;callback：指定callback回调函数。如果操作成功，则返回ResultSet对象。 |
   | RdbStore | querySql(sql:&nbsp;string,&nbsp;bindArgs?:&nbsp;Array&lt;ValueType&gt;):Promise&lt;ResultSet&gt; | 根据指定SQL语句查询数据库中的数据，结果以Promise形式返回。<br/>-&nbsp;sql：指定要查询的SQL语句。<br/>-&nbsp;bindArgs：SQL语句中参数的值。 |
 
@@ -188,6 +188,25 @@
 | -------- | -------- | -------- |
 | RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback\<Array\<string>>): void;| 从数据库中删除指定类型的指定观察者，结果以callback形式返回。<br/>-&nbsp;type：指在{@code SubscribeType}中定义的订阅类型；SUBSCRIBE_TYPE_REMOTE 订阅远程数据更改。<br/>-&nbsp;observer：指已注册的数据更改观察者。 |
 
+### 数据库的备份和恢复
+
+**备份**
+
+**表13** 备份数据库
+
+| 类名 | 接口名 | 描述 |
+| -------- | -------- | -------- |
+| RdbStore |backup(destName:string, callback: AsyncCallback&lt;void&gt;):void| 以指定名称备份数据库，结果以callback形式返回。<br/>-&nbsp;destName：指定数据库的备份文件名。<br/>-&nbsp;callback：指定callback回调函数。 |
+| RdbStore |backup(destName:string): Promise&lt;void&gt;| 以指定名称备份数据库，结果以promise形式返回。<br/>-&nbsp;destName：指定数据库的备份文件名。 |
+
+**恢复**
+
+**表14** 恢复数据库
+
+| 类名 | 接口名 | 描述 |
+| -------- | -------- | -------- |
+| RdbStore |restore(srcName:string, callback: AsyncCallback&lt;void&gt;):void| 从指定的数据库备份文件恢复数据库，结果以callback形式返回。<br/>-&nbsp;srcName：指定数据库的备份文件名。<br/>-&nbsp;callback：指定callback回调函数。 |
+| RdbStore |restore(srcName:string): Promise&lt;void&gt;| 从指定的数据库备份文件恢复数据库，结果以promise形式返回。<br/>-&nbsp;srcName：指定数据库的备份文件名。 |
 
 ## 开发步骤
 
@@ -321,6 +340,29 @@
     let tableName = rdbStore.obtainDistributedTableName(deviceId, "test");
     let resultSet = rdbStore.querySql("SELECT * FROM " + tableName)
     ```
+8. 数据库的备份和恢复。
+   1. 调用数据库的备份接口，备份当前数据库文件。
+   2. 调用数据库的恢复接口，从数据库的备份文件恢复数据库文件。
+   
+   示例代码如下：
+
+    ```js
+    let promiseBackup = rdbStore.backup("dbBackup.db")
+    promiseBackup.then(()=>{
+        console.info('Backup success.')
+    }).catch((err)=>{
+        console.info('Backup failed, err: ' + err)
+    })
+    ```
+    ```js
+    let promiseRestore = rdbStore.restore("dbBackup.db")
+    promiseRestore.then(()=>{
+        console.info('Restore success.')
+    }).catch((err)=>{
+        console.info('Restore failed, err: ' + err)
+    })
+    ```
+
 ## 相关实例
 针对关系型数据库开发，有以下相关实例可供参考：
 - [`Rdb`：关系型数据库（eTS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/data/Rdb)

zh-cn/device-dev/subsystems/subsys-data-relational-database-guide.md

@@ -155,6 +155,30 @@
 |  ----  |  ----  |  ----  |
 | RdbStore | bool UnSubscribe(const SubscribeOption& option, RdbStoreObserver *observer) | 从数据库中删除指定类型的指定观察者。<ul><li> option：订阅类型；</li><li> observer：指已注册的数据更改观察者</li></ul>
 
+### 数据库的备份和恢复 
+
+关系型数据库提供对本地数据库文件的备份和恢复能力，相关API如下所示。
+
+- 备份
+
+  关系型数据库提供了备份数据库文件的接口，通过databasePath指定的备份文件名（支持路径）备份当前数据库文件。通过返回值判断是否备份成功，成功时返回0，失败时则返回相应的错误码。
+
+  表11 数据库备份API
+
+  | 类名 | 接口名 | 描述 |
+  |  ----  |  ----  |  ----  |
+  | RdbStore | int Backup(const std::string databasePath, const std::vector&lt;uint8_t&gt; destEncryptKey) | 备份数据库文件。<ul><li>databasePath：指定的备份文件名。 </li><li> destEncryptKey：数据库的加密密钥。注意：当前只支持非加密数据库的备份。</li></ul> |
+
+- 恢复
+
+  关系型数据库提供了恢复数据库文件的接口，通过backupPath指定的备份文件名（支持路径）恢复当前数据库文件。通过返回值判断是否恢复成功，成功时返回0，失败时则返回相应的错误码。
+
+  表12 数据库恢复API
+
+  | 类名 | 接口名 | 描述 |
+  |  ----  |  ----  |  ----  |
+  | RdbStore | int Restore(const std::string backupPath, const std::vector&lt;uint8_t&gt; &newKey) | 恢复数据库文件。<ul><li>backupPath：指定的备份文件名。 </li><li> newKey：数据库的加密密钥。注意：当前只支持非加密数据库的恢复。</li></ul> |
+
 ## 约束与限制
 
 无。
@@ -303,3 +327,17 @@
     std::string tableName = store->ObtainDistributedTableName("123456789abcd", "test");
     auto resultSet = store->QuerySql("SELECT * from ?;", tableName);
     ```
+
+8. 数据库的备份和恢复
+
+   a. 根据指定的数据库备份文件名备份当前数据库。
+
+   b. 根据指定的数据库备份文件恢复当前数据库。
+
+   示例代码如下：
+   ```
+    std::string backupName = "backup.db"; // 指定数据库的备份文件名
+    std::vector<uint8_t> key; // 数据库的加密密钥
+    int errno = store->Backup(backupName, key);
+    errno = store->Restore(backupName, key);
+    ```
\ No newline at end of file