一步一步教你进行鸿蒙应用开发：十、本地关系型数据库[email protected]模块的使用

 前言

@ohos.data.relationalStore 是 OpenHarmony 的关系型数据库模块，基于 SQLite 实现，适用于需要复杂数据结构和事务支持的场景（如联系人管理、订单记录等）。本文主要介绍其核心功能及使用方法，最后展示在工程中如何集成此模块。

一、模块特性与核心类

1. 核心特性

• ‌关系型数据模型‌：支持表结构定义、主键、索引、关联查询。
• ‌SQL 兼容‌：可直接执行 SQL 语句或使用链式 API。
• ‌事务支持‌：保障数据操作的原子性。
• ‌数据加密‌：可选 AES-256 加密保护敏感数据。
• ‌多线程安全‌：支持跨线程访问。

2. 核心类说明

类名	作用
RdbStore	数据库操作入口，提供增删改查、事务方法
Predicates	条件构造器，封装查询条件（类似 WHERE 子句）
ResultSet	查询结果集，支持遍历和类型转换
ValuesBucket	键值对容器，用于插入或更新数据

二、数据库使用流程

 ‌1、创建数据库‌

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

const config: dataRdb.StoreConfig = {
        name: 'alarm.db',
        securityLevel: dataRdb.SecurityLevel.S2
};

rdbStore = await dataRdb.getRdbStore(context, config);

// 表结构定义 (SQL)
const sql = `CREATE TABLE IF NOT EXISTS alarms (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      time TEXT NOT NULL,
      enabled INTEGER DEFAULT 1
    )`;

await rdbStore?.executeSql(sql);

‌2、插 入数据‌

// 使用 ValuesBucket 封装数据
let values: relationalStore.ValuesBucket = {
  id: 1,
  time: '2025-05-06',
  enabled: 1
};

// 插入并获取自动生成的 id
rdbStore.insert('alarms', values, (err, rowId) => {
  if (err) {
    console.error(`插入失败: ${err.code}`);
    return;
  }
  console.log(`新记录 ID: ${rowId}`);
});

‌3、查询 数据‌

// 构造查询条件（Predicates）
let predicates = new relationalStore.RdbPredicates('alarms');
predicates.equalTo('time', '2025-05-06')
  .orderByAsc('time')
  .limit(10);

// 执行查询
rdbStore.query(predicates, ['id', 'time', 'enabled'], (err, resultSet) => {
  if (err || !resultSet) {
    console.error('查询失败');
    return;
  }
  
  // 遍历结果集
  while (!resultSet.isEnded) {
    const row = {
      id: resultSet.getLong(resultSet.getColumnIndex('id')),
      name: resultSet.getString(resultSet.getColumnIndex('time')),
      age: resultSet.getLong(resultSet.getColumnIndex('enabled'))
    };
    console.log(JSON.stringify(row));
    resultSet.goToNext();
  }
  resultSet.close(); // 必须关闭！
});

‌4、更新数据‌

let updateValues: relationalStore.ValuesBucket = {
  enabled: 1
};

// 条件：更新所有时间为2025-05-06的记录
let predicates = new relationalStore.RdbPredicates('alarms');
predicates.equalTo('time', '2025-05-06');

rdbStore.update(updateValues, predicates, (err, rowsAffected) => {
  console.log(`影响了 ${rowsAffected} 条记录`);
});

5、删除数据

let predicates = new relationalStore.RdbPredicates('alarms');
predicates.lessThanOrEqualTo('id', 10); // 删除id≤10的记录

rdbStore.delete(predicates, (err, rowsDeleted) => {
  console.log(`已删除 ${rowsDeleted} 条数据`);
});

三、注意事项

1. ‌性能优化‌

   • 批量操作使用事务减少 I/O 开销
   • 频繁查询字段建立索引

   rdbStore.executeSql('CREATE INDEX idx_alarms_time ON alarms(time)');
   

2. ‌线程管理‌

   • 通过 getRdbStore 获取的实例可在多线程共享
   • 避免在 UI 线程执行耗时操作

3. ‌错误码处理‌

   错误码	含义
   14800000	数据库已关闭
   14800001	无效参数
   14800011	唯一约束冲突

4. ‌结果集管理‌

   • 及时调用 resultSet.close() 释放资源
   • 避免在循环中频繁打开新查询

四、示例代码：闹钟管理

示例继续在上一篇文章的基础上增加一个关系型数据库alarm.db，用来存储闹钟设置数据，本示例只简单的演示数据库的初始化、创建表及查询数据的方法，详细的使用请参考使用指导自己扩展使用，代码中新建了一个数据库管理类，用于初始化数据库，并提供了泛型支持的解析工具方法，方便大家在自己创建表时使用。

import dataRdb from '@ohos.data.relationalStore';
import Logger from '../util/Logger'
import { EntityFactory } from '../db/EntityFactory';

const TAG: string = 'DatabaseManager';


export class DatabaseManager {
  private static rdbStore: dataRdb.RdbStore;

  static getDB(): dataRdb.RdbStore {
    return DatabaseManager.rdbStore
  }

  static async init(context: Context, isFirstRun: boolean) {
    if (!DatabaseManager.rdbStore) {
      const config: dataRdb.StoreConfig = {
        name: 'alarm.db',
        securityLevel: dataRdb.SecurityLevel.S2
      };
      DatabaseManager.rdbStore = await dataRdb.getRdbStore(context, config);

      if (isFirstRun) {
        await DatabaseManager.createTables();
      }

    }
    return DatabaseManager.rdbStore;
  }

  private static async createTables() {

    const sql = `CREATE TABLE IF NOT EXISTS alarms (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      time TEXT NOT NULL,
      enabled INTEGER DEFAULT 1
    )`;
    await DatabaseManager.rdbStore?.executeSql(sql);
    Logger.info('#################### create table success')
  }

  static async querySql(sql:string, factory: EntityFactory) : Promise {
    const resultSet = await DatabaseManager.rdbStore?.querySql(sql);
    const dataList:T[] = []

    try {
      if (resultSet.rowCount > 0) {
        while (resultSet.goToNextRow()) {

          const data: Record = {};
          resultSet.columnNames.forEach(col => {
            data[col] = resultSet.getValue(resultSet.getColumnIndex(col));
          });
          dataList.push(factory.fromData(data));

        };
      }
    } catch (err) {
      Logger.error(`#################### get data fail: ${err.message}`)
    } finally {
      resultSet.close(); // 显式关闭结果集
    }

    return dataList || [];
  }

}

示例代码请参考：关系型数据库@ohos.data.relationalStore数据库管理类DatabaseManager.zip