SQLITE DATABASE

@capacitor-community/sqlite

CAPACITOR 3

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

CAPACITOR 3 (Master)

🚨 Release 3.4.3-3 all platforms ->> 🚨

The main change is related to the delete table's rows when a synchronization table exists as well as a last_mofidied table's column, allowing for database synchronization of the local database with a remote server database.

• All existing triggers to YOUR_TABLE_NAME_trigger_last_modified must be modified as follows

  CREATE TRIGGER YOUR_TABLE_NAME_trigger_last_modified
    AFTER UPDATE ON YOUR_TABLE_NAME
    FOR EACH ROW WHEN NEW.last_modified < OLD.last_modified
    BEGIN
        UPDATE YOUR_TABLE_NAME SET last_modified= (strftime('%s', 'now')) WHERE id=OLD.id;
    END;
  

• an new column sql_deleted must be added to each of your tables as

  sql_deleted BOOLEAN DEFAULT 0 CHECK (sql_deleted IN (0, 1))
  

  This column will be autommatically set to 1 when you will use a DELETE FROM ... sql statement in the execute, run or executeSet methods.

• In the JSON object that you provide to importFromJson, all the deleted rows in your remote server database's tables must have the sql_deleted column set to 1. This will indicate to the import process to physically delete the corresponding rows in your local database. All the others rows must have the sql_deleted column set to 0.

• In the JSON object outputs by the exportToJson, all the deleted rows in your local database have got the sql_deleted column set to 1 to help in your synchronization management process with the remote server database. A system last_exported_date is automatically saved in the synchronization table at the start of the export process flow.

• On successfull completion of your synchronization management process with the remote server database, you must

  • Set a new synchronization date (as (new Date()).toISOString()) with the setSyncDate method.
  • Execute the deleteExportedRows method which physically deletes all table's rows having 1 as value for the sql_deleted column prior to the last_exported_date in your local database.

An example of using this new feature is given in solidjs-vite-sqlite-app. It has been used to test the validity of the implementation.

🚨 Release 3.4.3-3 <<- 🚨

🚨 Release 3.4.2-4 ->> 🚨 !!!! DO NOT USE IT !!!! 🚨 Release 3.4.2-4 <<- 🚨

🚨 Since release 3.4.2-3 ->> 🚨

• overwrite boolean parameter has been added to the Json Object (default false)

  • true : delete the physically the database whatever the version is.
  • false:
    • re-importing a database with the same version number will do nothing, keeping the existing database and will return changes = 0
    • re-importing a database with a lower version number will throw an error ImportFromJson: Cannot import a version lower than

• During an import in full mode the Foreign Key constraint has been turn off before dropping the tables and turn back on after

🚨 Since release 3.4.2-3 <<- 🚨 🚨 Since release 3.4.1 ->> 🚨 Databases location for Electron can be set in the config.config.ts as followed:

• for sharing databases between users:

  plugins: {
    CapacitorSQLite: {
      electronMacLocation: "/YOUR_DATABASES_PATH",
      electronWindowsLocation: "C:\\ProgramData\\CapacitorDatabases",
      electronLinuxLocation: "/home/CapacitorDatabases"
    }
  }
  

• for only the user in its Home folder

  Plugins: {
    CapacitorSQLite: {
      electronMacLocation: "Databases",
      electronWindowsLocation: "Databases",
      electronLinuxLocation: "Databases"
    }
  }
  

For existing databases, YOU MUST COPY old databases to the new location You MUST remove the Electron folder and add it again with

npx cap add @capacitor-community/electron
npm run build 
cd electron
npm i --save sqlite3
npm i --save @types:sqlite3
npm run rebuild
cd ..
npx cap sync @capacitor-community/electron
npm run build
npx cap copy @capacitor-community/electron
npx cap open @capacitor-community/electron

🚨 Since release 3.4.1 <<- 🚨

🚨 Since release 3.4.1-1 ->> 🚨

• add iosIsEncryption, androidIsEncryption in capacitor.config.ts When your application use only non-encrypted databases set those parameter to false then iOS KeyChain & Android MasterKey are not defined.

🚨 Since release 3.4.1-1 <<- 🚨

🚨 Since release 3.4.0-2 ->> 🚨

• iOS & Android only Adding biometric FaceID/TouchID to secure the pass phrase in the Keychain/SharedPreferences stores. see: Biometric_Authentication

• iOS only Fix identical pass phrase stored in the Keychain for differents applications using the plugin by adding an application prefix to the Keychain account. Before the account "CapacitorSQLitePlugin" was used and was the same for all applications. Now by adding iosKeychainPrefix: 'YOUR_APP_NAME'in the capacitor.config.ts of your application, the account will be "YOUR_APP_NAME_CapacitorSQLitePlugin" If you were having a pass phrase stored, first modify the capacitor.config.ts and then run the command isSecretStored which will manage the upgrade of the Keychain account. 🚨 Since release 3.4.0-2 <<- 🚨

🚨 Since release 3.3.3-2 ->> 🚨

• iOS only Support for a database location not visible to iTunes and backed up to iCloud. For this you must add to the const config: CapacitorConfig of the capacitor.config.ts file of your application the following:

    plugins: {
      CapacitorSQLite: {
        "iosDatabaseLocation": "Library/CapacitorDatabase"
      }
    }

  Pre-existing databases from the Documents folder will be moved to the new folder Library/CapacitorDatabase and your application will work as before. If you do not modify the capacitor.config.ts file of your application the databases will still reside in the Documents folder

🚨 Since release 3.3.3-2 <<- 🚨

🚨 Since release 3.2.5-2 ->> 🚨

• support zip file in copyFromAssets method
• add optional overwrite parameter (true/false) default to true

🚨 Since release 3.2.5-2 <<- 🚨

🚨 Since release 3.2.3-1 ->> 🚨

The initWebStore and saveToStore methods have been added to the Web platform.

• The initWebStore has been added to fix the issue#172 and since then is MANDATORY

...
if(platform === "web") {
  await customElements.whenDefined('jeep-sqlite');
  const jeepSqliteEl = document.querySelector('jeep-sqlite');
  if(jeepSqliteEl != null) {
    await sqliteConnection.initWebStore()
    ...
  }
}
...

• the saveToStore allows to perform intermediate save of the database in case the browser needs to delete the cache.

🚨 Since release 3.2.3-1 <<- 🚨

The test has been achieved on:

• a Ionic/Angular app

• a Ionic/React app

• a Ionic/Vue app

• a React Vite app

• a Vue Vite app

• a Vue TypeORM app

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.

Installation

npm install @capacitor-community/sqlite
npm run build
npx cap add android
npx cap add ios
npx cap add @capacitor-community/electron

and do when you update

npx cap sync
npx cap sync @capacitor-community/electron

Web

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

IOS

• on iOS, no further steps needed.

Android

• On Android, no further steps needed.

Electron

• On Electron, go to the Electron folder of YOUR_APPLICATION

cd electron
npm install --save sqlite3
npm install --save jszip
npm install --save-dev @types/sqlite3
npm run build

Build & Run

npm run build
npx cap copy
npx cap copy web
npx cap copy @capacitor-community/electron

Web

• Angular

ionic serve

• Vue

npm run serve

• React

npm run start

IOS

npx cap open ios

Android

npx cap open android

Electron

npx cap open @capacitor-community/electron

Readme previous releases

previous releases

Issues

issues

Configuration

No configuration required for this plugin

Supported methods

Name	Android	iOS	Electron	Web
createConnection	✅	✅	✅	✅
closeConnection	✅	✅	✅	✅
isConnection	✅	✅	✅	✅
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	✅	✅	❌	❌
checkConnectionsConsistency	✅	✅	✅	✅
isSecretStored	✅	✅	❌	❌
setEncryptionSecret	✅	✅	❌	❌
changeEncryptionSecret	✅	✅	❌	❌
initWebStore	❌	❌	❌	✅
saveToStore	❌	❌	❌	✅
getNCDatabasePath	✅	✅	❌	❌
createNCConnection	✅	✅	❌	❌
closeNCConnection	✅	✅	❌	❌
isNCDatabase	✅	✅	❌	❌
transaction	✅	✅	✅	✅

Supported SQLite Types

-Datatypes In SQLite Version 3

Documentation

API

• API_Documentation

• API_Connection_Wrapper_Documentation

• API_DB_Connection_Wrapper_Documentation

• ImportExportJson_Documentation

• UpgradeDatabaseVersion_Documentation

• MigratingCordovaDatabases_Documentation

• TypeORM_Documentation

• Web_Documentation

• Non_Conformed_Databases_Documentation

• Biometric_Authentication

Framework's Usage

• Ionic/Angular_Usage_Documentation

• Ionic/React_Usage_Documentation

• Ionic/Vue_Usage_Documentation

Applications demonstrating the use of the plugin

Ionic/Angular

• angular-sqlite-app-starter

Ionic/React

• react-sqlite-app-starter

React+Vite

• react-vite-sqlite-app

Ionic/Vue

• vue-sqlite-app-starter

Vue

• vue-sqlite-app

Vue+Vite

• vue-vite-sqlite-app

SolidJS+Vite

• solidjs-vite-sqlite-app

Usage

• see capacitor documentation

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. The Web code is using the Stencil component jeep-sqlite based on sql.js, localforage. and jszip

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jean Pierre Quéau 💻

Paul Antoine 💻

Karyfars 💻

Chriswep 📖

Nirajhinge 💻

Dirk Gausmann 💻

Mike Summerfeldt 💻

Peakcool 💻

Gion-Andri Cantieni 📖

Robin Genz 📖

Dewald Els 💻

Joe Woodhouse 📖

Ptasheq 📖

Victory Osayi 💻

Tobias Mücksch 💻

Manuel Rodríguez 💻

This project follows the all-contributors specification. Contributions of any kind welcome!