目录

Preferences Database Debugging Tool Guide

Currently, when using the preferences database for development, debugging, and problem locating, developers are unable to view the content information in the database files, such as metadata and user data.

To improve developers' work efficiency, the database debugging tool allows developers to view the preference_kv and preference_xml databases on devices.

The preference storage mode corresponding to the preference_kv database is GSKV mode, and that corresponding to the preference_xml database is XML mode.

The preferences database debugging tool is available since HarmonyOS 6.0.0.

Environment requirements

Preparations

Command List

The following table lists the commands supported by the preference_kv and preference_xml debugging tools.

Command Format Description
.help Displays the help information.
.q | .quit Exits the database interaction mode.
get key:{key name} Queries the database based on the specified key.

put key:{key name}

value:{value}

Inserts a KV pair to the database or updates the KV pair. You need to input two lines of commands, where the first line uses key: as the keyword and the second line uses value: as the keyword.

Example: put key:123

value:345
delete key:{key name}

Deletes a KV pair.

Example: delete key:123
delete Deletes all contents in the table.
scan

Scans the full table.

Note: preference_xml supports full table query, but preference_kv does not.

Constraints

Command Usage and Examples

[h2]Displaying All Commands and Descriptions

After the preference_kv or preference_xml database is opened, you can run the .help command to view the supported commands.

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

[h2]Creating or Opening an Existing Database

  1. Run the hdc shell command to enter the shell interaction mode.

  2. You must switch to the path of the target debugging application, and then go to the path where the .db file is located. Run the arkdata -t preference_kv command (with -f set to the default value) or the arkdata -t preference_xml command (with -f set to the default value) to create a database.

    C:\Users\*****>hdc shell
$ cd /data/app/el1/100/database/com.test.myapplication   // Go to the target application path. (The current path is an example. Go to the path based on your actual needs.)
$ cd entry/rdb/                                          // Go to the path where the .db file exists. You need to have the read and write permissions on the .db file to create a new database.
$ 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 needs to put a data record so that the database file can be created internally.
 ...>>> value:1
preference_xml>>> .q

  3. Wait for the system to automatically generate the following files. The tag debug_hap_data_file indicates that the file is the target app 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. Open an existing database.

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

[h2]Inserting Data

At the preference_kv>>> prompt, you can insert a KV pair using the put command, and the following information is displayed.

preference_kv>>> put key:name
 ...>>> value:123
preference_kv>>> put key:id_name
 ...>>> value:'123'
preference_kv>>> get key:name   // Result without quotation marks.
type int: 123
preference_kv>>> get key:id_name   // Result with quotation marks.
type string: 123

[h2]Scan the full table.

When the number of displayed data items reaches 5, the system asks you whether to continue displaying or exit. Enter q to exit the display or enter n to continue displaying.

[h2]Querying a Single Value

At the preference_kv>>> prompt, you can run the get command to query the specified KV pair, and the following information is displayed.

preference_kv>>> get key:name
  No data for key = name  // No value available.

The values queried with and without quotation marks are different. The following information is displayed.

preference_kv>>> put key:name1
 ...>>> value:123
preference_kv>>> put key:name2
 ...>>> value:'123'
preference_kv>>> put key:name3
 ...>>> value:true
preference_kv>>> put key:name4
 ...>>> value:'true'
preference_kv>>> get key:name1      // Result of the number without quotation marks.
type int: 123
preference_kv>>> get key:name2      // Result of the number with quotation marks.
type string: 123
preference_kv>>> get key:name3      // Result of true without quotation marks.
type bool: 1
preference_kv>>> get key:name4      // Result of true with quotation marks.
type string: true

[h2]Updating Data

At the preference_kv>>> prompt, if the specified key exists, you can run the put command to update the KV pair. The following information is displayed.

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

[h2]Deleting Data

At the preference_kv>>> prompt, you can run the delete command to delete a specified KV pair. The following information is displayed.

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

If the delete command is used without specifying a KV pair, all data in the table is deleted. The following information is displayed.

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

At the preference_kv>>> prompt, you can run the .q or .quit command to exit the database interaction mode. The following information is displayed.

preference_kv>>>.q
$

Emulator Support

This tool supports the Emulator.

FAQs

[h2]How do I delete characters?

You can press Ctrl+Backspace to delete a single character and press Ctrl+U to delete all characters.