Build with AI
PowerSync SDK on NPM
This SDK is distributed via NPM
Source Code
Refer to
packages/capacitor in the powersync-js repo on GitHubAPI Reference
Full API reference for the SDK
Example Projects
Gallery of example projects/demo apps built with Capacitor and PowerSync
Changelog
Changelog for the SDK
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:
- It uses the Capacitor-specific SQLite implementation (
@capacitor-community/sqlite) on native Android and iOS. - Some features are not supported on native Android and iOS. See Limitations.
Schema and Table from @powersync/web, and PowerSyncDatabase from @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 handle schema changes without explicit migrations on the client side.
Installation
Requirements: The Capacitor SDK requires Capacitor 8 or later. Minimum platform versions are iOS 15.0 and Android API level 24. On iOS, both Swift Package Manager (SPM) and CocoaPods are supported.If you are on Capacitor 6 or 7, follow the Capacitor v8 upgrade guide before installing or upgrading
@powersync/capacitor.- npm
- yarn
- pnpm
- npm
- yarn
- pnpm
Getting Started
Prerequisites: Before you start, connect your source database to the PowerSync Service and deploy Sync Streams. These are steps 1-4 in the Setup Guide.1. Define the Client-Side Schema
The client-side schema defines the tables and columns of the SQLite database that the PowerSync client SDK manages and that your app reads from and writes to. It is usually derived from your backend database schema and your Sync Streams, and it can also include local-only tables. You apply the schema when you instantiate the database in the next step. Schema migrations are not required. The SDK syncs schemaless data and applies the schema to that data with SQLite views. The exception is raw tables, which you create and migrate yourself. The available column types aretext, integer, and real. These should match the values produced by your Sync Streams. If a value does not match, it is cast automatically. For details on how source database types map to SQLite types, see Types.
Example:
You do not need to declare an
id column. PowerSync creates it automatically.2. Instantiate the PowerSync Database
Next, instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your Sync Streams. Your app reads from and writes to this local database whether the user is online or offline. Example:CapacitorSQLiteOpenFactory for Capacitor platforms:
3. Integrate with Your Backend
The backend connector connects the PowerSync client SDK to your application backend. The SDK uses it to:- Get an auth token to connect to the PowerSync instance.
- Upload client-side writes to your backend API. The SDK places every write to the SQLite database in an upload queue and uploads the queue to your backend when the user is connected. Your backend then applies the changes to the source database.
- PowerSyncBackendConnector.fetchCredentials - The SDK calls this method to get authentication credentials. It caches the credentials and calls the method again only when needed, for example on the first connection or when the token is near expiry. See When
fetchCredentials()is Called for details and Authentication Setup for how to generate credentials. - PowerSyncBackendConnector.uploadData - The SDK calls this method whenever it has client-side writes to upload to your backend API. Implement how those writes are processed and uploaded. See When
uploadData()is Called for triggers, throttling, and retry behavior, and Writing Client Changes for the app backend implementation.
4. Subscribe to Sync Streams
Streams defined withauto_subscribe: true start syncing as soon as the client connects. For all other streams, your app must subscribe before their data downloads. The basic pattern is: subscribe to a stream, wait for its data to sync, then unsubscribe when the data is no longer needed.
Using PowerSync: CRUD Functions
Once the PowerSync database is connected and your streams have synced, the data is in the local SQLite database. The most commonly used CRUD functions to interact with your SQLite data are:- 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 a dependent table changes.
- 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.When using the default client-side JSON-based view system, writes are applied to a view, with triggers writing to the underlying table. Because of this, If you need direct table writes, use raw tables.
result.rowsAffected from db.execute() can be 0 even when an UPDATE or DELETE succeeds.When you need to confirm whether a mutation changed any rows, add a RETURNING clause and check the returned rows:Configure Logging
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 have the same name in SQLite.PowerSyncDatabase.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. On Android, the SDK treats a statement as a query only when the SQL starts withselect(case-insensitive).
Additional Usage Examples
For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the Usage Examples page.ORM Support
See JavaScript ORM Support for details.Troubleshooting
See Troubleshooting for pointers to debug common issues.Supported Platforms
See Supported Platforms -> Capacitor SDK.Upgrading the SDK
Run the following command in your project folder:- npm
- yarn
- pnpm