Introducing the PowerSync Capacitor SDK (Alpha)

Today we are introducing our native PowerSync Capacitor SDK!

This SDK extends the PowerSync Web SDK so you can use the same APIs in Capacitor apps (iOS, Android, web), while adding native SQLite support for stronger persistence and performance on mobile platforms. Under the hood, it integrates with the @capacitor-community/sqlite driver for native platforms, falling back to WA‑SQLite on web.

How It Works

The SDK handles runtime detection automatically so your database logic stays the same across platforms. This means you can write your code once, and PowerSync will use the optimal storage engine for each environment — native SQLite on mobile, WA-SQLite in the browser.

• On web platforms, it uses the PowerSync Web SDK, which relies on WA‑SQLite backed by either IndexedDB or OPFS.

• On native mobile platforms (iOS / Android) within a Capacitor web view, it replaces WA‑SQLite with the Capacitor Community SQLite driver, which communicates directly with the system’s SQLite engine.

Your schema definitions, query logic, and sync behavior remain the same regardless of whether your app is running in a browser or natively.

Why Native SQLite Matters

Using native SQLite on mobile provides several practical advantages over browser-based storage:

• Improved Database Persistence: Native SQLite offers more reliable data persistence compared to browser-based storage.

• Faster Queries: Running directly on the device’s SQLite engine avoids the overhead of browser storage layers.

• Lower Latency: Queries don’t have to cross the JavaScript-WASM boundary used by web-based SQLite engines, which makes database operations noticeably faster.

Get Started

Demo App

Quickly get a feel for how things work by checking out our demo app, which runs on iOS, Android and web.

Install in Your Own Project

1. Install the Capacitor SDK

   npm install @powersync/capacitor

2. Install peer dependencies

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

   These packages are required for the native SQLite integration on mobile platforms and the web fallback.

3. Sync Capacitor plugins

   npx cap sync

4. Define your client-side schema as you would using the PowerSync Web SDK, see an example here.

5. Instantiate the PowerSync Database:

   import { PowerSyncDatabase } from '@powersync/capacitor';
   
   // Import general components from the Web SDK package
   import { Schema } from '@powersync/web';
   import { AppSchema } from './AppSchema';
   
   /**
    * The Capacitor PowerSyncDatabase will automatically detect the platform
    * and use the appropriate database drivers.
    */
   export const db = new PowerSyncDatabase({
     // The schema you defined in the previous step
     schema: AppSchema,
     database: {
       // Filename for the SQLite database — it's important to only instantiate one instance per file.
       dbFilename: 'powersync.db'
     }
   });

6. And connect:

   import { Connector } from './Connector';
   
   export const setupPowerSync = async () => {
     // Uses the backend connector that will be created in the next section
     const connector = new Connector();
     db.connect(connector);
   };

   Next: See these docs for wiring up your backend.

Reference

Find the full SDK reference, instructions and examples here.

Limitations

The following features from the PowerSync Web SDK are not yet supported in Capacitor apps:

• Encryption for native mobile platforms.

• 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.

• 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).

Shoutout

Massive thanks to brandonkboswell and D.Lorean for working with us through early versions of this release!

Feedback

We’re releasing the Capacitor SDK in alpha to collect real-world usage feedback.  Because the Web SDK foundation is stable, most core functionality is expected to work reliably. However, the Capacitor Community SQLite integration for mobile platforms was newly added in this release and still needs to be battle-hardened.

If you need any help, run into issues or have feature requests, please report them on GitHub or join our Discord community.