@capgo/capacitor-data-storage-sqlite

Store key and value strings in SQLite from your Capacitor app, with multiple stores and tables and optional encryption on iOS and Android. A simple, persistent alternative to localStorage.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-data-storage-sqlite in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-data-storage-sqlite to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Key value API: set(), get(), remove(), clear(), iskey(), keys(), values() and keysvalues().
• Stores and tables: openStore(), setTable(), tables(), deleteTable() and deleteStore().
• Encryption: optional encrypted stores on iOS and Android via SQLCipher.
• JSON import and export: importFromJson(), isJsonValid() and exportToJson().
• Filtering: filtervalues() returns values for keys that match a filter.
• Platforms: iOS, Android and Web. Web stores data in the browser with the same key value API.

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

Perfect for apps needing simple, reliable local storage without complex SQL queries.

Maintainers

Browser Support

The plugin follows the guidelines from the Capacitor Team,

• Capacitor Browser Support

meaning that it will not work in IE11 without additional JavaScript transformations, e.g. with Babel.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/data-storage-sqlite/

Compatibility

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-plugins

Then 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/electron

Go to the Electron folder of your application

cd electron
npm install --save sqlite3
npm install --save-dev @types/sqlite3
npm run build
cd ..
npx cap sync @capacitor-community/electron

Then 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 serve

Configuration

No configuration required for this plugin

Supported methods

Documentation

• API_Documentation

• USAGE_Documentation

Applications demonstrating the use of the plugin

Ionic/Angular

• angular-data-storage-sqlite-app-starter

Ionic/React

• react-data-storage-sqlite-app-starter

React

• react-datastoragesqlite-app

Ionic/Vue

• vue-data-storage-sqlite-app-starter

Vue

• vue-datastoragesqlite-app

Usage

• see capacitor documentation

• see USAGE_Documentation

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

Avoid editing those files directly; they are overwritten on install. Prefer 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

Since: 0.0.1

closeStore(...)

closeStore(options: capStorageOptions) => Promise<void>

Close the Store

Since: 3.0.0

isStoreOpen(...)

isStoreOpen(options: capStorageOptions) => Promise<capDataStorageResult>

Check if the Store is opened

Returns: Promise<capDataStorageResult>

Since: 3.0.0

isStoreExists(...)

isStoreExists(options: capStorageOptions) => Promise<capDataStorageResult>

Check if the Store exists

Returns: Promise<capDataStorageResult>

Since: 3.0.0

deleteStore(...)

deleteStore(options: capOpenStorageOptions) => Promise<void>

Delete a store

Since: 0.0.1

setTable(...)

setTable(options: capTableStorageOptions) => Promise<void>

Set or Add a table to an existing store

Since: 0.0.1

set(...)

set(options: capDataStorageOptions) => Promise<void>

Store a data with given key and value

Since: 0.0.1

get(...)

get(options: capDataStorageOptions) => Promise<capValueResult>

Retrieve a data value for a given data key

Returns: Promise<capValueResult>

Since: 0.0.1

remove(...)

remove(options: capDataStorageOptions) => Promise<void>

Remove a data with given key

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

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

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

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

Since: 3.0.0

importFromJson(...)

importFromJson(options: capStoreImportOptions) => Promise<capDataStorageChanges>

Import a database From a JSON

Returns: Promise<capDataStorageChanges>

Since: 3.2.0

isJsonValid(...)

isJsonValid(options: capStoreImportOptions) => Promise<capDataStorageResult>

Check the validity of a JSON Object

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

capStorageOptions

capDataStorageResult

capTableStorageOptions

capDataStorageOptions

capValueResult

capKeysResult

capValuesResult

capFilterStorageOptions

capKeysValuesResult

capTablesResult

capDataStorageChanges

capStoreImportOptions

capStoreJson

JsonStore

JsonTable

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 <--