PowerSync SDK on NPM
This SDK is distributed via NPM [External link].
Source Code
Refer to packages/capacitor in the powersync-js repo on GitHub.
API Reference
Full API reference for the PowerSync SDK [External link].
Example Projects
Gallery of example projects/demo apps built with Capacitor and PowerSync.
This SDK is currently in an alpha release.The SDK is largely built on our stable Web SDK, so that functionality can be considered stable. However, the Capacitor Community SQLite integration for mobile platforms is in alpha for real-world testing and feedback. There are known limitations currently.
Built on the Web SDKThe PowerSync Capacitor SDK is built on top of the PowerSync Web SDK. It shares the same API and usage patterns as the Web SDK. The main differences are:
- Uses Capacitor-specific SQLite implementation (
@capacitor-community/sqlite) for native Android and iOS platforms - Certain features are not supported on native Android and iOS platforms, see limitations below for details
@powersync/web for imports instead of @powersync/capacitor. See the JavaScript Web SDK reference for ORM support, SPA framework integration, and developer notes.SDK Features
- Real-time streaming of database changes: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic.
- Direct access to a local SQLite database: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions.
- Asynchronous background execution: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity.
- Query subscriptions for live updates: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date.
- Automatic schema management: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs can handle schema changes gracefully without requiring explicit migrations on the client-side.
Installation
Install Package
Add the PowerSync Capacitor NPM package to your project:- npm
- yarn
- pnpm
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
- yarn
- pnpm
Sync Capacitor Plugins
After installing, sync your Capacitor project:Getting Started
Before implementing the PowerSync SDK in your project, make sure you have completed these steps:- Signed up for a PowerSync Cloud account (here) or self-host PowerSync.
- Configured your backend database and connected it to your PowerSync instance.
- Installed the PowerSync Capacitor SDK.
1. Define the Schema
The first step is defining the schema for the local SQLite database. This schema represents a “view” of the downloaded data. No migrations are required — the schema is applied directly when the local PowerSync database is constructed (as we’ll show in the next step).
The types available are
text, integer and real. These should map directly to the values produced by the Sync Rules. If a value doesn’t match, it is cast automatically. For details on how Postgres types are mapped to the types below, see the section on Types in the Sync Rules documentation.
Example:
Note on imports: While you install
@powersync/capacitor, the Capacitor SDK extends the Web SDK so you import general components from @powersync/web (installed as a peer dependency). See the JavaScript Web SDK schema definition section for more advanced examples.Note: No need to declare a primary key
id column, as PowerSync will automatically create this.2. Instantiate the PowerSync Database
Next, you need to instantiate the PowerSync database — this is the core managed database. Its primary functions are to record all changes in the local database, whether online or offline. In addition, it automatically uploads changes to your app backend when connected. Example:The Capacitor PowerSyncDatabase automatically detects the platform and uses the appropriate database drivers:
- Android and iOS: Uses Capacitor Community SQLite for native database access
- Web: Falls back to the PowerSync Web SDK
CapacitorSQLiteOpenFactory for Capacitor platforms:
3. Integrate with your Backend
The PowerSync backend connector provides the connection between your application backend and the PowerSync client-side managed SQLite database. It is used to:- Retrieve an auth token to connect to the PowerSync instance.
- Apply local changes on your backend application server (and from there, to your backend database)
- PowerSyncBackendConnector.fetchCredentials - This is called every couple of minutes and is used to obtain credentials for your app backend API. -> See Authentication Setup for instructions on how the credentials should be generated.
- PowerSyncBackendConnector.uploadData - Use this to upload client-side changes to your app backend. -> See Writing Client Changes for considerations on the app backend implementation.
See the JavaScript Web SDK backend integration section for connector examples with Supabase and Firebase authentication, and handling
uploadData with batch operations.Using PowerSync: CRUD functions
Once the PowerSync instance is configured you can start using the SQLite DB functions.All CRUD examples from the JavaScript Web SDK apply: The Capacitor SDK uses the same API as the Web SDK. See the JavaScript Web SDK CRUD functions section for examples of
get, getAll, watch, execute, writeTransaction, incremental watch updates, and differential results.- PowerSyncDatabase.get - get (SELECT) a single row from a table.
- PowerSyncDatabase.getAll - get (SELECT) a set of rows from a table.
- PowerSyncDatabase.watch - execute a read query every time source tables are modified.
- PowerSyncDatabase.execute - execute a write (INSERT/UPDATE/DELETE) query.
Fetching a Single Item
The get method executes a read-only (SELECT) query and returns a single result. It throws an exception if no result is found. Use getOptional to return a single optional result (returnsnull if no result is found).
Querying Items (PowerSync.getAll)
The getAll method returns a set of rows from a table.Watching Queries (PowerSync.watch)
The watch method executes a read query whenever a change to a dependent table is made.- AsyncIterator approach
- Callback approach
Mutations (PowerSync.execute, PowerSync.writeTransaction)
The execute method can be used for executing single SQLite write statements.Configure Logging
Enable verbose output in the developer tools for detailed logs.
Limitations
- Encryption for native mobile platforms is not yet supported.
- Multiple tab support is not available for native Android and iOS targets.
PowerSyncDatabase.executeRawdoes not support results where multiple columns would have the same name in SQLitePowerSyncDatabase.executehas 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).