!13453 添加数据库升级场景示例

Merge pull request !13453 from LeiiYB/master

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

@@ -202,39 +202,77 @@
 
     ```js
    import data_rdb from '@ohos.data.relationalStore'
-    // 获取context
    import featureAbility from '@ohos.ability.featureAbility'
+   
+   // 获取context
    let context = featureAbility.getContext()
    
-   const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL, " + "blobType BLOB)";
+   const STORE_CONFIG = { 
+       name: "RdbTest.db",
+       securityLevel: data_rdb.SecurityLevel.S1
+   }
    
-   const STORE_CONFIG = { name: "RdbTest.db",
-                         securityLevel: data_rdb.SecurityLevel.S1}
+   // 假设当前数据库版本为3
    data_rdb.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) {
-      rdbStore.executeSql(CREATE_TABLE_TEST)
-      console.info('create table done.')
+        // 当数据库创建时，数据库默认版本为0
+        if (rdbStore.version == 0) {
+            rdbStore.executeSql("CREATE TABLE IF NOT EXISTS student (id INTEGER PRIMARY KEY AUTOINCREMENT, score REAL);", null)
+            // 设置数据库的版本，入参为大于0的整数
+            rdbStore.version = 3
+        }
+        
+        // 当数据库存在并假定版本为1时，例应用从某一版本升级到当前版本，数据库需要从1版本升级到2版本
+        if (rdbStore.version != 3 && rdbStore.version == 1) {
+            // version = 1：表结构：student (id, age) => version = 2：表结构：student (id, age, score)
+            rdbStore.executeSql("ALTER TABLE student ADD COLUMN score REAL", null)
+            rdbStore.version = 2
+        }
+        
+        // 当数据库存在并假定版本为2时，例应用从某一版本升级到当前版本，数据库需要从2版本升级到3版本
+        if (rdbStore.version != 3 && rdbStore.version == 2) {
+            // version = 2：表结构：student (id, age, score) => version = 3：表结构：student (id, score)
+            rdbStore.executeSql("ALTER TABLE student DROP COLUMN age INTEGER", null)
+            rdbStore.version = 3
+        }
    })
     ```
     Stage模型示例：
      ```ts
    import data_rdb from '@ohos.data.relationalStore'
-    // 获取context
-   import UIAbility from '@ohos.app.ability.UIAbility';
-   let context = null
+   import UIAbility from '@ohos.app.ability.UIAbility'
+   
    class EntryAbility extends UIAbility {
        onWindowStageCreate(windowStage) {
-         context = this.context
+           const STORE_CONFIG = { 
+               name: "rdbstore.db",
+               securityLevel: data_rdb.SecurityLevel.S1
            }
+   
+           // 假设当前数据库版本为3
+           data_rdb.getRdbStore(this.context, STORE_CONFIG, function (err, rdbStore) {
+               // 当数据库创建时，数据库默认版本为0
+               if (rdbStore.version == 0) {
+                   rdbStore.executeSql("CREATE TABLE IF NOT EXISTS student (id INTEGER PRIMARY KEY AUTOINCREMENT, score REAL);", null)
+                   // 设置数据库的版本，入参为大于0的整数
+                   rdbStore.version = 3
                }
     
-   const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL, " + "blobType BLOB)";
+               // 当数据库存在并假定版本为1时，例应用从某一版本升级到当前版本，数据库需要从1版本升级到2版本
+               if (rdbStore.version != 3 && rdbStore.version == 1) {
+                   // version = 1：表结构：student (id, age) => version = 2：表结构：student (id, age, score)
+                   rdbStore.executeSql("ALTER TABLE student ADD COLUMN score REAL", null)
+                   rdbStore.version = 2
+               }
     
-   const STORE_CONFIG = { name: "rdbstore.db",
-                          securityLevel: data_rdb.SecurityLevel.S1}
-   data_rdb.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) {
-       rdbStore.executeSql(CREATE_TABLE_TEST)
-       console.info('create table done.')
+               // 当数据库存在并假定版本为2时，例应用从某一版本升级到当前版本，数据库需要从2版本升级到3版本
+               if (rdbStore.version != 3 && rdbStore.version == 2) {
+                   // version = 2：表结构：student (id, age, score) => version = 3：表结构：student (id, score)
+                   rdbStore.executeSql("ALTER TABLE student DROP COLUMN age INTEGER", null)
+                   rdbStore.version = 3
+               }
            })
+       }
+   }
      ```
 
 2. 插入数据。
@@ -384,7 +422,6 @@
     
 8. 远程查询。
    
-   
    (1) 构造用于查询分布式表的谓词对象，指定组网内的远程分布式表名和设备。
    
    (2) 调用结果集接口，返回查询结果。
@@ -422,6 +459,7 @@
        console.info('Backup failed, err: ' + err)
     })
    ```
+   
    (2) 调用数据库的恢复接口，从数据库的备份文件恢复数据库文件。
 
    示例代码如下：

zh-cn/application-dev/reference/apis/js-apis-data-relationalStore.md

@@ -48,27 +48,22 @@ getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<Rd
 FA模型示例：
 
 ```js
-// 获取context
+
 import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取context
 let context = featureAbility.getContext()
 
-// 获取context后调用getRdbStore
 const STORE_CONFIG = {
     name: "RdbTest.db",
     securityLevel: data_rdb.SecurityLevel.S1
 }
+
 data_rdb.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) {
     if (err) {
         console.info("Get RdbStore failed, err: " + err)
         return
     }
-    if (rdbStore.openStatus == data_rdb.OpenStatus.ON_CREATE) {
-        console.log("RdbStore status is ON_CREATE")
-    } else if (rdbStore.openStatus == data_rdb.OpenStatus.ON_OPEN) {
-        console.log("RdbStore status is ON_OPEN")
-    } else {
-        return
-    }
     console.log("Get RdbStore successfully.")
 })
 ```
@@ -76,36 +71,24 @@ data_rdb.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) {
 Stage模型示例：
 
 ```ts
-// 获取context
-import UIAbility from '@ohos.app.ability.UIAbility';
-
-let context;
+import UIAbility from '@ohos.app.ability.UIAbility'
 
 class EntryAbility extends UIAbility {
     onWindowStageCreate(windowStage){
-        context = this.context
-    }
-}
-
-// 获取context后调用getRdbStore
-const STORE_CONFIG = {
+        const STORE_CONFIG = {
             name: "RdbTest.db",
             securityLevel: data_rdb.SecurityLevel.S1
-}
-data_rdb.getRdbStore(context, STORE_CONFIG, function (err, rdbStore) {
+        }
+        
+        data_rdb.getRdbStore(this.context, STORE_CONFIG, function (err, rdbStore) {
             if (err) {
                 console.info("Get RdbStore failed, err: " + err)
                 return
             }
-    if (rdbStore.openStatus == data_rdb.OpenStatus.ON_CREATE) {
-        console.log("RdbStore status is ON_CREATE")
-    } else if (rdbStore.openStatus == data_rdb.OpenStatus.ON_OPEN) {
-        console.log("RdbStore status is ON_OPEN")
-    } else {
-        return
-    }
             console.log("Get RdbStore successfully.")
-})
+        })
+    }
+}
 ```
 
 ## data_rdb.getRdbStore
@@ -143,24 +126,18 @@ getRdbStore(context: Context, config: StoreConfig): Promise<RdbStore>
 FA模型示例：
 
 ```js
-// 获取context
 import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取context
 let context = featureAbility.getContext()
 
-// 获取context后调用getRdbStore
 const STORE_CONFIG = {
     name: "RdbTest.db",
     securityLevel: data_rdb.SecurityLevel.S1
 }
+
 let promise = data_rdb.getRdbStore(context, STORE_CONFIG);
 promise.then(async (rdbStore) => {
-    if (rdbStore.openStatus == data_rdb.OpenStatus.ON_CREATE) {
-        console.log("RdbStore status is ON_CREATE")
-    } else if (rdbStore.openStatus == data_rdb.OpenStatus.ON_OPEN) {
-        console.log("RdbStore status is ON_OPEN")
-    } else {
-        return
-    }
     console.log("Get RdbStore successfully.")
 }).catch((err) => {
     console.log("Get RdbStore failed, err: " + err)
@@ -170,35 +147,23 @@ promise.then(async (rdbStore) => {
 Stage模型示例：
 
 ```ts
-// 获取context
-import UIAbility from '@ohos.app.ability.UIAbility';
-
-let context;
+import UIAbility from '@ohos.app.ability.UIAbility'
 
 class EntryAbility extends UIAbility {
     onWindowStageCreate(windowStage){
-        context = this.context
-    }
-}
-
-// 获取context后调用getRdbStore
-const STORE_CONFIG = {
+        const STORE_CONFIG = {
             name: "RdbTest.db",
             securityLevel: data_rdb.SecurityLevel.S1
-}
-let promise = data_rdb.getRdbStore(context, STORE_CONFIG);
-promise.then(async (rdbStore) => {
-    if (rdbStore.openStatus == data_rdb.OpenStatus.ON_CREATE) {
-        console.log("RdbStore status is ON_CREATE")
-    } else if (rdbStore.openStatus == data_rdb.OpenStatus.ON_OPEN) {
-        console.log("RdbStore status is ON_OPEN")
-    } else {
-        return
         }
+        
+        let promise = data_rdb.getRdbStore(this.context, STORE_CONFIG);
+        promise.then(async (rdbStore) => {
             console.log("Get RdbStore successfully.")
-}).catch((err) => {
+        }).catch((err) => {
             console.log("Get RdbStore failed, err: " + err)
-})
+        })
+    }
+}
 ```
 
 ## data_rdb.deleteRdbStore
@@ -230,11 +195,11 @@ deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void&g
 FA模型示例：
 
 ```js
-// 获取context
 import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取context
 let context = featureAbility.getContext()
 
-// 获取context后调用deleteRdbStore
 data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) {
     if (err) {
         console.info("Delete RdbStore failed, err: " + err)
@@ -247,25 +212,19 @@ data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) {
 Stage模型示例：
 
 ```ts
-// 获取context
-import UIAbility from '@ohos.app.ability.UIAbility';
-
-let context;
+import UIAbility from '@ohos.app.ability.UIAbility'
 
 class EntryAbility extends UIAbility {
     onWindowStageCreate(windowStage){
-        context = this.context
-    }
-}
-
-// 获取context后调用deleteRdbStore
-data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) {
+        data_rdb.deleteRdbStore(this.context, "RdbTest.db", function (err) {
             if (err) {
                 console.info("Delete RdbStore failed, err: " + err)
                 return
             }
             console.log("Delete RdbStore successfully.")
-})
+        })
+    }
+}
 ```
 
 ## data_rdb.deleteRdbStore
@@ -302,11 +261,11 @@ deleteRdbStore(context: Context, name: string): Promise<void>
 FA模型示例：
 
 ```js
-// 获取context
 import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取context
 let context = featureAbility.getContext()
 
-// 获取context后调用deleteRdbStore
 let promise = data_rdb.deleteRdbStore(context, "RdbTest.db")
 promise.then(()=>{
     console.log("Delete RdbStore successfully.")
@@ -318,24 +277,18 @@ promise.then(()=>{
 Stage模型示例：
 
 ```ts
-// 获取context
-import UIAbility from '@ohos.app.ability.UIAbility';
-
-let context;
+import UIAbility from '@ohos.app.ability.UIAbility'
 
 class EntryAbility extends UIAbility {
     onWindowStageCreate(windowStage){
-        context = this.context
-    }
-}
-
-// 获取context后调用deleteRdbStore
-let promise = data_rdb.deleteRdbStore(context, "RdbTest.db")
-promise.then(()=>{
+        let promise = data_rdb.deleteRdbStore(this.context, "RdbTest.db")
+        promise.then(()=>{
             console.log("Delete RdbStore successfully.")
-}).catch((err) => {
+        }).catch((err) => {
             console.info("Delete RdbStore failed, err: " + err)
-})
+        })
+    }
+}
 ```
 
 ## StoreConfig
@@ -423,17 +376,6 @@ promise.then(()=>{
 | ON_CONFLICT_IGNORE   | 4    | 表示当冲突发生时，跳过包含违反约束的行并继续处理 SQL 语句的后续行。 |
 | ON_CONFLICT_REPLACE  | 5    | 表示当冲突发生时，在插入或更新当前行之前删除导致约束违例的预先存在的行，并且命令会继续正常执行。 |
 
-## OpenStatus<sup>10+</sup>
-
-RdbStore的状态枚举。
-
-**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
-
-| 名称       | 值   | 说明                                                 |
-| --------- | ---- | --------------------------------------------------- |
-| ON_CREATE | 0    | 表示RdbStore首次创建，处于ON_CREATE状态。               |
-| ON_OPEN   | 1    | 表示RdbStore非首次创建，处于ON_OPEN状态。                |
-
 ## RdbPredicates
 
 表示关系型数据库（RDB）的谓词。该类确定RDB中条件表达式的值是true还是false。
@@ -1283,7 +1225,16 @@ predicates.notIn("NAME", ["Lisa", "Rose"])
 
 | 名称         | 类型            | 必填 | 说明                             |
 | ------------ | ----------- | ---- | -------------------------------- |
-| openStatus<sup>10+</sup>  | number | 是   | RdbStore的状态。值为0时，表示RdbStore首次创建，处于ON_CREATE状态。值为1时，表示RdbStore非首次创建，处于ON_OPEN状态。       |
+| version<sup>10+</sup>  | number | 是   | 设置和获取数据库版本，值为大于0的正整数。       |
+
+**示例：**
+
+```js
+// 设置数据库版本
+rdbStore.version = 3
+// 获取数据库版本
+console.info("Get RdbStore version is " + rdbStore.version)
+```
 
 ### insert