1# 关系型数据库开发指导 2 3## 场景介绍 4 5关系型数据库是在SQLite基础上实现的本地数据操作机制，提供给用户无需编写原生SQL语句就能进行数据增删改查的方法，同时也支持原生SQL语句操作。 6 7## 接口说明 8### 数据库的创建和删除 9 10关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的API如下所示。 11 12表1 数据库创建和删除API 13 14| 类名 | 接口名 | 描述 | 15| ---- | ---- | ---- | 16| RdbStoreConfig | RdbStoreConfig(const std::string &path, <br> StorageMode storageMode = StorageMode::MODE_DISK, <br> bool readOnly = false, <br> const std::vector<uint8_t> &encryptKey = std::vector<uint8_t>(), <br> const std::string &journalMode = "", <br> const std::string &syncMode = "", <br> const std::string &databaseFileType = "", <br> const std::string &databaseFileSecurityLevel = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。 <ul><li> path：数据库路径；</li><li> readOnly：是否只读；</li><li> storageMode：存储模式；</li><li> encryptKey：加密密钥; </li><li> journalMode：日志模式；</li><li> syncMode：同步模式；</li><li> databaseFileType：数据库类型； </li><li> databaseFileSecurityLevel：安全等级 </li></ul> | 17| RdbOpenCallback | int OnCreate(RdbStore &rdbStore) | 数据库创建时被回调，开发者可以在该方法中初始化表结构，并添加一些应用使用到的初始化数据。 | 18| RdbOpenCallback | int OnUpgrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库升级时被回调。 | 19| RdbOpenCallback | int OnDowngrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库降级时被回调。 | 20| RdbHelper | std::shared_ptr\<RdbStore\> GetRdbStore(const RdbStoreConfig &config, int version, RdbOpenCallback &openCallback, int &errCode) | 根据配置创建或打开数据库。 | 21| RdbHelper | int DeleteRdbStore(const std::string &path) | 删除指定的数据库。 | 22 23### 数据库的加密 24 25关系型数据库提供数据库加密的能力，在创建数据库时若指定了密钥，则会创建为加密数据库。再次使用此数据库时，需要指定该密钥，才能正确打开数据库。 26 27表2 数据库修改密钥API 28| 类名 | 接口名 | 描述 | 29| ---- | ---- | ---- | 30| RdbStore | int ChangeEncryptKey(const std::vector<uint8_t> &newKey) | 为数据库设置新的加密密钥。注：仅支持加密数据库更换加密密钥。 | 31 32### 数据库谓词的使用 33 34关系型数据库提供了用于设置数据库操作条件的谓词AbsRdbPredicates，其中包括两个实现子类RdbPredicates和RawRdbPredicates： 35 36- RdbPredicates：开发者无需编写复杂的SQL语句，仅通过调用该类中条件相关的方法，如equalTo、notEqualTo、groupBy、orderByAsc、beginsWith等，就可自动完成SQL语句拼接，方便用户聚焦业务操作。 37- RawRdbPredicates：可满足复杂SQL语句的场景，支持开发者自己设置where条件子句和whereArgs参数。不支持equalTo等条件接口的使用。 38 39 表3 数据库谓词API 40 | 类名 | 接口名 | 描述 | 41 | ---- | ---- | ---- | 42 | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值相等。 | 43 | RdbPredicates | AbsPredicates *NotEqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值不相等。 | 44 | RdbPredicates | AbsPredicates *BeginsWith(std::string field, std::string value) | 设置谓词条件，满足field字段以value值开头。 | 45 | RdbPredicates | AbsPredicates *Between(std::string field, std::string low, std::string high) | 设置谓词条件，满足field字段在最小值low和最大值high之间。 | 46 | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | 设置谓词条件，根据field字段升序排列。 | 47 | RdbPredicates | void SetWhereClause(std::string whereClause) | 设置where条件子句。 | 48 | RdbPredicates | void SetWhereArgs(std::vector\<std::string\> whereArgs) | 设置whereArgs参数，该值表示where子句中占位符的值。 | 49 | RdbPredicates | AbsRdbPredicates *InDevices(std::vector<std::string>& devices) | 设置谓词条件，同步分布式数据库时指定组网内的远程设备。 | 50 | RdbPredicates | AbsRdbPredicates *InAllDevices() | 设置谓词条件，同步分布式数据库时连接到组网内的所有远程设备。| 51 52 53### 数据表的增删改查 54 55关系型数据库提供对本地数据增删改查操作的能力，相关API如下所示。 56 57- 新增 58 59 关系型数据库提供了插入数据的接口，通过ValuesBucket输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败时则返回-1。 60 61 表4 数据表插入API 62 63 | 类名 | 接口名 | 描述 | 64 | ---- | ---- | ---- | 65 | RdbStore | int Insert(int64_t &outRowId, const std::string &table, const ValuesBucket &initialValues) | 向数据库插入数据。<ul><li>table：待添加数据的表名。 </li><li> initialValues：以ValuesBucket存储的待插入的数据。它提供一系列put方法，如PutString(const std::string &columnName, const std::string &value)，PutDouble(const std::string &columnName, double value)，用于向ValuesBucket中添加数据。</li></ul> | 66 67- 删除 68 69 调用删除接口，通过AbsRdbPredicates指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回0。 70 71 表5 数据表删除API 72 | 类名 | 接口名 | 描述 | 73 | ---- | ---- | ---- | 74 | RdbStore | int Delete(int &deletedRows, const AbsRdbPredicates &predicates) | 删除数据。<ul><li> deletedRows：删除的记录条数。 </li><li> predicates：Rdb谓词，指定了删除操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。<ul><li> RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。</li><li> RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。 </li></ul></li></ul> | 75 76- 更新 77 78 调用更新接口，传入要更新的数据，并通过AbsRdbPredicates指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。 79 80 表6 数据表更新API 81 | 类名 | 接口名 | 描述 | 82 | ---- | ---- | ---- | 83 | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | 更新数据库表中符合谓词指定条件的数据。<ul><li> changedRows：更新的记录条数。 </li><li> values：以ValuesBucket存储的要更新的数据。 </li><li> predicates：指定了更新操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。<ul><li> RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。</li><li> RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。 </li></ul></li></ul> | 84 85- 查询 86 87 关系型数据库提供了两种查询数据的方式： 88 89 - 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的SQL语句进行查询操作，无需用户传入原生的SQL语句。 90 - 执行原生的SQL语句进行查询操作。 91 92 表7 数据表查询API 93 | 类名 | 接口名 | 描述 | 94 | ---- | ---- | ---- | 95 | RdbStore | std::unique_ptr<AbsSharedResultSet> Query(const AbsRdbPredicates &predicates, const std::vector\<std::string\> columns) | 查询数据。<ul><li> predicates：谓词，可以设置查询条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。<ul><li> RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。</li><li> RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。 </li></ul> <li> columns：规定查询返回的列。</li></ul></li></ul> | 96 | RdbStore | std::unique_ptr<AbsSharedResultSet> QuerySql(const std::string &sql, const std::vector\<std::string\> &selectionArgs = std::vector\<std::string\>()) | 执行原生的用于查询操作的SQL语句。<ul><li> sql：原生用于查询的sql语句。</li><li> selectionArgs：sql语句中占位符参数的值，若select语句中没有使用占位符，该参数可以设置为null。</li></ul> | 97 98### 查询结果集的使用 99 100关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 101 102表8 结果集API 103| 类名 | 接口名 | 描述 | 104| ---- | ---- | ---- | 105| ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | 106| ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | 107| ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | 108| ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | 109| ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | 110| ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | 111| ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | 112| ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | 113| ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | 114| ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | 115| ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | 116| ResultSet | int GetBlob(int columnIndex, std::vector\<uint8_t\> &blob) | 获取当前行指定列的值，以字节数组形式返回。 | 117| ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | 118 119### 设置分布式列表 120 121用户可以对当前数据库中的列表设置为分布式列表。 122 123表9 设置分布式列表 124| 类名 | 接口名 | 描述 | 125| ---- | ---- | ---- | 126| RdbStore | bool SetDistributedTables(const std::vector<std::string>& tables) | 设置分布式列表。<ul><li> tables：要设置的分布式列表表名 </li></ul> 127 128### 根据本地表名获取指定远程设备的分布式表名 129 130用户根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名。 131 132表9 根据本地表名获取指定远程设备的分布式表名 133| 类名 | 接口名 | 描述 | 134| ---- | ---- | ---- | 135| RdbStore | std::string ObtainDistributedTableName(const std::string& device, const std::string& table) | 根据本地表名获取指定远程设备的分布式表名。在查询远程设备数据库时，需要使用分布式表名。<ul><li> device：远程设备ID </li><li> table：本地表名</li></ul> 136 137### 在设备之间同步数据 138 139表10 在设备之间同步数据 140| 类名 | 接口名 | 描述 | 141| ---- | ---- | ---- | 142| RdbStore | bool Sync(const SyncOption& option, const AbsRdbPredicates& predicate, const SyncCallback& callback) | 在设备之间同步数据。<ul><li> option：同步选项；mode：同步模式(PUSH表示数据从本地设备推送到远程设备/PULL表示数据从远程设备拉至本地设备)；isBlock：是否阻塞 </li><li> callback：指定的callback回调函数</li></ul> 143 144### 注册数据库的观察者 145 146表10 注册数据库的观察者 147| 类名 | 接口名 | 描述 | 148| ---- | ---- | ---- | 149| RdbStore | bool Subscribe(const SubscribeOption& option, RdbStoreObserver *observer) | 注册数据库的观察者。当分布式数据库中的数据发生更改时，将调用回调。<ul><li> option：订阅类型；</li><li> observer：指分布式数据库中数据更改事件的观察者</li></ul> 150 151### 从数据库中删除指定类型的指定观察者 152 153表10 从数据库中删除指定类型的指定观察者 154| 类名 | 接口名 | 描述 | 155| ---- | ---- | ---- | 156| RdbStore | bool UnSubscribe(const SubscribeOption& option, RdbStoreObserver *observer) | 从数据库中删除指定类型的指定观察者。<ul><li> option：订阅类型；</li><li> observer：指已注册的数据更改观察者</li></ul> 157 158## 约束与限制 159 160无。 161 162## 开发步骤 163 1641. 创建数据库。 165 166 a. 配置数据库相关信息，包括数据库的名称、存储模式、是否为只读模式等。 167 168 b. 初始化数据库表结构和相关数据。 169 170 c. 创建数据库。 171 172 示例代码如下： 173 ``` 174 const std::string DATABASE_NAME = RDB_TEST_PATH + "RdbStoreTest.db"; 175 const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, salary REAL, blobType BLOB)"; 176 177 class OpenCallback : public RdbOpenCallback { 178 public: 179 int OnCreate(RdbStore &rdbStore) override; 180 int OnUpgrade(RdbStore &rdbStore, int oldVersion, int newVersion) override; 181 }; 182 183 int OpenCallback::OnCreate(RdbStore &store) 184 { 185 return store.ExecuteSql(CREATE_TABLE_TEST); 186 } 187 188 RdbStoreConfig config(DATABASE_NAME); 189 OpenCallback callback; 190 191 std::shared_ptr<RdbStore> store = RdbHelper::GetRdbStore(config, 1, callback, 0); 192 ``` 193 1942. 插入数据。 195 196 a. 构造要插入的数据，以ValuesBucket形式存储。 197 198 b. 调用关系型数据库提供的插入接口。 199 200 c. 创建数据库。 201 202 示例代码如下： 203 ``` 204 ValuesBucket values; 205 206 values.PutInt("id", 1); 207 values.PutString("name", std::string("Tom")); 208 values.PutInt("age", 18); 209 values.PutDouble("salary", 100.5); 210 values.PutBlob("blobType", std::vector<uint8_t>{ 1, 2, 3 }); 211 store->Insert(id, "test", values); 212 ``` 213 2143. 查询数据。 215 216 a. 构造用于查询的谓词对象，设置查询条件。 217 218 b. 指定查询返回的数据列。 219 220 c. 调用查询接口查询数据。 221 222 d. 调用结果集接口，遍历返回结果。 223 224 示例代码如下： 225 ``` 226 std::vector<std::string> columns = {"id", "name", "age", "salary"}; 227 228 RdbPredicates predicates("test"); 229 predicates.EqualTo("age", "25")->OrderByAsc("salary"); 230 std::unique_ptr<ResultSet> resultSet = store->Query(predicates, columns) 231 resultSet.goToNextRow(); 232 ``` 233 2344. 设置分布式同步表 235 236 a. 调用接口设置分布式同步表。 237 238 示例代码如下： 239 240 ``` 241 store->SetDistributedTables("test"); 242 ``` 243 2445. 分布式数据同步 245 246 a. 定义同步模式和阻塞状态。 247 248 b. 构造用于同步分布式表的谓词对象，指定组网内的远程设备。 249 250 c. 调用接口同步数据。 251 252 示例代码如下： 253 254 ``` 255 SyncOption option; 256 option.mode = PUSH; 257 option.isBlock = true; 258 AbsRdbPredicates predicate("test"); 259 predicate.InAllDevices(); 260 store->Sync(option, predicate, []（const SyncResult& result) { 261 for (const auto& [device, status] : result) { 262 LogI("device=%s status=%d", device.c_str(), status); 263 } 264 }); 265 ``` 266 2676. 分布式数据订阅 268 269 a. 重写数据更改观察者OnChange()函数。 270 271 b. 定义分布式数据订阅类型。 272 273 c. 调用接口实现分布式数据订阅，或取消订阅。 274 275 示例代码如下： 276 277 ``` 278 class MyObserver : public RdbStoreObserver { 279 public: 280 void OnChange(const std::vector<std::string>& devices) override { 281 for (const auto& device : devices) { 282 LOGI("device=%s data change", device.c_str()); 283 } 284 } 285 }; 286 287 SubscribeOption option; 288 option.mode = SubscribeMode::REMOTE; 289 MyObserver observer; 290 store->Subscribe(option, &observer); // 分布式数据订阅 291 292 store->UnSubscribe(option, &observer); // 取消订阅 293 ``` 294 2957. 跨设备查询 296 297 a. 根据本地表名获取指定远程设备的分布式表名。 298 299 b. 根据指定SQL语句查询数据库中的数据。 300 301 示例代码如下： 302 ``` 303 std::string tableName = store->ObtainDistributedTableName("123456789abcd", "test"); 304 auto resultSet = store->QuerySql("SELECT * from ?;", tableName); 305 ``` 306