Skip to main content
Build with AI

PowerSync SDK on NPM

This SDK is distributed via NPM

Source Code

Refer to packages/react-native in the powersync-js repo on GitHub

API Reference

Full API reference for the SDK

Example Projects

Gallery of example projects/demo apps built with React Native and PowerSync.

Changelog

Changelog for the SDK

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.

Using Hooks

The @powersync/react package provides React hooks for PowerSync. See React Hooks for examples.

npm: @powersync/react

Installation

Add the PowerSync React Native NPM package to your project:
@op-engineering/op-sqlite is the SQLite library used by the PowerSync SDK on React Native. It needs to be installed separately because React Native only considers direct dependencies for autolinking. The PowerSync React Native SDK currently supports version 1.17.0 or later of @op-engineering/op-sqlite.
Using Expo Go? Our native database adapter is not compatible with Expo Go’s sandbox environment. To run PowerSync with Expo Go install our JavaScript-based adapter @powersync/adapter-sql-js instead. See details here.
Polyfills and additional notes:
  • For async iterator support with watched queries, additional polyfills are required. See the Babel plugins section in the README.
  • We recommend adding this metro config to avoid build issues.

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.
Generate schema automaticallyIn the PowerSync Dashboard, select your project and instance and click the Connect button in the top bar to generate the client-side schema in your preferred language. The schema is generated from your Sync Streams. The CLI offers the same function.The generated schema does not include an id column. The client SDK creates an id column of type text automatically, so you do not need to declare it. See Client ID for details.
The available column types are text, 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:
powersync/AppSchema.ts
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:
powersync/system.ts
After you instantiate the PowerSync database, call the connect() method to sync data with your backend.
This section assumes that you use PowerSync to sync your backend source database with SQLite in your app. To manage a local SQLite database without sync, instantiate the PowerSync database without calling connect() and see the Local-Only guide.
powersync/system.ts

3. Integrate with Your Backend

The backend connector connects the PowerSync client SDK to your application backend. The SDK uses it to:
  1. Get an auth token to connect to the PowerSync instance.
  2. 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.
The connector must implement two methods:
  1. 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.
  2. 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.
Example:
powersync/Connector.ts

4. Subscribe to Sync Streams

Streams defined with auto_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.
If you use React, the useQuery hook accepts a streams option and the useSyncStream hook manages a subscription for you. See Framework Integrations. After you unsubscribe, the synced data stays in the local database for the stream’s time-to-live (TTL), which is 24 hours by default. If the app subscribes again within that time, the data is already available. See Client-Side Usage for framework hooks, per-subscription sync status, custom TTLs, priority overrides, and connection parameters.

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:

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 (returns null if no result is found).
TodoItemWidget.jsx

Querying Items (PowerSync.getAll)

The getAll method returns a set of rows from a table.
ListsWidget.jsx

Watching Queries (PowerSync.watch)

The watch method executes a read query whenever a change to a dependent table is made. It can be used with an AsyncGenerator, or with a callback.
For advanced watch query features such as incremental updates and differential results, see Live Queries / Watch Queries.

Mutations (PowerSync.execute)

The execute method can be used for executing single SQLite write statements.
ListsWidget.jsx
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, 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:
If you need direct table writes, use raw tables.

Configure Logging

Enable verbose output in the developer tools for detailed logs.

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 -> React Native SDK.

Upgrading the SDK

Run the following command in your project folder:

Developer Notes

Connection Methods

This SDK supports two methods for streaming sync commands:
  1. HTTP Streaming (Default)
    • This is the default streaming method for Expo apps.
  2. WebSocket (Fallback)
    • This implementation uses RSocket for reactive socket streams.
    • This is necessary on React Native without Expo, as fetch() in React Native does not support streaming responses.
    • To customize window sizes for flow control and back-pressure, set fetchStrategy to Buffered (default) or Sequential.
By default, the PowerSyncDatabase.connect() method uses HTTP on Expo apps (with expo/fetch as an HTTP client) and WebSockets for plain React Native apps. You can optionally specify the connectionMethod to override this:

Android: Flipper Network Plugin for HTTP Streams

If you connect to PowerSync with HTTP streams (the default), Android requires additional configuration. React Native does not support streams natively, so the SDK uses the polyfills from the installation steps. An open Flipper issue prevents the Flipper network plugin from firing stream events. Disable the plugin so that HTTP streams work. If you are using Java (Expo < 50): Uncomment the following in android/app/src/debug/java/com/<ProjectName>/ReactNativeFlipper.java:
Disable the dev client network inspector in android/gradle.properties:
If you are using Kotlin (Expo > 50): Comment out the following in onCreate in android/app/src/main/java/com/<ProjectName>/example/MainApplication.kt:

Development on iOS Simulator

If you test offline mode on an iOS simulator by disabling the host machine’s internet connection, the simulator stays offline even after you restore the connection. This affects all network requests in the app.