capacitor-community-sqlite-add-unexpected-behaviour-docs: A Swift repository from folsze

SQLITE DATABASE

@capacitor-community/sqlite

CAPACITOR 4

Capacitor community plugin for Native and Electron SQLite Databases. In Native databases could be encrypted with SQLCipher

Maintainers

Maintainer	GitHub	Social
Quéau Jean Pierre	jepiqueau

To install:

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

yarn add @capacitor-community/sqlite
npx cap sync

pnpm install --save @capacitor-community/sqlite
pnpm install --save @jeep-sqlite
pnpm install --save sql.js
npx cap sync

then add plugin to main capacitor.config.json file:

{
  "appId": "com.example.app",
  "appName": "cap",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "plugins": {
    "CapacitorSQLite": {
      "iosDatabaseLocation": "Library/CapacitorDatabase",
      "iosIsEncryption": false,
      "iosKeychainPrefix": "cap",
      "iosBiometric": {
        "biometricAuth": false,
        "biometricTitle" : "Biometric login for capacitor sqlite"
      },
      "androidIsEncryption": false,
      "androidBiometric": {
        "biometricAuth" : false,
        "biometricTitle" : "Biometric login for capacitor sqlite",
        "biometricSubTitle" : "Log in using your biometric"
      },
      "electronWindowsLocation": "C:\\ProgramData\\CapacitorDatabases",
      "electronMacLocation": "YOUR_VOLUME/CapacitorDatabases",
      "electronLinuxLocation": "Databases"
    }
  }
}

Web Quirks

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. You'll need the usual capacitor/android/react npm script to build and copy the assets folder.

For Angular framework

Copy manually the file sql-wasm.wasm from node_modules/sql.js/dist/sql-wasm.wasm to the src/assets folder of YOUR_APP

For Vue & React frameworks

Copy manually the file sql-wasm.wasm from node_modules/sql.js/dist/sql-wasm.wasm to the public/assets folder of YOUR_APP

Android Quirks

In case you get the following error when building your app in Android Studio: x files found with path 'build-data.properties'. You can you add the following code to app/build.gradle:

    packagingOptions {
        exclude 'build-data.properties'
    }

See #301 and SO question for more information.

Check/Add the following: Gradle JDK version 11 Android Gradle Plugin Version 7.2.2 In variables.gradle

minSdkVersion = 22
compileSdkVersion = 33
targetSdkVersion = 33

In AndroidManifest.xml

    <application
      android:allowBackup="false"
      android:fullBackupContent="false"
      android:dataExtractionRules="@xml/data_extraction_rules"

In res/xml create a file data_extraction_rules.xml containing:

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
      <exclude domain="root" />
      <exclude domain="database" />
      <exclude domain="sharedpref" />
      <exclude domain="external" />
    </cloud-backup>
    <device-transfer>
      <exclude domain="root" />
      <exclude domain="database" />
      <exclude domain="sharedpref" />
      <exclude domain="external" />
    </device-transfer>
</data-extraction-rules>

Electron Quirks

On Electron, go to the Electron folder of YOUR_APPLICATION

cd electron
npm install --save sqlite3
npm install --save jszip
npm install --save node-fetch@2.6.7
npm install --save-dev @types/sqlite3

Important: node-fetch version must be <=2.6.7; otherwise you'll get an error running the app.

IOS Quirks

on iOS, no further steps needed.

Supported Methods by Platform

Name	Android	iOS	Electron	Web
createConnection (ReadWrite)	✅	✅	✅	✅
createConnection (ReadOnly)	✅	✅	✅	❌
closeConnection (ReadWrite)	✅	✅	✅	✅
closeConnection (ReadOnly)	✅	✅	✅	❌
isConnection (ReadWrite)	✅	✅	✅	✅
isConnection (ReadOnly)	✅	✅	✅	❌
open (non-encrypted DB)	✅	✅	✅	✅
open (encrypted DB)	✅	✅	❌	❌
close	✅	✅	✅	✅
getUrl	✅	✅	❌	❌
getVersion	✅	✅	✅	✅
execute	✅	✅	✅	✅
executeSet	✅	✅	✅	✅
run	✅	✅	✅	✅
query	✅	✅	✅	✅
deleteDatabase	✅	✅	✅	✅
importFromJson	✅	✅	✅	✅
exportToJson	✅	✅	✅	✅
deleteExportedRows	✅	✅	✅	✅
createSyncTable	✅	✅	✅	✅
setSyncDate	✅	✅	✅	✅
getSyncDate	✅	✅	✅	✅
isJsonValid	✅	✅	✅	✅
isDBExists	✅	✅	✅	✅
addUpgradeStatement	✅	✅	✅	✅
copyFromAssets	✅	✅	✅	✅
isDBOpen	✅	✅	✅	✅
isDatabase	✅	✅	✅	✅
isTableExists	✅	✅	✅	✅
getTableList	✅	✅	✅	✅
getDatabaseList	✅	✅	✅	✅
getMigratableDbList	✅	✅	❌	❌
addSQLiteSuffix	✅	✅	❌	❌
deleteOldDatabases	✅	✅	❌	❌
moveDatabasesAndAddSuffix	✅	✅	❌	❌
checkConnectionsConsistency	✅	✅	✅	✅
isSecretStored	✅	✅	❌	❌
setEncryptionSecret	✅	✅	❌	❌
changeEncryptionSecret	✅	✅	❌	❌
clearEncryptionSecret	✅	✅	❌	❌
checkEncryptionSecret	✅	✅	❌	❌
initWebStore	❌	❌	❌	✅
saveToStore	❌	❌	❌	✅
getNCDatabasePath	✅	✅	❌	❌
createNCConnection	✅	✅	❌	❌
closeNCConnection	✅	✅	❌	❌
isNCDatabase	✅	✅	❌	❌
transaction	✅	✅	✅	✅
getFromHTTPRequest	✅	✅	✅	✅
isDatabaseEncrypted	✅	✅	❌	❌
isInConfigEncryption	✅	✅	❌	❌
isInConfigBiometricAuth	✅	✅	❌	❌

Documentation & APIs

Applications demonstrating the use of the plugin and related documentation

Ionic/Angular

Ionic/Angular Usage Documentation
ionic-angular-sqlite-starter Ionic 6 Angular SQLite CRUD operations.
angular-sqlite-app-starter This one is now more for testing the issues.
angular-sqlite-synchronize-app

Ionic/Angular TypeORM app

ionic-sqlite-typeorm-app

Ionic/React

React+Vite

react-vite-sqlite-app

Ionic/Vue

Dependencies

The iOS and Android codes are using SQLCipher allowing for database encryption. The iOS codes is using ZIPFoundation for unzipping assets files. The Electron code is using sqlite3 and node-fetch from 4.2.0. The Web code is using the Stencil component jeep-sqlite based on sql.js, localforage, and jszip.