Problem Description
PersistentStorage, user preferences (Preferences), key-value database (KV-Store), and relational database (RelationalStore) are all mechanisms for persistent data storage, but their applicable scenarios and characteristics vary. How should users choose when using them?
Background knowledge
PersistentStorage : Persistently stores UI state, usually used in conjunction with AppStorage. Select AppStorage to write data stored in the disk to ensure that the values of these properties when the application is restarted are the same as when the application is closed.
Application data persistence: refers to the application saving the data in the memory to the device in the form of files or databases. The data form in the memory is usually any data structure or data object, and the data form on the storage medium may be text, database, binary file, etc. The HarmonyOS standard system supports typical storage data forms, including user preferences (Preferences) , key-value database (KV-Store) , and relational database (RelationalStore) .
Troubleshooting Process
- Reviewed HarmonyOS official documentation for each storage mechanism: PersistentStorage, Preferences, KV-Store, and RelationalStore.
- Compared their purpose, applicable scenarios, limitations, and encryption support.
- Identified the main confusion: users often do not know when to use lightweight options (PersistentStorage / Preferences) versus structured databases (KV-Store / RelationalStore).
- Analyzed performance and restriction notes, such as UI thread blocking risks in PersistentStorage, lack of multi-process safety in Preferences, record size limits in KV-Store, and single-write restrictions in RelationalStore.
Analysis Conclusion
- PersistentStorage is best for UI state persistence only, lightweight (<2KB).
- Preferences suits application configuration / user settings (≤50MB, single process).
- KV-Store is designed for non-relational structured data (distributed or single-device, key-value pairs).
- RelationalStore is required for complex relational data where entities have multiple fields and relationships.
- Choosing the wrong mechanism may cause performance degradation (e.g., freezing UI), data corruption, or unnecessary complexity.
Solution
PersistentStorage, user preferences (Preferences), key-value database (KV-Store), relational database (RelationalStore) are applicable to the following scenarios:
| PersistentStorage | User Preferences | Key-Value Database (KV-Store) | Relational Store | |
|---|---|---|---|---|
| Introduce | PersistentStorage persists the UI state and is usually used in conjunction with AppStorage. The data stored in AppStorage is written to disk to ensure that the values of these properties when the application is restarted are the same as when the application was closed. | Preferences is a lightweight database for storing application settings. It provides a simple mechanism for storing and retrieving application configuration information, typically stored as key-value pairs. Preferences data is stored synchronously and is suitable for storing small amounts of structured data. | A non-relational database in which data is organized, indexed, and stored as key-value pairs, where the key serves as a unique identifier. | The relational database is based on the SQLite component and is suitable for storing scenarios containing complex relational data. |
| Applicable Scenarios | ① Applications that need to persist UI state. ② Require persistence after initialization of a UI instance. ③ Expect to restore the last state when the application is restarted after being closed. | ① Need to store application configuration information. ② Need to support fast data read and write. ③ Want to share data between different parts of the application. ④ The application needs to save user personalized settings (font size, whether to enable night mode). | The stored data does not have a complex relational model, such as storing product names and corresponding prices, employee IDs, and whether the employee has been present today. | Scenarios where there is a strong correspondence between data. For example, the student information of a class needs to include name, student ID, grades in various subjects, etc.; the employee information of a company needs to include name, work ID, position, etc. |
| Whether encryption is supported | Not supported. | Supported, refer to the database encryption document | Supported, refer to the database encryption document | |
| Restrictions | ① Nested objects (arrays of objects, object properties that are objects, etc.) are not supported. ② PersistentStorage is suitable for storing lightweight data (<2KB). Its synchronous write-to-disk mechanism can affect UI thread performance. When storing large amounts of data, database APIs should be used instead to avoid interface rendering lags. For more details, refer to the official documentation | ① Preferences cannot guarantee multi-process concurrency security and can easily lead to data corruption. Multi-process use is not supported. ② Keys must be of string type, non-null, and ≤1024 bytes in length. ③ Values of string type must be encoded in UTF-8, can be null, and must not exceed 16MB in length when non-null. ③ Memory usage increases with data volume. We recommend storing lightweight data ≤50MB. Synchronizing and persisting large data can easily cause main thread lag and app freeze issues. For more details, please refer to the official documentation | ① For device-collaborative databases, for each record, the key length is ≤ 896 bytes, and the value length is < 4 MB. ② For single-version databases, for each record, the key length is ≤ 1 KB, and the value length is < 4 MB. ③ Each application supports a maximum of 16 key-value distributed databases open simultaneously. ④ Blocking operations, such as modifying UI components, are not allowed in key-value database event callback methods. For more details, please refer to the official documentation | ① To ensure data accuracy, the database can only support one write operation at a time. ② To ensure successful data insertion and reading, it is recommended that each data entry be no larger than 2MB. If this size is exceeded, insertion will succeed but reading will fail. ③ When the app is uninstalled, the relevant database files and temporary files on the device will be automatically cleared. For more details, ple |
Top comments (0)