Skip to main content

PowerSync SDK for Capacitor

PowerSync keeps a client-side SQLite database in sync with your backend database. Changes appear across users and devices in real-time, user interactions feel instant and your app continues to work even when offline. Supports Postgres, MongoDB, MySQL, and SQL Server. Client SDKs are available for a wide range of environments including web, mobile, desktop, headless and embedded.

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: Beta Release​

This package is currently in a beta 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

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 the native Capacitor Community SQLite driver, PowerSyncDatabase.connect() defaults to HTTP with NDJSON streaming. This avoids slow binary payload processing in the native SQLite bridge. Web targets keep the default Web SDK connection behavior.

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.
  • 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). Queries such as INSERT into customers (id, name) VALUES (uuid(), 'name') RETURNING * do not work on Android.
  • Multiple tab support is not available for native Android and iOS targets. If you're not opening a second webview in your native app using something like @jackobo/capacitor-webview, you are unaffected by this.

Examples​

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

Found a bug or need help?​