Capacitor SQLite puts a native, encryptable database inside a Capacitor app

One SQLite engine across iOS, Android, Electron and the browser

Capacitor applications are web applications that run inside a native shell, and that creates a familiar problem. The database you use in the browser is not the database you use on a device, so any data logic ends up written twice or abstracted into a layer that is only as good as its lowest platform. This plugin attacks that by giving the same SQLite API on all four targets. The repository layout reflects that scope, with an android directory, an ios directory, an electron directory and a src directory for the TypeScript layer, and a Package.swift alongside a CapacitorCommunitySqlite.podspec for the Apple side. The plugin API is published as @capacitor-community/sqlite and the package metadata shows a main entry of dist/plugin.cjs.js, an ESM module entry and an unpkg build, so the same package serves a bundler, a native build and a browser. The intended user is a mobile developer who wants a real relational store on device without maintaining a parallel web implementation.

Encryption is SQLCipher on native and multiple ciphers on Electron

The README states the encryption story in one line: in Native, databases could be encrypted with SQLCipher, and in Electron, databases could be encrypted with better-sqlite3-multiple-ciphers. The difference is not cosmetic. SQLCipher is a SQLite fork that adds encryption at the page level, and on iOS and Android the plugin drives the native library, so a database file on disk is ciphertext rather than a plain SQLite file that any tool can open. On Electron, where the database lives in a Node process, the plugin goes through better-sqlite3-multiple-ciphers instead. The configuration keys follow the same split, with iosIsEncryption, androidIsEncryption and electronIsEncryption in the plugin configuration, and separate location keys for each platform, iosDatabaseLocation, electronWindowsLocation, electronMacLocation and electronLinuxLocation. Two of those example values are worth a second look before shipping, since the example values point at a Windows ProgramData path and a macOS volume path that belongs to the machine that wrote the sample.

The plugin links SQLCipher even when you do not encrypt anything

This is the warning block, and it deserves attention before the install command is copied anywhere. The README says the plugin uses the SQLCipher library even for unencrypted databases, and that this is subject to the encryption export regulations, with a link to Apple's documentation on complying with those regulations and to a discussion on the subject. The practical consequence is stated: it may require you to submit a year-end self-classification report to the US government. That is a compliance task attached to a package install, and no amount of code review will remove it. If your company has no process for export classification, this plugin creates work that has nothing to do with your database. If it does, the work is bounded, since the classification attaches to a known open source library rather than to a custom encryption scheme.

Installing the plugin and declaring the database locations

The install path is the standard Capacitor one. The package is added with your package manager and then npx cap sync propagates the native side of the plugin into the iOS and Android projects. The plugin then has to be declared in the main capacitor.config.ts file, under the plugins key with a CapacitorSQLite entry.

npm install --save @capacitor-community/sqlite
npx cap sync

The configuration block below shows the shape of the entry. You should see the three encryption switches and the per platform database locations replaced with your own values.

    CapacitorSQLite: {
      iosDatabaseLocation: 'Library/CapacitorDatabase',
      iosIsEncryption: true,
      iosKeychainPrefix: 'angular-sqlite-app-starter',
      iosBiometric: {
        biometricAuth: false,
        biometricTitle : "Biometric login for capacitor sqlite"
      },
      androidIsEncryption: true,
      androidBiometric: {
        biometricAuth : false,
        biometricTitle : "Biometric login for capacitor sqlite",
        biometricSubTitle : "Log in using your biometric"
      },
      electronIsEncryption: true,

The iosKeychainPrefix is what ties the stored encryption key to the iOS keychain, and the biometric block shows that a lock screen prompt can gate access to the database. The pnpm variant of the install additionally pulls jeep-sqlite and sql.js, which are the web side of the same story.

On the web the database is jeep-sqlite in IndexedDB

The web platform is where the plugin is least native, and the README is direct about it. When using the web platform, SQLite databases are backed by jeep-sqlite and stored in IndexedDB, which can be difficult to inspect during development. The plugin therefore leans on the browser's storage quota model rather than on a real file, and the difference shows up in two practical ways. First, the sql-wasm.wasm file has to be copied into the app by hand, from node_modules/sql.js/dist/sql-wasm.wasm into src/assets for Angular or into public/assets for Vue and React. Second, there is no direct database file to open, which is why the README points to a Chrome DevTools extension, Jeep SQLite Browser, that browses, queries and exports jeep-sqlite databases straight out of IndexedDB. On the browser side the plugin also follows the Capacitor Team's browser support guidelines, so it will not work in IE11 without additional JavaScript transformations such as Babel.

The Android build needs specific versions and backup exclusions

The Android quirks section is where the real setup work sits, and it is specific. If the build reports that x files were found with the path build-data.properties, the README says to add packagingOptions with an exclude for build-data.properties to app/build.gradle, and it links the issue and a Stack Overflow question for the underlying Gradle behaviour. Beyond that, the README asks you to check or add a Gradle JDK version of 21, an Android Gradle Plugin version of 8.7.2, and the following SDK values in variables.gradle.

      minSdkVersion = 23
      compileSdkVersion = 35
      targetSdkVersion = 35

The manifest needs backup switched off, with allowBackup and fullBackupContent set to false and a dataExtractionRules attribute pointing at a res/xml/data_extraction_rules.xml file. That last requirement is not cosmetic: it stops the operating system from copying an encrypted database into a cloud backup where the key would not travel with it. The minimum SDK of 23 also means the plugin will not run on older Android devices, which is a floor worth checking against your own audience.

Where the plugin is the wrong choice

The first case is an app that never leaves the browser. If there is no native shell, sql.js with a wasm file in IndexedDB gives you the same SQL surface with none of the native build, the SQLCipher dependency or the export question. The second case is a team that already has a native database layer. Capacitor apps often have native code for other reasons, and a plugin that duplicates a database you already own adds a second schema, a second migration path and a second set of failure modes for no gain. The third case is compliance, as described above. The fourth is Electron, where the plugin runs against a Node SQLite build rather than the native library, so a bug that reproduces on iOS may not reproduce on the desktop and vice versa. And the fifth is any project where the platform floor matters, since minimum SDK 23 and the JDK 21 requirement narrow who can build it and who can run it.

Editorial conclusion

Teams building a Capacitor application that needs a real local database rather than localStorage, and that need the same schema and query code to run on iOS, Android, Electron and the web, are the people this plugin was made for. It is the wrong choice for an app that never leaves the browser, where sql.js in IndexedDB is enough, and it is the wrong choice for a team unwilling to deal with export compliance, because the plugin uses SQLCipher even for unencrypted databases and the README points to the encryption export regulations and a year-end self-classification report to the US government. Check three things before adopting it: that your build pipeline can satisfy the Android requirements listed in the README, including JDK 21, Android Gradle Plugin 8.7.2 and the backup exclusions in AndroidManifest.xml, that your Electron database paths point at a location that exists on the user's machine, and whether the web fallback with jeep-sqlite is acceptable for your data. The plugin is MIT licensed, the last push was on 2026-08-06, and the newest release is v8.1.1 from the same day.

Frequently asked questions

Official sources

1. capacitor-community/sqlite on GitHub
2. Issues
3. License: MIT
4. README
5. Releases