鸿蒙OS 对象关系映射数据库开发指导

场景介绍

关系型数据库是在 SQLite 基础上实现的本地数据操作机制，提供给用户无需编写原生 SQL 语句就能进行数据增删改查的方法，同时也支持原生 SQL 操作。

接口说明

数据库的创建和删除

关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的 API 如下所示。

数据库的加密

关系型数据库提供数据库加密的能力，创建数据库时传入指定密钥、创建加密数据库，后续打开加密数据库时，需要传入正确密钥。

数据库的增删改查

关系型数据库提供本地数据增删改查操作的能力，相关 API 如下所示。

• 新增

关系型数据库提供了插入数据的接口，通过 ValuesBucket 输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败则返回 -1。

• 更新

调用更新接口，传入要更新的数据，并通过AbsRdbPredicates 指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。

• 删除

调用删除接口，通过 AbsRdbPredicates 指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回 0。

• 查询

关系型数据库提供了两种查询数据的方式：

• 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的 SQL 语句进行查询操作，无需用户传入原生的 SQL。
• 执行原生的用于查询的 SQL 语句。

数据库谓词的使用

关系型数据库提供了用于设置数据库操作条件的谓词 AbsRdbPredicates，其中包括两个实现子类 RdbPredicates 和 RawRdbPredicates：

• RdbPredicates：开发者无需编写复杂的 SQL 语句，仅通过调用该类中条件相关的方法，如 equalTo、notEqualTo、groupBy、orderByAsc、beginsWith 等，就可自动完成 SQL 语句拼接，方便用户聚焦业务操作。
• RawRdbPredicates：可满足复杂 SQL 语句的场景，支持开发者自己设置 where 条件子句和 whereArgs 参数。不支持 equalTo 等条件接口的使用。

查询结果集的使用

关系型数据库提供了查询返回的结果集 ResultSet，他指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ReusltSet 的对外 API 如下表格。

事务

关系型数据库提供事务机制，来保证用户操作的原子性。对单条数据进行数据库操作时，无需开启事务；插入大量数据时，开启事务可以保证数据的准确性。如果中途操作出现失败，会执行回滚操作。

事务和结果集观察者

关系型数据库提供了事务和结果集观察者能力，当对应的事件被触发时，观察者会收到通知。

数据库的备份和恢复

用户可以将当前数据库的数据进行保存进行备份，还可以在需要的时候进行数据恢复。

开发步骤

1. 创建数据库。

1. 配置数据库相关信息，包括数据库的名称、存储模式、是否为只读模式等。
2. 初始化数据库表结构和相关数据。
3. 创建数据库。

示例代码如下：

   StoreConfig config = StoreConfig.newDefaultConfig("RdbStoreTest.db");
   private static final RdbOpenCallback callback = new RdbOpenCallback() {
       @Override
       public void onCreate(RdbStore store) {
           store.executeSql("CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER, salary REAL, blobType BLOB)");
       }
       @Override
       public void onUpgrade(RdbStore store, int oldVersion, int newVersion) {
       }
   };
   DatabaseHelper helper = new DatabaseHelper(context);
   RdbStore store = helper.getRdbStore(config, 1, callback, null);

1. 插入数据。

1. 构造要插入的数据，以 ValuesBucket 形式存储。
2. 调用关系型数据库提供的插入接口。

示例代码如下：

   ValuesBucket values = new ValuesBucket();
   values.putInteger("id", 1);
   values.putString("name", "zhangsan");
   values.putInteger("age", 18);
   values.putDouble("salary", 100.5);
   values.putByteArray("blobType", new byte[] {1, 2, 3});
   long id = store.insert("test", values);

1. 查询数据。

1. 构造用于查询的谓词对象，设置查询条件。
2. 指定查询返回的数据列。
3. 调用查询接口查询数据。
4. 调用结果集接口，遍历返回结果。

示例代码如下：

   String[] columns = new String[] {"id", "name", "age", "salary"};
   RdbPredicates rdbPredicates = new RdbPredicates("test").equalTo("age", 25).orderByAsc("salary"); 
   ResultSet resultSet = store.query(rdbPredicates, columns);
   resultSet.goToNextRow();