跳到主要内容

preferences数据库调试工具指导

当前开发者在使用preferences数据库进行开发调试和定位问题时，无法查看数据库文件中的内容信息，如元数据和用户数据等。

为了提升开发者的工作效率，数据库调试工具支持开发者查看设备中的preference_kv数据库和preference_xml数据库内容。

其中，preference_kv数据库对应的首选项存储模式为GSKV存储模式；preference_xml数据库对应的首选项存储模式为XML存储模式。

从HarmonyOS 6.0.0版本开始，支持使用preferences数据库调试工具。

环境要求​

  • 在使用本工具前，开发者需要先获取hdc工具，开启开发者选项，执行hdc shell。
  • 此调试工具仅支持调试应用使用，配置调试应用具体可见配置应用可调试。
  • 正常连接设备。

操作准备​

  • 在使用preferences调试工具之前，必须要先切换至目标调试应用路径下，再使用arkdata命令进入到preferences调试工具（需要使用arkdata配置相关参数打开preferences数据库，开库成功后才能使用preferences工具进行数据的增删改查）。

    arkdata命令支持的参数如下表所示：

    参数参数值类型描述
    -t字符串数据库类型，进入到对应的数据库调试工具， 取值范围：{preference_kv, preference_xml, vector}。
    -f字符串数据库文件全路径，包含文件名， 路径不能以‘/’结尾。
    -p整型数据库pagesize，数据库开库配置参数，代表存储的单页大小，默认值32，可取值为是4、8、16、32、64。
    -c整型数据库cacheSize，数据库开库配置参数，即bufferPoolSize，代表内存缓存池大小， 默认值2048，可取值为2048和4096。
    -h不涉及打印程序帮助信息。

    preferences数据库调试工具-p和-c两个参数无效，数据库pagesize和cachesize，输入限定范围内的值时，直接使用默认值，默认值为32和2048，输入限定范围外的值时会报错。

    C:\Users\*****>hdc shell
    $ cd /data/app/el1/100/base/com.test.myapplication   // 进入到目标调试应用路径下(当前路径为示例,开发者需自己获取调试应用路径)
    $ arkdata -t preference_kv                           // 缺省-f, 没有指定数据库文件，默认新建一个名字为arkdata的数据库，路径在当前工作目录的data/preference_kv目录下.
    Enter ".help" for usage hints.

    在非调试应用路径下，执行数据库开库操作时，缺少-f默认创建文件夹，在当前目录下创建data/preference_kv文件夹层级失败，具体报错如下：

    C:\Users\*****>hdc shell
    $ arkdata -t preference_kv
    [unsucc]Failed to create directory ./data/preference_kv : Permission denied

    在非调试应用路径下，执行数据库开库操作时，指定路径，db文件创建失败，具体报错如下：

    C:\Users\*****>hdc shell
    $ arkdata -t preference_kv -f ./preference_kv
    [GMDB SERVER] [GMERR-1013000] multi-process init init unsucc!
    [ERROR] open db fail, ret = -5000.

    preference_xml和preference_kv数据库同名不能交叉读写操作，不能混用，preference_kv打开preference_xml数据库会报错，preference_xml打开preference_kv数据库会损坏，具体报错如下：

    $ ls ./data/preference_kv
    arkdata       arkdata.ctrl.dwr  arkdata.redo  arkdata.undo
    arkdata.ctrl  arkdata.map       arkdata.safe
    $ ls ./data/preference_xml/
    arkdata  arkdata.lock
    $ arkdata -t preference_kv -f ./data/preference_xml/arkdata
    [GMDB SERVER] [GMERR-1019003] open-mode check init unsucc!
    [unsucc] open db fail, ret = -43000
    $ arkdata -t preference_xml -f ./data/preference_kv/arkdata
    Enter ".help" for usage hints.
    preference_xml>>> /data/temp/./data/preference_kv/arkdata:1: parser error : Start tag expected, '<' not found
    ^

  • 可使用arkdata --help查看整个数据库的相关参数。

    C:\Users\*****>hdc shell
    $ arkdata --help
    USAGE
      arkdata [option]
    OPTION
      -t|--type      <preference_kv | preference_xml | vector>, it is mandatory
      -f|--file      <database file path> 
      -p|--pageSize  <database pageSize>  
      -c|--cacheSize <database cacheSize>
      -h|--help

命令列表​

preference_kv和preference_xml调试工具支持的命令如下表所示：

命令格式命令描述
.help显示帮助信息。
.q.quit
get key:{key name}根据指定的key查询数据库。
put key:{key name} value:{value}插入指定的键值对到数据库或者更新键值对。输入需要两行，第一行输入key，使用“key:”作为关键字，第二行输入value，使用“value:”作为关键字。 例如：put key:123 value:345
delete key:{key name}删除指定键值对。 例如：delete key:123
delete删除表内所有内容。
scan全表查询。 **说明：**preference_xml支持全表查询，preference_kv不支持全表查询。

约束限制​

  • 数字默认为int类型，若以引号赋予数字值，将识别为string类型。
  • 命令行输入数据仅支持string、number和boolean类型，其他类型将被转换为string类型。
  • 由于hdc使用中文会显示乱码，因此数据库调试工具不支持中文。
  • 支持的设备：Phone、PC/2in1。

命令的具体使用及示例​

帮助命令（.help）​

打开preference_kv或者preference_xml数据库后，使用帮助命令可以查看其支持的命令。

preference_kv>>> .help
preference_xml>>> .help

创建或打开已有的数据库​

  1. 执行hdc shell命令进入shell交互模式。

  2. 必须要先切换至目标调试应用路径下，再进入存在db文件的路径下，执行"arkdata -t preference_kv -f perfdata"或者"arkdata -t preference_xml -f perfdata"新建一个数据库。

    C:\Users\*****>hdc shell
    $ cd /data/app/el1/100/database/com.test.myapplication   // 进入到目标调试应用路径下.(当前路径为示例,开发者需自己获取调试应用路径)
    $ cd entry/rdb/                                          // 需要进入到有db文件的路径下,保证有读写权限,才能有权限创建新数据库.
    $ arkdata -t preference_kv
    Enter ".help" for usage hints.
    preference_kv>>>.q
    $ arkdata -t preference_xml
    Enter ".help" for usage hints.
    preference_xml>>> put key:1                               // preference_xml需要put一条数据,内部才会触发创建数据库文件.
     ...>>> value:1
    preference_xml>>> .q

  3. 创建新的数据库时，系统会自动生成以下类型的文件， 标签debug_hap_data_file代表属于调试应用。

    $ ls -lZ ./data/preference_kv/
    total 148
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0  73728 2025-08-12 20:31 arkdata
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0   4112 2025-08-12 20:31 arkdata.ctrl
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0  12304 2025-08-12 20:31 arkdata.ctrl.dwr
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0      0 2025-08-12 20:31 arkdata.map
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0    512 2025-08-12 20:31 arkdata.redo
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0      8 2025-08-12 20:31 arkdata.safe
    -rw-rw---- 1 shell shell u:object_r:debug_hap_data_file:s0  16384 2025-08-12 20:31 arkdata.undo

    $ ls -lZ ./data/preference_xml/
    total 12
    -rw-rw---- 1 root ddms u:object_r:debug_hap_data_file:s0  105 2025-09-05 15:11 arkdata
    -rw-rw---- 1 root ddms u:object_r:debug_hap_data_file:s0    0 2025-09-05 15:11 arkdata.lock

  4. 打开已有数据库。

    $ arkdata -t preference_kv -f ./data/preference_kv/arkdata
    Enter ".help" for usage hints.
    preference_kv>>>

插入数据​

在preference_kv>>>提示符下，可通过put命令插入指定键值对，显示结果如下：

preference_kv>>> put key:name
 ...>>> value:123
preference_kv>>> put key:id_name
 ...>>> value:'123'
preference_kv>>> get key:name   // 不带引号结果
type int: 123
preference_kv>>> get key:id_name   // 带引号结果
type string: 123

全表查询​

  • 在preference_xml>>>提示符下，可通过scan命令全表查询，显示结果如下：

    preference_xml>>> scan
    ==========================PREFERENCES XML INFO============================
    DataCount:7
    ==========================PREFERENCES XML DATA============================
    ==========================Data Index:1==========================
    key:
    1
    value:
    type int: 1
    ==========================Data Index:2==========================
    key:
    2
    value:
    type int: 2
    ==========================Data Index:3==========================
    key:
    3
    value:
    type int: 3
    ==========================Data Index:4==========================
    key:
    4
    value:
    type int: 4
    ==========================Data Index:5==========================
    key:
    5
    value:
    type int: 5
    Press 'q' to quit, 'n' to continue: n
    ==========================Data Index:6==========================
    key:
    6
    value:
    type int: 6
    ==========================Data Index:7==========================
    key:
    7
    value:
    type int: 7
    preference_xml>>>

  • preference_kv不支持全表扫描，显示结果如下：

    preference_kv>>> scan
    [unsucc] Unable to parse command.

当显示数据条目达到5条时，为提升阅读体验，系统将提示用户是否继续显示或退出。输入q键退出显示，输入n继续显示结果。

单值查询​

在preference_kv>>>提示符下，可通过get命令指定key查询指定键值对，显示结果如下：

preference_kv>>> get key:name
 No data for key = name  // 表示没有值

带引号与不带引号查询的值不同，显示结果如下：

preference_kv>>> put key:name
 ...>>> value:123
preference_kv>>> put key:id_name
 ...>>> value:'123'
preference_kv>>> put key:name
 ...>>> value:true
preference_kv>>> put key:name1
 ...>>> value:'true'
preference_kv>>> get key:name      // 数字不带引号结果
type int: 123
preference_kv>>> get key:id_name   // 数字带引号结果
type string: 123
preference_kv>>> get key:name      // true不带引号结果
type bool: 1
preference_kv>>> get key:name1     // true带引号结果
type string: true

更新数据​

在preference_kv>>>提示符下，当key值存在时， 可通过put命令更新键值对，显示结果如下：

preference_kv>>> put key:name
 ...>>> value:x
preference_kv>>> get key:name
type string: x
preference_kv>>> put key:name
 ...>>> value:y
preference_kv>>> get key:name
type string: y

删除数据​

在preference_kv>>>提示符下，可通过delete命令删除指定键值对，显示结果如下：

preference_kv>>> get key:name
type string: y
preference_kv>>> delete key:name
preference_kv>>> get key:name
 No data for key = key:name

delete命令不指定键值对全表删除，显示结果如下：

preference_kv>>> get key:name
type int: xx
preference_kv>>> get key:id_name
type int: yy
preference_kv>>> delete
preference_kv>>> get key:name
 No data for key = name
preference_kv>>> get key:id_name
 No data for key = id_name

在preference_kv>>>提示符下，可以使用 .q或者.quit命令退出数据库交互模式，显示结果如下：

preference_kv>>>.q
$

模拟器支持情况​

当前工具支持模拟器。

常见问题​

如何删除字符​

使用Ctrl+BackSpace删除单个字符，使用Ctrl+U删除全部字符。