1 概述

關(guān)系型數(shù)據(jù)庫(kù)(Relational Database, 以下簡(jiǎn)稱RDB)是一種基于關(guān)系模型來管理數(shù)據(jù)的數(shù)據(jù)庫(kù)，是在SQLite基礎(chǔ)上提供一套完整的對(duì)本地?cái)?shù)據(jù)庫(kù)進(jìn)行管理的機(jī)制，為開發(fā)者提供無需編寫原生SQL語(yǔ)句即可實(shí)現(xiàn)數(shù)據(jù)增、刪、改、查等接口，同時(shí)開發(fā)者也可以直接運(yùn)行原生SQL語(yǔ)句來滿足復(fù)雜的場(chǎng)景需要。關(guān)系型數(shù)據(jù)庫(kù)在應(yīng)用卸載之后，才會(huì)被自動(dòng)清除。

2 運(yùn)作機(jī)制

RDB對(duì)外提供通用的接口，底層使用SQLite作為持久化存儲(chǔ)引擎，支持SQLite具有的所有數(shù)據(jù)庫(kù)特性。SQLite是一個(gè)進(jìn)程內(nèi)的庫(kù)，具有自給自足、無服務(wù)、零配置、事務(wù)性特性的SQL數(shù)據(jù)庫(kù)引擎。RDB包括但不限于事務(wù)、索引、視圖、觸發(fā)器、外鍵、參數(shù)化查詢和預(yù)編譯SQL語(yǔ)句。

3 使用場(chǎng)景

• 通訊錄
• 記事本
• 計(jì)算器歷史記錄
• App用戶登錄信息
• App主題
• ...

4 流程

5 詳細(xì)步驟

RDB對(duì)開發(fā)者提供的接口大部分為異步接口，均有callback和Promise兩種返回形式，接下來將會(huì)一一介紹。

5.1 導(dǎo)入模塊

import relationalStore from '@ohos.data.relationalStore';

5.2 配置數(shù)據(jù)庫(kù)相關(guān)信息

創(chuàng)建數(shù)據(jù)庫(kù)時(shí)需要配置數(shù)據(jù)庫(kù)相關(guān)信息，RDB提供管理關(guān)系型數(shù)據(jù)庫(kù)配置的StoreConfig接口，其參數(shù)如表5-1所示：

表5-1 關(guān)系型數(shù)據(jù)庫(kù)配置參數(shù)

表5-2 數(shù)據(jù)庫(kù)的安全級(jí)別枚舉

const store_config = {
    name: "RdbSample.db",
    securityLevel: relationalStore.SecurityLevel.S4,
    encrypt: true
}

5.3 創(chuàng)建數(shù)據(jù)庫(kù)

和MySQL、Oracle等數(shù)據(jù)庫(kù)類似，在使用之前需要先創(chuàng)建數(shù)據(jù)庫(kù)，RDB提供了getRdbStore()方法用于創(chuàng)建數(shù)據(jù)庫(kù)，該方法需要傳入應(yīng)用上下文Context和數(shù)據(jù)庫(kù)配置信息StoreConfig兩個(gè)參數(shù)，該方法有callback和Promise兩種返回形式，如表5-3所示。

表5-3 數(shù)據(jù)庫(kù)創(chuàng)建方法

// callback形式
relationalStore.getRdbStore(this.context, STORE_CONFIG, (err, rdbStore) => {
  if (err) {
    Log.error(TAG, "Get RdbStore fialed, err: " + JSON.stringify(err))
    return;
  }
  // rdbStore相關(guān)操作
  Log.info(TAG, "Get RdbStore successfully.");
})

// Promise形式
relationalStore.getRdbStore(this.context, STORE_CONFIG).then((rdbStore) => {
  // rdbStore相關(guān)操作
  Log.info(TAG, "Get RdbStore successfully.");
}).catch((err) => {
  Log.error(TAG, "Get RdbStore fialed, err: " + JSON.stringify(err))
})

注：RDB不僅提供了數(shù)據(jù)庫(kù)創(chuàng)建的方法，同時(shí)還提供了刪除數(shù)據(jù)庫(kù)方法，可以調(diào)用deleteRdbStore()方法進(jìn)行數(shù)據(jù)庫(kù)刪除，使用方式和getRdbStore()方法類似。

5.4 數(shù)據(jù)表操作

創(chuàng)建數(shù)據(jù)庫(kù)后，獲取到RdbStore實(shí)例。RdbStore提供管理RDB方法的接口，在使用其增、刪、改、查等接口之前，需要使用executeSql接口初始化數(shù)據(jù)表結(jié)構(gòu)和相關(guān)數(shù)據(jù)。

5.4.1 創(chuàng)建數(shù)據(jù)表

executeSql()方法執(zhí)行包含指定參數(shù)但不返回值得SQL語(yǔ)句，有callback和Promise兩種形式，如表5-4所示。

表5-4 創(chuàng)建數(shù)據(jù)表方法

注：表中的ValueType用于表示允許的數(shù)據(jù)字段類型，當(dāng)前僅支持表示值類型為數(shù)字的number，表示值類型為字符的string，表示值類型為布爾值的boolean。

const sql = "CREATE TABLE IF NOT EXISTS USER (ID INTEGER PRIMARY KEY AUTOINCREMENT, USERNAME TEXT NOT NULL, PASSWORD TEXT NOT NULL)"
// callback形式
rdbStore.executeSql(sql, null, (err) {
  if (err) {
    Log.error(TAG, "ExecuteSql failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Create table done.");
})
// Promise形式
rdbStore.executeSql(sql, null).then(() => {
  Log.info(TAG, "Create table done.");
}).catch((err) => {
  Log.error(TAG, "ExecuteSql failed, err: " + JSON.stringify(err));
})

5.4.2 新增數(shù)據(jù)

RdbStore提供了單條數(shù)據(jù)插入和批量數(shù)據(jù)插入兩種為數(shù)據(jù)表新增數(shù)據(jù)的方法，如表5-5所示。

表5-5 新增數(shù)據(jù)方法

注：表5-5中ValuesBucket是用于存儲(chǔ)鍵值對(duì)的類型，其鍵為string類型，值類型可為ValueType|Uint8Array|null。

const tableName = "USER";
const valueBacket = {
  "USERNAME": "Admin",
  "PASSWORD": "123456"
}
// insert callback形式
rdbStore.insert(tableName, valueBucket, (err, rowId) => {
  if (err) {
    Log.error(TAG, "Insert data failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Insert data successful, rowId = " + rowId);
})
// insert Promise形式
rdbStore.insert(tableName, valueBucket).then((rowId) => {
  Log.info(TAG, "Insert data successful, rowId = " + rowId);
}).catch((err) => {
  Log.error(TAG, "Insert data failed, err: " + JSON.stringify(err));
})

const valueBuckets = [{
  "USERNAME": "aaa",
  "PASSWORD": "123456"
}, {
  "USERNAME": "bbb",
  "PASSWORD": "123456"
}]
// batchInsert callback形式
rdbStore.batchInsert(tableName, valueBuckets, (err, count) => {
  if (err) {
    Log.error(TAG, "batchInsert data failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "batchInsert data successful, count = " + count);
})
// batchInsert Promise形式
rdbStore.batchInsert(tableName, valueBuckets).then((count) => {
  Log.info(TAG, "batchInsert data successful, count = " + count);
}).catch((err) => {
  Log.error(TAG, "batchInsert data failed, err: " + JSON.stringify(err));
})

5.4.3 更新數(shù)據(jù)

RdbStore提供了根據(jù)RdbPredicates指定實(shí)例對(duì)象和根據(jù)DataSharePredicates指定實(shí)例對(duì)象兩種方式更新數(shù)據(jù)表中的數(shù)據(jù)，兩種方式均有callback和Promise形式，如表5-6所示。

RdbPredicates和DataSharePredicates均用于數(shù)據(jù)表中用來代表數(shù)據(jù)實(shí)體的性質(zhì)、特征或者數(shù)據(jù)實(shí)體之間關(guān)系的詞項(xiàng)，主要用于定義數(shù)據(jù)表的操作條件。如設(shè)置根據(jù)賬號(hào)查找用戶信息的條件，或者根據(jù)賬號(hào)修改用戶密碼的條件。兩者區(qū)別在于使用前者需要先指定操作的數(shù)據(jù)表名稱，同時(shí)前者為分布式數(shù)據(jù)操作做了擴(kuò)充。使用后者需要導(dǎo)入新模塊import dataSharePredicates from '@ohos.data.dataSharePredicates';

表5-6 更新數(shù)據(jù)方法

const tableName = "USER";
const valueBucket = {
  "USERNAME": "aaa",
  "PASSWORD": "123456789"
}

// RdbPredicates
let predicates = new relationalStore.RdbPredicates(tableName);
predicates.equalTo("USERNAME", "aaa");
// update callback形式
rdbStore.update(valueBucket, predicates, (err, rows) => {
  if (err) {
    Log.error(TAG, "Updated failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Updated row count: " + rows);
})
// update Promise形式
rdbStore.update(valueBucket, predicates).then((rows) => {
  Log.info(TAG, "Updated row count: " + rows);
}).catch((err) => {
  Log.error(TAG, "Updated failed, err: " + JSON.stringify(err));
})

// DataSharePredicates
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("USERNAME", "aaa");
// update callback形式
rdbStore.update(tableName, valueBucket, predicates, (err, rows) => {
  if (err) {
    Log.error(TAG, "Updated failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Updated row count: " + rows);
})
// update Promise形式
rdbStore.update(tableName, valueBucket, predicates).then((rows) => {
  Log.info(TAG, "Updated row count: " + rows);
}).catch((err) => {
  Log.error(TAG, "Updated failed, err: " + JSON.stringify(err));
})

5.4.4 查詢數(shù)據(jù)

數(shù)據(jù)表數(shù)據(jù)的查詢和更新相似，RdbStore也提供了RdbPredicates和DataSharePredicates兩種方式，如表5-7所示。不同之處在于返回的結(jié)果不同，更新數(shù)據(jù)返回受影響的行數(shù)，查詢數(shù)據(jù)返回的數(shù)據(jù)結(jié)果集ResultSet，關(guān)于結(jié)果集詳細(xì)講解將在下一節(jié)介紹。

表5-7 查詢數(shù)據(jù)方法

const tableName = "USER";
// RdbPredicates
let predicates = new relationalStore.RdbPredicates(tableName);
predicates.equalTo("USERNAME", "aaa");
// query callback形式
rdbStore.query(predicates, null, (err, resultSet) => {
  if (err) {
    Log.error(TAG, "Query failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Query successful.");
  Log.info(TAG, "ResultSet column count: " + resultSet.columnCount);
})
// query Promise形式
rdbStore.query(predicates, null).then((resultSet) => {
  Log.info(TAG, "Query successful.");
  Log.info(TAG, "ResultSet column count: " + resultSet.columnCoun
}).catch((err) => {
    Log.error(TAG, "Query failed, err: " + JSON.stringify(err));
})

// DataSharePredicates
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("USERNAME", "aaa");
// query callback形式
rdbStore.query(tableName, predicates, null, (err, resultSet) => {
  if (err) {
    Log.error(TAG, "Query failed, err: " + JSON.stringify(err));
    return;
  }
  Log.info(TAG, "Query successful.");
  Log.info(TAG, "ResultSet column count: " + resultSet.columnCount);
})
// query Promise形式
rdbStore.query(tableName, predicates, null).then((resultSet) => {
  Log.info(TAG, "Query successful.");
  Log.info(TAG, "ResultSet column count: " + resultSet.columnCount);
}).catch((err) => {
    Log.error(TAG, "Query failed, err: " + JSON.stringify(err));
})

5.4.5 刪除數(shù)據(jù)

表5-8 刪除數(shù)據(jù)方法

const tableName = "USER";
// RdbPredicates
let predicates = new relationalStore.RdbPredicates(tableName);
predicates.equalTo("USERNAME", "aaa");
// delete callback
rdbStore.delete(predicates, (err, rows) => {
  if (err) {
    Log.error(TAG, "Delete failed, err: " + JSON.string(err));
    return;
  }
  Log.info(TAG, "Delete rows: " + rows);
})
// delete Promise
rdbStore.delete(predicates).then((rows) => {
  Log.info(TAG, "Delete rows: " + rows);
}).catch((err) => {
  Log.error(TAG, "Delete failed, err: " + JSON.string(err));
})

// DataSharePredicates
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("USERNAME", "aaa");
// delete callback
rdbStore.delete(tableName, predicates, (err, rows) => {
  if (err) {
    Log.error(TAG, "Delete failed, err: " + JSON.string(err));
    return;
  }
  Log.info(TAG, "Delete rows: " + rows);
})
// delete Promise
rdbStore.delete(tableName, predicates).then((rows) => {
  Log.info(TAG, "Delete rows: " + rows);
}).catch((err) => {
  Log.error(TAG, "Delete failed, err: " + JSON.string(err));
})

6 原生SQL操作數(shù)據(jù)表

RdbStore不僅提供了適用于增刪改查簡(jiǎn)單易操作的接口方法，同時(shí)還支持原生SQL語(yǔ)句的操作。

• querySql()方法支持使用指定SQL語(yǔ)句查詢數(shù)據(jù)表中的數(shù)據(jù)

const sql = "select * from user";
rdbStore.querySql(sql).then((resultSet) => {
  Log.info(TAG, "Query successful.");
  Log.info(TAG, "ResultSet column count: " + resultSet.columnCount);
}).catch((err) => {
    Log.error(TAG, "Query failed, err: " + JSON.stringify(err));
})

7 小節(jié)

當(dāng)然RdbStore還提供了其他的方法，諸如在開始執(zhí)行SQL語(yǔ)句之前開啟事務(wù)的beginTransaction()方法、提交已執(zhí)行的SQL語(yǔ)句的commit()方法、回滾已執(zhí)行的SQL語(yǔ)句的rollBack()方法以及用于其他能力的方法。本節(jié)僅對(duì)RDB數(shù)據(jù)庫(kù)的簡(jiǎn)單使用做了講解，其中涉及到RdbPredicates、DataSharePredicates、ResultSet相關(guān)的更多內(nèi)容將在后續(xù)封裝RDB工具類中詳細(xì)介紹。