README.md
1# distributeddatamgr\_appdatamgr<a name="EN-US_TOPIC_0000001124534865"></a>
2
3- [Introduction](#section11660541593)
4 - [RDB](#section1589234172717)
5 - [Preferences Database](#section1287582752719)
6
7- [Directory Structure](#section161941989596)
8- [Relational Database](#section101010894114)
9 - [Constraints](#section18387142613414)
10
11- [Preferences Database](#section762641474720)
12 - [Constraints](#section1944481420489)
13
14- [Repositories Involved](#section1371113476307)
15
16## Introduction<a name="section11660541593"></a>
17
18The **relational database \(RDB\)** manages data based on relational models. With the underlying SQLite database, the OpenHarmony RDB provides a complete mechanism for managing local databases.
19
20The **preferences database** provides lightweight key-value operations for local applications to store a small amount of data. As the stored data is already loaded in the memory, the faster data access speed achieves a higher work efficiency. The preferences database is non-relational, and therefore it is not suitable for storing a large amount of data. Instead, the preferences database is usually used to operate data in key-value pairs.
21
22### RDB<a name="section1589234172717"></a>
23
24With the SQLite database as the persistence engine, the OpenHarmony RDB supports all features of the SQLite database , including but not limited to transactions, indices, views, triggers, foreign keys, parameterized queries, and prepared SQL statements.
25
26**Figure 1** How RDB works<a name="fig3330103712254"></a>
27
28
29
30
31### Preferences Database<a name="section1287582752719"></a>
32
331. The preferences database provides operation classes for applications to operate the database.
342. With the **PreferencesHelper**, an app can load the content of a specified file to the **Preferences** instance. Each file has only one **Preferences** instance. The system stores the instance in the memory through a static container until the app removes the instance from the memory or deletes the file.
353. After obtaining the **Preferences** instance, the app can use the functions in **Preferences** to read data from or write data to the **Preferences** instance, and use **flush\(\)** or **flushSync\(\)** to save the modification to the file that stores the preference data.
36
37**Figure 2** How the preferences database works<a name="fig833053712258"></a>
38
39
40
41
42## Directory Structure<a name="section161941989596"></a>
43
44```
45//foundation/distributeddatamgr/appdatamgr
46├── frameworks # Framework code
47│ └── innerkitsimpl # Internal API implementation
48└── interfaces # APIs
49 └── innerkits # Internal APIs
50```
51
52## Relational Database<a name="section101010894114"></a>
53
54Some basic concepts are as follows:
55
56- **Relational database \(RDB\)**
57
58 A database created on the basis of relational models. The RDB stores data in rows and columns.
59
60- **Result set**
61
62 A set of query results used to access the data. You can access the required data in a result set in flexible modes.
63
64- **SQLite database**
65
66 A lightweight RDB in compliance with the atomicity, consistency, isolation, and durability \(ACID\) properties. It is an open-source database.
67
68
69### Constraints<a name="section18387142613414"></a>
70
71The RDB can use a maximum of four connection pools to manage read and write operations.
72
73To ensure data accuracy, the RDB supports only one writ operation at a time.
74
75## Preferences Database<a name="section762641474720"></a>
76
77Some basic concepts are as follows:
78
79- **Key-value database**
80
81 A database that stores data in key-value pairs. The **key** indicates keyword, and **value** indicates the corresponding value.
82
83- **Non-relational database**
84
85 A database not in compliance with the atomicity, consistency, isolation, and durability \(ACID\) database management properties of relational data transactions. Instead, the data in a non-relational database is independent and scalable.
86
87- **Preference** **data**
88
89 A type of data that is frequently accessed and used.
90
91
92### Constraints<a name="section1944481420489"></a>
93
94A key should be a string with a maximum of 80 characters and cannot be an empty string.
95
96A value in the format of string can have a maximum of 8192 characters. A value can be an empty string.
97
98To avoid a high memory cost, it is recommended that the preferences database store no more than ten thousand data entries.
99
100## Repositories Involved<a name="section1371113476307"></a>
101
102Distributed Data Management subsystem
103
104distributeddatamgr\_appdatamgr
105
106third\_party\_sqlite
107
108
README_zh.md
1# 本地数据管理组件<a name="ZH-CN_TOPIC_0000001124534865"></a>
2
3- [简介](#section11660541593)
4 - [关系型数据库（RDB）](#section1589234172717)
5 - [轻量级偏好数据库（Preferences）](#section1287582752719)
6 - [轻量系统KV数据库（Lightweight KV store）](#section1287582752720)
7- [目录](#section161941989596)
8- [关系型数据库（RDB）](#section101010894114)
9 - [约束](#section18387142613414)
10
11- [轻量级偏好数据库（Preferences）](#section762641474720)
12 - [约束](#section1944481420489)
13
14- [轻量系统KV数据库（Lightweight KV store）](#section762641474721)
15 - [约束](#section1944481420490)
16
17- [相关仓](#section1371113476307)
18
19## 简介<a name="section11660541593"></a>
20
21**关系型数据库（Relational Database，RDB）** 是一种基于关系模型来管理数据的数据库。OpenHarmony关系型数据库基于SQLite组件提供了一套完整的对本地数据库进行管理的机制。
22
23**轻量级偏好数据库（Preferences）** 主要提供轻量级Key-Value操作，支持本地应用存储少量数据，数据存储在本地文件中，同时也加载在内存中的，所以访问速度更快，效率更高。轻量级偏好数据库属于非关系型数据库，不宜存储大量数据，经常用于操作键值对形式数据的场景。
24
25**轻量系统KV数据库（Lightweight KV store）** 依托当前公共基础库提供的KV存储能力开发，为轻量系统设备应用提供键值对数据管理能力。在有进程的平台上，KV存储提供的参数管理，供单进程访问不能被其他进程使用。在此类平台上，KV存储作为基础库加载在应用进程，以保障不被其他进程访问。
26
27### 关系型数据库（RDB）<a name="section1589234172717"></a>
28
29OpenHarmony关系型数据库底层使用SQLite作为持久化存储引擎，支持SQLite具有的所有数据库特性，包括但不限于事务、索引、视图、触发器、外键、参数化查询和预编译SQL语句。
30
31**图 1** 关系型数据库运作机制<a name="fig3330103712254"></a>
32
33
34
35
36### 轻量级偏好数据库（Preferences）<a name="section1287582752719"></a>
37
381. 本模块提供偏好型数据库的操作类，应用通过这些操作类完成数据库操作。
392. 借助PreferencesHelper，可以将指定文件的内容加载到Preferences实例，每个文件最多有一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。
403. 获取Preferences实例后，可以借助Preferences类的函数，从Preferences实例中读取数据或者将数据写入Preferences实例，通过flush或者flushSync将Preferences实例持久化。
41
42**图 2** 轻量级偏好数据库运行机制<a name="fig833053712258"></a>
43
44
45
46
47### 轻量系统KV数据库（Lightweight KV store）<a name="section1287582752720"></a>
48
49> 当前先支持轻量键值（KV）本地数据存储能力，后续会逐步支持其他更丰富的数据类型。
50>
51> 轻量键值（KV）数据：数据有结构，文件轻量，具有简易事务性，单独提供一套专用的键值对接口
52
53分布式数据管理服务在不同平台上，将数据操作接口形成抽象层用来统一进行文件操作，使厂商不需要关注不同芯片平台文件系统的差异。
54
55**目前，在轻量系统上默认关闭该特性，需要使用时请用户修改vendor_hisilicon仓配置以开启。**
56
57## 目录<a name="section161941989596"></a>
58
59```
60//foundation/distributeddatamgr/appdatamgr
61├── frameworks # 框架层代码
62│ └── innerkitsimpl # 内部接口实现
63└── interfaces # 接口代码
64 └── innerkits # 内部接口声明
65```
66
67## 关系型数据库（RDB）<a name="section101010894114"></a>
68
69以下是几个基本概念：
70
71- **关系型数据库**
72
73 创建在关系模型基础上的数据库，以行和列的形式存储数据。
74
75- **结果集**
76
77 指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便的拿到用户想要的数据。
78
79- **SQLite数据库**
80
81 一款轻量级的数据库，是遵守ACID的关系型数据库组件。它是一个开源的项目。
82
83
84### 约束<a name="section18387142613414"></a>
85
86数据库中连接池的最大数量是4个，用以管理用户的读写操作。
87
88为保证数据的准确性，数据库同一时间只能支持一个写操作。
89
90## 轻量级偏好数据库（Preferences）<a name="section762641474720"></a>
91
92以下是几个基本概念：
93
94- **Key-Value数据库**
95
96 一种以键值对存储数据的一种数据库。Key是关键字，Value是值。
97
98- **非关系型数据库**
99
100 区别于关系数据库，不保证遵循ACID（Atomic、Consistency、Isolation及Durability）特性，不采用关系模型来组织数据，数据之间无关系，扩展性好。
101
102- **偏好数据**
103
104 用户经常访问和使用的数据。
105
106
107### 约束<a name="section1944481420489"></a>
108
109Key键为String类型，要求非空且长度不超过80个字符。
110
111如果Value值为String类型，可以为空但是长度不超过8192个字符。
112
113存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销。
114
115## 轻量系统KV数据库（Lightweight KV store）<a name="section762641474721"></a>
116
117### 说明
118
119KV存储能力继承自公共基础库原始设计，在原有能力基础上进行增强，新增提供数据删除及二进制value读写能力的同时，保证操作的原子性；
120
121>- 轻量系统普遍性能有限，内存及计算能力不足，对于数据管理的场景大多读多写少，且内存占用敏感；
122>- 平台使用的文件操作接口是由文件系统提供，一般来说文件操作接口本身并不是进程安全的，请格外注意；
123>- 轻量系统，存在不具备锁能力的情况，不提供锁的机制，并发由业务保证，若需要提供有锁机制，则需要提供hook，由业务进行注册。
124### 约束<a name="section1944481420490"></a>
125
126- KV大小及可存储条目数在平台可承受内可修改配置，轻量系统默认为小于Key(32byte)，Value(512byte)，通过修改编译宏修改；
127
128- 依赖平台具有正常的文件创建、读写删除修改、锁等能力，针对不同平台（如LiteOS-M内核、LiteOS-A内核等）尽可能表现接口语义功能的不变；
129
130- 由于平台能力差异数据库能力需要做相应裁剪，其中不同平台内部实现可能不同；
131
132- 对于指定路径仅支持创建数据库单例，不支持同一路径创建多数据库实例对象。
133
134## 相关仓<a name="section1371113476307"></a>
135
136分布式数据管理子系统
137
138distributeddatamgr\_appdatamgr
139
140third\_party\_sqlite
