API DOCUMENTATION

capacitor-data-storage-sqlite

CAPACITOR 3

Capacitor Data Storage SQlite Plugin is a custom Native Capacitor plugin providing a key-value permanent store for simple data of type string only to SQLite on IOS, Android and Electron platforms and to IndexDB for the Web platform.

To store `JSON object`, you should manage conversion through `JSON.stringify` before storing and `JSON.parse` when retrieving the data To store `number`, use the same procedure, with `number.toString()` and `Number()`. For both IOS and Android platforms, the store can be encrypted. The plugin uses SQLCipher for encryption with a `passphrase`. ## Databases Location ### Android in **data/data/YOUR_PACKAGE/databases** ### IOS in **the Document folder of YOUR_APPLICATION** ### Electron in **YourApplication/Electron/Databases** ## Methods Index * [`echo(...)`](#echo) * [`openStore(...)`](#openstore) * [`closeStore(...)`](#closestore) * [`isStoreOpen(...)`](#isstoreopen) * [`isStoreExists(...)`](#isstoreexists) * [`deleteStore(...)`](#deletestore) * [`setTable(...)`](#settable) * [`set(...)`](#set) * [`get(...)`](#get) * [`remove(...)`](#remove) * [`clear()`](#clear) * [`iskey(...)`](#iskey) * [`keys()`](#keys) * [`values()`](#values) * [`filtervalues(...)`](#filtervalues) * [`keysvalues()`](#keysvalues) * [`isTable(...)`](#istable) * [`tables()`](#tables) * [`deleteTable(...)`](#deletetable) * [`importFromJson(...)`](#importfromjson) * [`isJsonValid(...)`](#isjsonvalid) * [`exportToJson()`](#exporttojson) * [Interfaces](#interfaces) ## API ### openStore(...) ```typescript openStore(options: capOpenStorageOptions) => Promise ``` Open a store | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capOpenStorageOptions | : capOpenStorageOptions | **Since:** 0.0.1 -------------------- ### closeStore(...) ```typescript closeStore(options: capStorageOptions) => Promise ``` Close the Store | Param | Type | Description | | ------------- | --------------------------------------------------------------- | ---------------------------------------------------- | | **`options`** | capStorageOptions | : capStorageOptions | **Since:** 3.0.0 -------------------- ### isStoreOpen(...) ```typescript isStoreOpen(options: capStorageOptions) => Promise ``` Check if the Store is opened | Param | Type | Description | | ------------- | --------------------------------------------------------------- | ---------------------------------------------------- | | **`options`** | capStorageOptions | : capStorageOptions | **Returns:** Promise<capDataStorageResult> **Since:** 3.0.0 -------------------- ### isStoreExists(...) ```typescript isStoreExists(options: capStorageOptions) => Promise ``` Check if the Store exists | Param | Type | Description | | ------------- | --------------------------------------------------------------- | ---------------------------------------------------- | | **`options`** | capStorageOptions | : capStorageOptions | **Returns:** Promise<capDataStorageResult> **Since:** 3.0.0 -------------------- ### deleteStore(...) ```typescript deleteStore(options: capOpenStorageOptions) => Promise ``` Delete a store | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capOpenStorageOptions | : capOpenStorageOptions | **Since:** 0.0.1 -------------------- ### setTable(...) ```typescript setTable(options: capTableStorageOptions) => Promise ``` Set or Add a table to an existing store | Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | | **`options`** | capTableStorageOptions | : capTableStorageOptions | **Since:** 0.0.1 -------------------- ### set(...) ```typescript set(options: capDataStorageOptions) => Promise ``` Store a data with given key and value | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capDataStorageOptions | : capDataStorageOptions | **Since:** 0.0.1 -------------------- ### get(...) ```typescript get(options: capDataStorageOptions) => Promise ``` Retrieve a data value for a given data key | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capDataStorageOptions | : capDataStorageOptions | **Returns:** Promise<capValueResult> **Since:** 0.0.1 -------------------- ### remove(...) ```typescript remove(options: capDataStorageOptions) => Promise ``` Remove a data with given key | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capDataStorageOptions | : capDataStorageOptions | **Since:** 0.0.1 -------------------- ### clear() ```typescript clear() => Promise ``` Clear the Data Store (delete all keys) **Since:** 0.0.1 -------------------- ### iskey(...) ```typescript iskey(options: capDataStorageOptions) => Promise ``` Check if a data key exists | Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | **`options`** | capDataStorageOptions | : capDataStorageOptions | **Returns:** Promise<capDataStorageResult> **Since:** 0.0.1 -------------------- ### keys() ```typescript keys() => Promise ``` Get the data key list **Returns:** Promise<capKeysResult> **Since:** 0.0.1 -------------------- ### values() ```typescript values() => Promise ``` Get the data value list **Returns:** Promise<capValuesResult> **Since:** 0.0.1 -------------------- ### filtervalues(...) ```typescript filtervalues(options: capFilterStorageOptions) => Promise ``` Get the data value list for filter keys | Param | Type | Description | | ------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **`options`** | capFilterStorageOptions | : capFilterStorageOptions | **Returns:** Promise<capValuesResult> **Since:** 2.4.2 -------------------- ### keysvalues() ```typescript keysvalues() => Promise ``` Get the data key/value pair list **Returns:** Promise<capKeysValuesResult> **Since:** 0.0.1 -------------------- ### isTable(...) ```typescript isTable(options: capTableStorageOptions) => Promise ``` Check if a table exists | Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | | **`options`** | capTableStorageOptions | : capTableStorageOptions | **Returns:** Promise<capDataStorageResult> **Since:** 3.0.0 -------------------- ### tables() ```typescript tables() => Promise ``` Get the table list for the current store **Returns:** Promise<capTablesResult> **Since:** 3.0.0 -------------------- ### deleteTable(...) ```typescript deleteTable(options: capTableStorageOptions) => Promise ``` Delete a table | Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | | **`options`** | capTableStorageOptions | : capTableStorageOptions | **Since:** 3.0.0 -------------------- ### importFromJson(...) ```typescript importFromJson(options: capStoreImportOptions) => Promise ``` Import a database From a JSON | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | capStoreImportOptions | **Returns:** Promise<capDataStorageChanges> **Since:** 3.2.0 -------------------- ### isJsonValid(...) ```typescript isJsonValid(options: capStoreImportOptions) => Promise ``` Check the validity of a JSON Object | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | capStoreImportOptions | **Returns:** Promise<capDataStorageResult> **Since:** 3.2.0 -------------------- ### exportToJson() ```typescript exportToJson() => Promise ``` Export the given database to a JSON Object **Returns:** Promise<capStoreJson> **Since:** 3.2.0 -------------------- ### Interfaces #### capEchoResult | Prop | Type | Description | | ----------- | ------------------- | --------------- | | **`value`** | string | String returned | #### capEchoOptions | Prop | Type | Description | | ----------- | ------------------- | ------------------- | | **`value`** | string | String to be echoed | #### capOpenStorageOptions | Prop | Type | Description | | --------------- | -------------------- | --------------------------------------------------------------------------- | | **`database`** | string | The storage database name | | **`table`** | string | The storage table name | | **`encrypted`** | boolean | Set to true for database encryption | | **`mode`** | string | * Set the mode for database encryption ["encryption", "secret","newsecret"] | #### capStorageOptions | Prop | Type | Description | | -------------- | ------------------- | ---------------- | | **`database`** | string | The storage name | #### capDataStorageResult | Prop | Type | Description | | ------------- | -------------------- | --------------------------------------------- | | **`result`** | boolean | result set to true when successful else false | | **`message`** | string | a returned message | #### capTableStorageOptions | Prop | Type | Description | | ----------- | ------------------- | ---------------------- | | **`table`** | string | The storage table name | #### capDataStorageOptions | Prop | Type | Description | | ----------- | ------------------- | ---------------------------- | | **`key`** | string | The data name | | **`value`** | string | The data value when required | #### capValueResult | Prop | Type | Description | | ----------- | ------------------- | ----------------------------------- | | **`value`** | string | the data value for a given data key | #### capKeysResult | Prop | Type | Description | | ---------- | --------------------- | ----------------------------- | | **`keys`** | string[] | the data key list as an Array | #### capValuesResult | Prop | Type | Description | | ------------ | --------------------- | -------------------------------- | | **`values`** | string[] | the data values list as an Array | #### capFilterStorageOptions | Prop | Type | Description | | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **`filter`** | string | The filter data for filtering keys ['%filter', 'filter', 'filter%'] for [starts with filter, contains filter, ends with filter] | #### capKeysValuesResult | Prop | Type | Description | | ---------------- | ------------------ | ------------------------------------------------------------------ | | **`keysvalues`** | any[] | the data keys/values list as an Array of {key:string,value:string} | #### capTablesResult | Prop | Type | Description | | ------------ | --------------------- | --------------------------- | | **`tables`** | string[] | the tables list as an Array | #### capDataStorageChanges | Prop | Type | Description | | ------------- | ------------------- | ---------------------------------------------------- | | **`changes`** | number | the number of changes from an importFromJson command | #### capStoreImportOptions | Prop | Type | Description | | ---------------- | ------------------- | ----------------------------- | | **`jsonstring`** | string | Set the JSON object to import | #### capStoreJson | Prop | Type | Description | | ------------ | ----------------------------------------------- | --------------------- | | **`export`** | JsonStore | an export JSON object | #### JsonStore | Prop | Type | Description | | --------------- | ------------------------ | ------------------------------------------------------------ | | **`database`** | string | The database name | | **`encrypted`** | boolean | Set to true (database encryption) / false iOS & Android only | | **`tables`** | JsonTable[] | * Array of Table (JsonTable) | #### JsonTable | Prop | Type | Description | | ------------ | ------------------------------------ | ------------------------------------------------------------------------------ | | **`name`** | string | The database name | | **`values`** | capDataStorageOptions[] | * Array of Values (capDataStorageOptions) | ## Encrypted DataStore ### Existing Datastore encryption use the `openStore` method with the following options: ``` { database:"fooDB", table:"fooTable", encrypted:true, mode:"encryption" } ``` The existing datastore will be encrypted with a secret key and opens with given database and table names. To define your own `secret` and `newsecret` passphrases (Capacitor CLI apps): **Recommended:** set them in `capacitor.config.ts` under `plugins.CapgoCapacitorDataStorageSqlite`: ```ts plugins: { CapgoCapacitorDataStorageSqlite: { encryptionSecret: 'my-production-passphrase', encryptionNewSecret: 'my-next-passphrase', }, }, ``` Run `npx cap sync` after changing config. Use `mode: "secret"` or `mode: "encryption"` with `encryptionSecret`, and `mode: "newsecret"` to rekey to `encryptionNewSecret`. **Defaults in the plugin package** (do not edit in `node_modules`; values reset on install): - iOS: `@capgo/capacitor-data-storage-sqlite` → `ios/Sources/CapgoCapacitorDataStorageSqlitePlugin/Global.swift` - Android: `@capgo/capacitor-data-storage-sqlite` → `android/src/main/java/com/jeep/plugin/capacitor/capgocapacitordatastoragesqlite/cdssUtils/Global.java` ### Create a New Encrypted Datastore use the `openStore` method with the following options: ``` { database:"fooDB", table:"fooTable", encrypted:true, mode:"secret" } ``` The Datastore will be encrypted and opens with given database and table names and the secret key stored in your application. ### Change the Secret of an Existing Encrypted Datastore use the `openStore` method with the following options: ``` { database:"fooDB", table:"fooTable", encrypted:true, mode:"newsecret" } ``` The secret key of the encrypted datastore will be modified with the newsecret key stored in your application and the datastore will be opened with given database and table names and newsecret key. Do not forget after this change of secret to go in the code of your app and modified in the `Global`file the `secret` parameter with the value of the `newsecret` parameter and reassign a new value of your choice to the `newsecret` parameter, before the relauch of your app.