README.md

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, MySQL or SQL Server 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"
  }
});

• On Android and iOS, this SDK uses Capacitor Community SQLite for native database access.
• On web, it falls back to the PowerSync Web SDK.

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?

• Join our Discord server to ask questions or share feedback.
• Open a GitHub issue for bugs.
• Submit ideas via our public roadmap or schedule a chat.