1# Persisting KV Store Data
2
3
4## When to Use
5
6The key-value (KV) database stores data in the form of KV pairs. You can use KV stores to store data organized in a simple model, for example, product names and prices or employee IDs and daily attendance. The simple data structure allows higher compatibility with different database versions and device types.
7
8
9## Constraints
10
11- For each record in a device KV store, the key cannot exceed 896 bytes and the value cannot exceed 4 MB.
12
13- For each record in a single KV store, the key cannot exceed 1 KB and the value cannot exceed 4 MB.
14
15- A maximum of 16 distributed KV stores can be opened simultaneously for an application.
16
17- Blocking operations, for example, modifying UI components, are not allowed in the KV store event callbacks.
18
19
20## Available APIs
21
22The following table lists the APIs used for KV data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [Distributed KV Store](../reference/apis-arkdata/js-apis-distributedKVStore.md).
23
24| API| Description| 
25| -------- | -------- |
26| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.| 
27| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Obtains a KV store of the specified type.| 
28| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | Adds a KV pair of the specified type to this KV store.| 
29| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | Obtains the value of the specified key.| 
30| delete(key: string, callback: AsyncCallback<void>): void | Deletes a KV pair based on the specified key.| 
31
32
33## How to Develop
34
351. Create a **KvManager** instance to manage database objects. <br>Example:
36
37   Stage model:
38
39     
40   ```js
41   // Import the module.
42   import { distributedKVStore } from '@kit.ArkData';
43   
44   // Stage model
45   import { window } from '@kit.ArkUI';
46   import { UIAbility } from '@kit.AbilityKit';
47   import { BusinessError } from '@kit.BasicServicesKit';
48   
49   let kvManager: distributedKVStore.KVManager | undefined = undefined;
50   
51   export default class EntryAbility extends UIAbility {
52     onCreate() {
53       let context = this.context;
54       const kvManagerConfig: distributedKVStore.KVManagerConfig = {
55         context: context,
56         bundleName: 'com.example.datamanagertest'
57       };
58       try {
59         // Create a KVManager instance.
60         kvManager = distributedKVStore.createKVManager(kvManagerConfig);
61         console.info('Succeeded in creating KVManager.');
62         // Create and obtain the database.
63       } catch (e) {
64         let error = e as BusinessError;
65         console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
66       }
67     }
68   }
69   if (kvManager !== undefined) {
70      kvManager = kvManager as distributedKVStore.KVManager;
71     // Perform subsequent operations.
72     //...
73   }
74   ```
75
76   FA model:
77
78     
79   ```js
80   // Import the module.
81   import { distributedKVStore } from '@kit.ArkData';
82   
83   // FA model
84   import { featureAbility } from '@kit.AbilityKit';
85   import { BusinessError } from '@kit.BasicServicesKit';
86   
87   let kvManager: distributedKVStore.KVManager | undefined = undefined;
88   let context = featureAbility.getContext(); // Obtain the context.
89   const kvManagerConfig: distributedKVStore.KVManagerConfig = {
90     context: context,
91     bundleName: 'com.example.datamanagertest'
92   };
93   try {
94     kvManager = distributedKVStore.createKVManager(kvManagerConfig);
95     console.info('Succeeded in creating KVManager.');
96     // Create and obtain the database.
97   } catch (e) {
98      let error = e as BusinessError;
99      console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
100   }
101   if (kvManager !== undefined) {
102     kvManager = kvManager as distributedKVStore.KVManager;
103     // Perform subsequent operations.
104     //...
105   }
106
107   ```
108
1092. Create and obtain a KV store. <br>Example:
110     
111   ```js
112   let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
113   try {
114     const options: distributedKVStore.Options = {
115       createIfMissing: true,
116       encrypt: false,
117       backup: false,
118       autoSync: false,
119       // If kvStoreType is left empty, a device KV store is created by default.
120       kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
121       // Device KV store: kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
122       securityLevel: distributedKVStore.SecurityLevel.S3
123     };
124     kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
125       if (err) {
126         console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
127         return;
128       }
129       console.info('Succeeded in getting KVStore.');
130       kvStore = store;
131       // Before performing related data operations, obtain a KV store instance.
132     });
133   } catch (e) {
134     let error = e as BusinessError;
135     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
136   }
137   if (kvStore !== undefined) {
138     kvStore = kvStore as distributedKVStore.SingleKVStore;
139       // Perform subsequent operations.
140       //...
141   }
142   ```
143
1443. Use **put()** to add data to the KV store. <br>Example:
145     
146   ```js
147   const KEY_TEST_STRING_ELEMENT = 'key_test_string';
148   const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
149   try {
150     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
151       if (err !== undefined) {
152         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
153         return;
154       }
155       console.info('Succeeded in putting data.');
156     });
157   } catch (e) {
158     let error = e as BusinessError;
159     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
160   }
161   ```
162
163   > **NOTE**
164   >
165   > The **put()** method adds a KV pair if the specified key does not exists and changes the value if the the specified key already exists.
166
1674. Use **get()** to obtain the value of a key. <br>Example:
168     
169   ```js
170   try {
171     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
172       if (err !== undefined) {
173         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
174         return;
175       }
176       console.info('Succeeded in putting data.');
177       kvStore = kvStore as distributedKVStore.SingleKVStore;
178       kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
179         if (err != undefined) {
180           console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
181           return;
182         }
183         console.info(`Succeeded in getting data. Data:${data}`);
184       });
185     });
186   } catch (e) {
187     let error = e as BusinessError;
188     console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
189   }
190   ```
191
1925. Use **delete()** to delete the data of the specified key. <br>Example:
193     
194   ```js
195   try {
196     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
197       if (err !== undefined) {
198         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
199         return;
200       }
201       console.info('Succeeded in putting data.');
202       kvStore = kvStore as distributedKVStore.SingleKVStore;
203       kvStore.delete(KEY_TEST_STRING_ELEMENT, (err) => {
204         if (err !== undefined) {
205           console.error(`Failed to delete data. Code:${err.code},message:${err.message}`);
206           return;
207         }
208         console.info('Succeeded in deleting data.');
209       });
210     });
211   } catch (e) {
212     let error = e as BusinessError;
213     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
214   }
215   ```
216