> ## Documentation Index > Fetch the complete documentation index at: https://powersync-sync-streams-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # React Native & Expo SDK > Use PowerSync in React Native (& Expo) apps. ```text Build with AI icon="sparkles" wrap theme={null} Install the PowerSync Agent Skills with: npx skills add powersync-ja/agent-skills. Then follow the skills to onboard this project to PowerSync using the React Native & Expo SDK. ``` This SDK is distributed via NPM Refer to packages/react-native in the powersync-js repo on GitHub Full API reference for the SDK Gallery of example projects/demo apps built with React Native and PowerSync. 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](/client-sdks/frameworks/react) for examples. ## Installation Add the [PowerSync React Native NPM package](https://www.npmjs.com/package/@powersync/react-native) to your project: ```bash theme={null} npx expo install @powersync/react-native @op-engineering/op-sqlite ``` ```bash theme={null} yarn expo add @powersync/react-native @op-engineering/op-sqlite ``` ``` pnpm expo install @powersync/react-native @op-engineering/op-sqlite ``` `@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](/client-sdks/frameworks/expo-go-support). **Polyfills and additional notes:** * For async iterator support with watched queries, additional polyfills are required. See the [Babel plugins section](https://www.npmjs.com/package/@powersync/react-native#babel-plugins-watched-queries) in the README. * We recommend adding this [metro config](https://github.com/powersync-ja/powersync-js/tree/main/packages/react-native#metro-config-optional) 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](/intro/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](/sync/streams/overview), and it can also include [local-only tables](/client-sdks/advanced/local-only-usage). 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](/client-sdks/advanced/raw-tables), which you create and migrate yourself. **Generate schema automatically** In the [PowerSync Dashboard](https://dashboard.powersync.com/), 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](/tools/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](/sync/advanced/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](/sync/types). **Example:** ```typescript powersync/AppSchema.ts theme={null} import { column, Schema, Table } from '@powersync/react-native'; const lists = new Table({ created_at: column.text, name: column.text, owner_id: column.text }); const todos = new Table( { list_id: column.text, created_at: column.text, completed_at: column.text, description: column.text, created_by: column.text, completed_by: column.text, completed: column.integer }, { indexes: { list: ['list_id'] } } ); export const AppSchema = new Schema({ todos, lists }); // For types export type Database = (typeof AppSchema)['types']; export type TodoRecord = Database['todos']; // OR: // export type Todo = RowType; export type ListRecord = Database['lists']; ``` 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:** ```typescript powersync/system.ts theme={null} import { PowerSyncDatabase } from '@powersync/react-native'; import { AppSchema } from './Schema'; export const powersync = 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. // For other database options see, // https://powersync-ja.github.io/powersync-js/web-sdk/globals#sqlopenoptions dbFilename: 'powersync.db' } }); ``` After you instantiate the PowerSync database, call the [connect()](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#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](/client-sdks/advanced/local-only-usage) guide. ```typescript powersync/system.ts theme={null} import { Connector } from './Connector'; export const setupPowerSync = async () => { // Uses the backend connector that you create in the next step const connector = new Connector(); powersync.connect(connector); }; ``` ### 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](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L16) - 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](/configuration/app-backend/client-side-integration#when-fetchcredentials-is-called) for details and [Authentication Setup](/configuration/auth/overview) for how to generate credentials. 2. [PowerSyncBackendConnector.uploadData](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L24) - 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](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for the app backend implementation. **Example:** ```typescript powersync/Connector.ts theme={null} import { type PowerSyncBackendConnector, type CommonPowerSyncDatabase, UpdateType } from "@powersync/react-native" export class Connector implements PowerSyncBackendConnector { /** * Implement fetchCredentials to obtain a JWT from your authentication service. * See https://docs.powersync.com/configuration/auth/custom */ async fetchCredentials() { return { // The PowerSync instance URL or self-hosted endpoint endpoint: 'https://xxxxxx.powersync.journeyapps.com', /** * To get started quickly, use a development token, see: * Authentication Setup https://docs.powersync.com/configuration/auth/development-tokens) to get up and running quickly */ token: 'An authentication token' }; } /** * Implement uploadData to send local changes to your backend service. * You can omit this method if you only want to sync data from the database to the client * See example implementation here: https://docs.powersync.com/client-sdks/usage-examples#send-changes-in-local-data-to-your-backend-service */ async uploadData(database: CommonPowerSyncDatabase) { /** * For batched crud transactions, use data.getCrudBatch(n); * https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#getcrudbatch */ const transaction = await database.getNextCrudTransaction(); if (!transaction) { return; } for (const op of transaction.crud) { // The data that needs to be changed in the remote db const record = { ...op.opData, id: op.id }; switch (op.op) { case UpdateType.PUT: // TODO: Instruct your backend API to CREATE a record break; case UpdateType.PATCH: // TODO: Instruct your backend API to PATCH a record break; case UpdateType.DELETE: //TODO: Instruct your backend API to DELETE a record break; } } // Completes the transaction and moves onto the next one await transaction.complete(); } } ``` ### 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. ```js theme={null} // Subscribe to a stream with parameters const sub = await db.syncStream('list_todos', { list_id: 'abc123' }).subscribe(); // Wait for the initial data to sync await sub.waitForFirstSync(); // The stream's rows are now in the local SQLite database. // TODO: Read the todos for this list with a local query. // When the data is no longer needed sub.unsubscribe(); ``` If you use React, the `useQuery` hook accepts a `streams` option and the `useSyncStream` hook manages a subscription for you. See [Framework Integrations](/sync/streams/client-usage#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](/sync/streams/client-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: * [PowerSyncDatabase.get](#fetching-a-single-item) - get (`SELECT`) a single row from a table. * [PowerSyncDatabase.getAll](#querying-items-powersync-getall) - get (`SELECT`) a set of rows from a table. * [PowerSyncDatabase.watch](#watching-queries-powersync-watch) - execute a read query every time a dependent table changes. * [PowerSyncDatabase.execute](#mutations-powersync-execute) - execute a write (`INSERT`/`UPDATE`/`DELETE`) query. ### Fetching a Single Item The [get](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#get) method executes a read-only (`SELECT`) query and returns a single result. It throws an exception if no result is found. Use [getOptional](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#getoptional) to return a single optional result (returns `null` if no result is found). ```js TodoItemWidget.jsx theme={null} import { Text } from 'react-native'; import { powersync } from "../powersync/system"; export const TodoItemWidget = ({id}) => { const [todoItem, setTodoItem] = React.useState([]); const [error, setError] = React.useState([]); React.useEffect(() => { // .get returns the first item of the result. Throws an exception if no result is found. powersync.get('SELECT * from todos WHERE id = ?', [id]) .then(setTodoItem) .catch(ex => setError(ex.message)) }, []); return {error || todoItem.description} } ``` ### Querying Items (`PowerSync.getAll`) The [getAll](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#getall) method returns a set of rows from a table. ```js ListsWidget.jsx theme={null} import { FlatList, Text} from 'react-native'; import { powersync } from "../powersync/system"; export const ListsWidget = () => { const [lists, setLists] = React.useState([]); React.useEffect(() => { powersync.getAll('SELECT * from lists').then(setLists) }, []); return ( ({key: list.id, ...list}))} renderItem={({item}) => {item.name}} />) } ``` ### Watching Queries (`PowerSync.watch`) The [watch](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#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. ```javascript theme={null} async function* pendingLists(): AsyncIterable { for await (const result of db.watch( `SELECT * FROM lists WHERE state = ?`, ['pending'] )) { yield result.rows?._array ?? []; } } ``` ```javascript theme={null} const pendingLists = (onResult: (lists: any[]) => void): void => { db.watch( 'SELECT * FROM lists WHERE state = ?', ['pending'], { onResult: (result: any) => { onResult(result.rows?._array ?? []); } } ); } ``` For advanced watch query features such as incremental updates and differential results, see [Live Queries / Watch Queries](/client-sdks/watch-queries). ### Mutations (`PowerSync.execute`) The [execute](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#execute) method can be used for executing single SQLite write statements. ```js ListsWidget.jsx theme={null} import { Alert, Button, FlatList, Text, View } from 'react-native'; import { powersync } from "../powersync/system"; export const ListsWidget = () => { // Populate lists with one of methods listed above const [lists, setLists] = React.useState([]); return ( ({key: list.id, ...list}))} renderItem={({item}) => ( {item.name}