# debug-database

**Repository Path**: jiang-hang-liu/debug-database

## Basic Information

- **Project Name**: debug-database
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 8
- **Created**: 2024-08-30
- **Last Updated**: 2024-11-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS Debug Database (debug-db)

### HarmonyOS Debug Database 是一款功能强大的鸿蒙应用数据库调试工具，方便开发人员在应用程序 Debug 版本下快速调试关系型数据库 (RdbStore)、用户首选项 (Preferences)、键值数据库 (KVStore)

与 [Android-Debug-Database](https://github.com/amitshekhariitbhu/Android-Debug-Database?tab=readme-ov-file) 相似， HarmonyOS Debug Database
可使开发者以非常简单的方式在**浏览器**中直接查看和操作三种 HarmonyOS 数据库，提升调试效率。

## 功能特性

**以下所有的功能都可以在不需要对设备进行 Root 操作（无需Root设备）的情况下使用：**

- 查看所有的 RdbStore 数据库 (包括加密数据库)
- 查看指定 RdbStore 数据库中的所有表
- 查看 RdbStore 数据库中指定表的所有数据
- 在指定的 RdbStore 数据库上运行任何SQL查询来创建、删除数据库，或增删改查数据库数据
- 直接对 RdbStore 数据进行增删改查
- 下载指定 RdbStore 对应的数据库文件
- 查看所有的 Preferences
- 查看指定 Preferences中所有首选项数据
- 直接对 Preferences 数据进行增删改查
- 查看所有的 KVStore (包括加密KV数据库，需手动配置)
- 查看指定 KVStore 中所有键值对数据
- 直接对 KVStore 数据进行增删改查

## 使用说明

#### 下载安装

```
ohpm install @hadss/debug-db
```

#### 简单使用

```
import {DebugDB} from '@hadss/debug-db';

...
const context = getContext(this) as common.UIAbilityContext;
DebugDB.initialize(context); // 在浏览器中访问 http://XXX.XXX.XXX.XXX:8080/index.html (详细地址请在 Log 中查看)
```

#### 进阶使用

**1、开启条件编译**

在项目打包时通常不希望将 Debug 版本使用的三方库打包进 Release 版本的 HAP 包中，因此需要在项目**build-profile.json5**配置文件中加入**条件编译**参数，并设置：

```
"buildOption":{
    "arkOptions":{
        "branchElimination":true
    }
}
```

关于应用编译选项的配置，详情可参考：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-profile-V5

**2、在应用中导入 DebugDB，设置 UIAbilityContext 及服务端运行的端口 ( 默认为 8080 )，依据需要配置加密的KV数据库名**

下面为在应用中 ability 的 aboutToApper 阶段导入并启动 DebugDB 的一个完整示例。你也可以在应用程序的其他位置启动 DebugDB 服务：

```
import {common} from '@kit.AbilityKit';
import {DEBUG} from 'BuildProfile';

...
aboutToApper():void{
    if(DEBUG){
        const context = getContext(this) as common.UIAbilityContext;
        const port = 8080;
        import('@hadss/debug-db').then(async ns => {
           await ns.DebugDB.initialize(context, { port: 9090, encryptedKVStoreNames: ['MyEncryptedKVStore'] }); // context为必要参数，根据需要配置可选参数
        })
    }
}

```
其中，DebugDB相关启动参数以“对象”的形式配置。

在编译过程中，由于已开启了**条件编译**，编译器会对 BuildProfile 中的 **DEBUG** 字段进行判断，并根据当前打包的环境 (Debug 或 Release) 对未生效的代码进行编译剪枝，生成的 HAP 包中仅包含开发者的项目代码。

**3、在浏览器中访问 DebugDB**

当开发者启动应用程序后，应用后台会自动启动 DebugDB 服务，若成功启动，则可以在 DevEco Studio 的 Log 界面查看到以下日志：

```
You can access DebugDB through http://XXX.XXX.XXX.XXX:8080/index.html
```

日志中的网址即为 DebugDB 运行时的界面首页，另外，你也可以通过`await DebugDB.getDebugDBAddress()`直接获取到 DebugDB 的运行地址。

当应用程序处于运行状态时，你可以在浏览器中输入上述地址直接访问服务端，如果你希望手动开启和关闭服务，你可以通过`await DebugDB.start()`和`await DebugDB.stop()`直接开启和关闭服务。

#### 注意事项

- 真机和使用浏览器的设备需要处于同一个网络环境 (Wifi 或 LAN)
- 目前DevEco Studio 中集成的 HarmonyOS 模拟器暂不支持联网，若应用在模拟器启动则无法在外部设备的浏览器中直接访问 Debug 服务端。

## DebugDB 界面

**RdbStore**

![](https://contentcenter-drcn.dbankcdn.cn/pub_1/DevEcoSpace_1_900_9/ce/v3/UlRi76KbRRKCwiz11g9LWw/Uu_Qe41uQmORYDQH0HMwFw.png)
![](https://contentcenter-drcn.dbankcdn.cn/pub_1/DevEcoSpace_1_900_9/9b/v3/LbNjVQzuSUCBdxiolFuvDA/WfFzqB1ERj2n9RewFLxD-w.png)

**Preferences**

![](https://contentcenter-drcn.dbankcdn.cn/pub_1/DevEcoSpace_1_900_9/13/v3/O-n7VI5XSzmj16smDfmd7Q/M0pxlo7sSf2eRFPBXalpzQ.png)

**KVStore**

![](https://contentcenter-drcn.dbankcdn.cn/pub_1/DevEcoSpace_1_900_9/ce/v3/T9r3Fjf6QYyhzzL8MgTRhA/fwHB8F2JRfO6rkkmZIjhrg.png)

## 常见错误

**1. 启动 Debug 服务后，访问浏览器无法显示页面**
- 查看浏览器的设备与移动设备不处于同一个局域网中
- 所配置的启动端口已经被占用

**2. 查询加密KV数据库时出现红体 “Query Execution Failed”**
- 未在启动时配置加密KV数据库名

**3. DevEco 没有输出服务端地址信息**
- 应用启动模式为 Release 模式

## 其他说明

**服务端**
本项目使用的服务端为开源库 [polka](https://ohpm.openharmony.cn/#/cn/detail/@ohos%2Fpolka)。

**相关权限**

由于需要通过浏览器直接访问服务端获取数据库信息，因此 debug-db 使用了以下权限：

```
"requestPermission":[{
      "name": "ohos.permission.INTERNET"
    },{
      "name": "ohos.permission.GET_WIFI_INFO"
    },{
      "name": "ohos.permission.GET_NETWORK_INFO"
    }]
```

**约束与限制**

在下述版本通过验证：
DevEco Studio NEXT Developer Beta6 (5.0.3.706) --SDK:API 12 (5.0.0.61)

**觉得这个项目有用吗？❤️**

- 点击此页面右上角的⭐按钮来支持本项目。✌️

本项目当前为 RC 版本，我们后续将会开发更多的功能并对错误进行修复，使用过程中发现的任何问题都可以提issue给我们，欢迎你的反馈。

**开源协议**

本项目基于[Apache License 2.0](https://gitee.com/openharmony-tpc/ImageKnife/blob/master/LICENSE)，请自由地享受与参与开源。🌏