Skip to main content

PowerSync SDK for Capacitor

PowerSync is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB or MySQL on the server-side.

This package (@powersync/capacitor) is the PowerSync SDK for Capacitor apps. It wraps the PowerSync Web SDK for Capacitor PWAs and uses Capacitor Community SQLite as the database driver for Android and iOS.

Note: Alpha Release​

This package is currently in an alpha release.

Installation​

Install Package​

npm install @powersync/capacitor

This package uses @powersync/web as a peer dependency. For additional @powersync/web configuration and instructions see the Web SDK README.

Install Peer Dependencies​

You must also install the following peer dependencies:

npm install @capacitor-community/sqlite @powersync/web @journeyapps/wa-sqlite

See the Capacitor Community SQLite repository for additional instructions.

Sync Capacitor Plugins​

After installing, sync your Capacitor project:

npx cap sync

Usage​

import { PowerSyncDatabase } from '@powersync/capacitor';
// Import general components from the Web SDK package
import { Schema } from '@powersync/web';
/**
 * The Capacitor PowerSyncDatabase will automatically detect the platform
 * and use the appropriate database drivers.
 */
const db = new PowerSyncDatabase({
  schema: new Schema({...}),
  database: {
    dbFilename: "mydatabase.sqlite"
  }
});

When using custom database factories, be sure to specify the CapacitorSQLiteOpenFactory for Capacitor platforms.

const db = new PowerSyncDatabase({
  schema: new Schema({...}),
  database: isWeb ? new WASQLiteOpenFactory({dbFilename: "mydb.sqlite"}) :
    new CapacitorSQLiteOpenFactory({dbFilename: "mydb.sqlite"})
});

Platform Support​

  • Android: Uses native SQLite via Capacitor Community SQLite.
  • iOS: Uses native SQLite via Capacitor Community SQLite.
  • Web: Uses WASQLite via the PowerSync Web SDK.
  • Electron: Uses WASQLite via the PowerSync Web SDK.

Limitations​

  • Encryption for native mobile platforms is not yet supported.
  • Multiple tab support is not available for native Android and iOS targets.
  • PowerSyncDatabase.executeRaw does not support results where multiple columns would have the same name in SQLite
  • PowerSyncDatabase.execute has limited support on Android. The SQLCipher Android driver exposes queries and executions as separate APIs, so there is no single method that handles both. While PowerSyncDatabase.execute accepts both, on Android we treat a statement as a query only when the SQL starts with select (case-insensitive).

Examples​

See the demos/example-capacitor/ directory for a working example.

Found a bug or need help?​