➡️ Get Instant updates for your App with Capgo 🚀
Fix your annoying bug now, Hire a Capacitor expert 💪
DATA STORAGE SQLITE
@capgo/capacitor-data-storage-sqlite
CAPACITOR 6
Note from the Owner
This Plugin has been transferred to Capgo org after his original creator @jepiqueau decide to retire.
We will forever be thankful for the work he did.
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.
Why Data Storage SQLite?
A maintained, community-driven plugin providing simple key-value storage backed by SQLite. Originally created by @jepiqueau and now maintained by Capgo:
- Simple API - Easy key-value storage interface for string data
- Cross-platform - Works on iOS, Android, Electron, and Web (IndexedDB)
- SQLite backing - Reliable, encrypted storage on native platforms
- Import/Export - JSON import/export for data migration
- Multi-table support - Organize data across multiple tables
Maintainers
| Maintainer | GitHub | Social | | ----------------- | ----------------------------------------- | ------ | | Martin Donadieu | riderx | | | Quéau Jean Pierre | jepiqueau | |
Browser Support
The plugin follows the guidelines from the Capacitor Team,
Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/data-storage-sqlite/
Compatibility
| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.\.\ | v8.\.\ | ✅ | | v7.\.\ | v7.\.\ | On demand | | v6.\.\ | v6.\.\ | ❌ | | v5.\.\ | v5.\.\ | ❌ |
Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
Installation
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-pluginsThen use the following prompt:
Use the capacitor-plugins skill from cap-go/capacitor-skills to install the @capgo/capacitor-data-storage-sqlite plugin in my project.If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
npm install --save @capgo/capacitor-data-storage-sqlite
npx cap sync- On iOS, no further steps are needed.
- On Android, no further steps are needed.
- On Web,
npm install --save localforage- On Electron
npm install --save @capacitor-community/electron
npx cap add @capacitor-community/electroncd electron
npm install --save sqlite3
npm install --save-dev @types/sqlite3
npm run build
cd ..
npx cap sync @capacitor-community/electronThen build YOUR_APPLICATION
npm run build
npx cap copy
npx cap copy @capacitor-community/electron
npx cap open ios
npx cap open android
npx cap open @capacitor-community/electron
ionic serveConfiguration
No configuration required for this plugin
Supported methods
| Name | Android | iOS | Electron | Web | | :--------------------------- | :------ | :-- | :------- | :-- | | openStore (non-encrypted DB) | ✅ | ✅ | ✅ | ✅ | | openStore (encrypted DB) | ✅ | ✅ | ❌ | ❌ | | closeStore | ✅ | ✅ | ✅ | ❌ | | isStoreOpen | ✅ | ✅ | ✅ | ❌ | | isStoreExists | ✅ | ✅ | ✅ | ❌ | | deleteStore | ✅ | ✅ | ✅ | ❌ | | setTable | ✅ | ✅ | ✅ | ✅ | | set | ✅ | ✅ | ✅ | ✅ | | get | ✅ | ✅ | ✅ | ✅ | | iskey | ✅ | ✅ | ✅ | ✅ | | keys | ✅ | ✅ | ✅ | ✅ | | values | ✅ | ✅ | ✅ | ✅ | | filtervalues | ✅ | ✅ | ✅ | ✅ | | keysvalues | ✅ | ✅ | ✅ | ✅ | | remove | ✅ | ✅ | ✅ | ✅ | | clear | ✅ | ✅ | ✅ | ✅ | | isTable | ✅ | ✅ | ✅ | ✅ | | tables | ✅ | ✅ | ✅ | ✅ | | deleteTable | ✅ | ✅ | ✅ | ❌ | | isJsonValid | ✅ | ✅ | ✅ | ✅ | | importFromJson | ✅ | ✅ | ✅ | ✅ | | exportToJson | ✅ | ✅ | ✅ | ✅ |
Documentation
Applications demonstrating the use of the plugin
Ionic/Angular
Ionic/React
React
Ionic/Vue
Vue
Usage
Dependencies
The IOS & Android code use SQLCipher allowing for database encryption.
The Android code is now based on androidx.sqlite. The database is not closed anymore after each transaction for performance improvement.
You must manage the close of the database before opening a new database.
The Web code use localforage package to store the datastore in the Browser.
The Electron code use sqlite3package
Database encryption passphrases
On iOS and Android, encrypted stores use SQLCipher passphrases from the plugin Global defaults (test secret / test new secret) unless you configure your own.
Recommended (Capacitor CLI apps): set passphrases in capacitor.config.ts so they are not patched inside node_modules:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
CapgoCapacitorDataStorageSqlite: {
encryptionSecret: 'my-production-passphrase',
encryptionNewSecret: 'my-next-passphrase',
},
},
};
export default config;
Then use openStore with encrypted: true and mode set to secret, encryption, or newsecret as described in the API docs.
Advanced: the built-in defaults live in the plugin package (not in your android/ app tree):
- Android:
node_modules/@capgo/capacitor-data-storage-sqlite/android/src/main/java/com/jeep/plugin/capacitor/capgocapacitordatastoragesqlite/cdssUtils/Global.java - iOS:
node_modules/@capgo/capacitor-data-storage-sqlite/ios/Sources/CapgoCapacitorDataStorageSqlitePlugin/Global.swift
capacitor.config or a fork of the plugin.
To open an encrypted .db in a desktop SQLCipher tool, use the same passphrase you configured as encryptionSecret (or the current secret after a newsecret rekey).
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Jean Pierre Quéau 💻 |
 Matthew Burke 📖 |
 Kevin van Schaijk 💻 |
 Andy Garbett 📖 |
openStore(...)closeStore(...)isStoreOpen(...)isStoreExists(...)deleteStore(...)setTable(...)set(...)get(...)remove(...)clear()iskey(...)keys()values()filtervalues(...)keysvalues()isTable(...)tables()deleteTable(...)importFromJson(...)isJsonValid(...)exportToJson()vacuum()getPluginVersion()- Interfaces
- Type Aliases
openStore(...)
openStore(options: capOpenStorageOptions) => Promise<void>Open a store
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capOpenStorageOptions | : capOpenStorageOptions |
Since: 0.0.1
--------------------
closeStore(...)
closeStore(options: capStorageOptions) => Promise<void>Close the Store
| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| options | capStorageOptions | : capStorageOptions |
Since: 3.0.0
--------------------
isStoreOpen(...)
isStoreOpen(options: capStorageOptions) => Promise<capDataStorageResult>Check if the Store is opened
| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| options | capStorageOptions | : capStorageOptions |
Returns: Promise<capDataStorageResult>
Since: 3.0.0
--------------------
isStoreExists(...)
isStoreExists(options: capStorageOptions) => Promise<capDataStorageResult>Check if the Store exists
| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| options | capStorageOptions | : capStorageOptions |
Returns: Promise<capDataStorageResult>
Since: 3.0.0
--------------------
deleteStore(...)
deleteStore(options: capOpenStorageOptions) => Promise<void>Delete a store
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capOpenStorageOptions | : capOpenStorageOptions |
Since: 0.0.1
--------------------
setTable(...)
setTable(options: capTableStorageOptions) => Promise<void>Set or Add a table to an existing store
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| options | capTableStorageOptions | : capTableStorageOptions |
Since: 0.0.1
--------------------
set(...)
set(options: capDataStorageOptions) => Promise<void>Store a data with given key and value
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capDataStorageOptions | : capDataStorageOptions |
Since: 0.0.1
--------------------
get(...)
get(options: capDataStorageOptions) => Promise<capValueResult>Retrieve a data value for a given data key
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capDataStorageOptions | : capDataStorageOptions |
Returns: Promise<capValueResult>
Since: 0.0.1
--------------------
remove(...)
remove(options: capDataStorageOptions) => Promise<void>Remove a data with given key
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capDataStorageOptions | : capDataStorageOptions |
Since: 0.0.1
--------------------
clear()
clear() => Promise<void>Clear the Data Store (delete all keys)
Since: 0.0.1
--------------------
iskey(...)
iskey(options: capDataStorageOptions) => Promise<capDataStorageResult>Check if a data key exists
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| options | capDataStorageOptions | : capDataStorageOptions |
Returns: Promise<capDataStorageResult>
Since: 0.0.1
--------------------
keys()
keys() => Promise<capKeysResult>Get the data key list
Returns: Promise<capKeysResult>
Since: 0.0.1
--------------------
values()
values() => Promise<capValuesResult>Get the data value list
Returns: Promise<capValuesResult>
Since: 0.0.1
--------------------
filtervalues(...)
filtervalues(options: capFilterStorageOptions) => Promise<capValuesResult>Get the data value list for filter keys
| Param | Type | Description |
| ------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| options | capFilterStorageOptions | : capFilterStorageOptions |
Returns: Promise<capValuesResult>
Since: 2.4.2
--------------------
keysvalues()
keysvalues() => Promise<capKeysValuesResult>Get the data key/value pair list
Returns: Promise<capKeysValuesResult>
Since: 0.0.1
--------------------
isTable(...)
isTable(options: capTableStorageOptions) => Promise<capDataStorageResult>Check if a table exists
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| options | capTableStorageOptions | : capTableStorageOptions |
Returns: Promise<capDataStorageResult>
Since: 3.0.0
--------------------
tables()
tables() => Promise<capTablesResult>Get the table list for the current store
Returns: Promise<capTablesResult>
Since: 3.0.0
--------------------
deleteTable(...)
deleteTable(options: capTableStorageOptions) => Promise<void>Delete a table
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| options | capTableStorageOptions | : capTableStorageOptions |
Since: 3.0.0
--------------------
importFromJson(...)
importFromJson(options: capStoreImportOptions) => Promise<capDataStorageChanges>Import a database From a JSON
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | capStoreImportOptions |
Returns: Promise<capDataStorageChanges>
Since: 3.2.0
--------------------
isJsonValid(...)
isJsonValid(options: capStoreImportOptions) => Promise<capDataStorageResult>Check the validity of a JSON Object
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | capStoreImportOptions |
Returns: Promise<capDataStorageResult>
Since: 3.2.0
--------------------
exportToJson()
exportToJson() => Promise<capStoreJson>Export the given database to a JSON Object
Returns: Promise<capStoreJson>
Since: 3.2.0
--------------------
vacuum()
vacuum() => Promise<void>Rebuild the current SQLite store to reclaim unused disk space.
Since: 8.0.32
--------------------
getPluginVersion()
getPluginVersion() => Promise<{ version: string; }>Get the native Capacitor plugin version
Returns: Promise<{ version: string; }>
--------------------
Interfaces
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 on iOS and Android. - encryption — encrypt an existing plaintext database with the configured passphrase - secret — open or create an encrypted database with the configured passphrase - newsecret — rekey an encrypted database from encryptionSecret to encryptionNewSecret Passphrases are set in capacitor.config under plugins.CapgoCapacitorDataStorageSqlite (see {@link CapgoCapacitorDataStorageSqliteConfig}). Defaults are defined in the plugin's Global sources if you do not configure them. |
| autoVacuum | capSQLiteAutoVacuum | Set the SQLite auto_vacuum mode for the store. Use none/0, full/1, or incremental/2. iOS, Android, and Electron only. Web ignores this option. |
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) |
Type Aliases
capSQLiteAutoVacuum
'none' | 'full' | 'incremental' | 0 | 1 | 2
This project follows the all-contributors specification. Contributions of any kind welcome!
Retirement message of @jepiqueau -->
I have been dedicated to developing and maintaining this plugin for many years since the inception of Ionic Capacitor. Now, at 73+ years old, and with my MacBook Pro becoming obsolete for running Capacitor 6 for iOS, I have made the decision to cease maintenance of the plugin. If anyone wishes to take ownership of this plugin, they are welcome to do so.
It has been a great honor to be part of this development journey alongside the developer community. I am grateful to see many of you following me on this path and incorporating the plugin into your applications. Your comments and suggestions have motivated me to continuously improve it.
I have made this decision due to several family-related troubles that require my full attention and time. Therefore, I will not be stepping back. Thank you to all of you for your support.
End <--