Skip to main content
PowerSync keeps a client-side SQLite database in sync with your backend database. Changes appear across users and devices in real time, user interactions feel instant, and your app continues to work even when offline. Your app reads and writes SQLite directly. With Sync Streams, you define the subset of backend data each client receives. This enables partial sync instead of replicating the entire backend database to every device. Changes in that subset flow through the PowerSync Service into SQLite, where watched queries update the UI. Client writes are committed locally first, then enter an upload queue and are sent to your application backend for validation and persistence. For synced data, this reduces per-screen fetching, cache invalidation, and client-state plumbing. By the end of this guide, you will have connected your source database, defined what data each client receives, and integrated a client SDK that reads, writes, and watches local data.

1. Configure Your Source Database

PowerSync needs to connect to your source database (Postgres, MongoDB, Azure DocumentDB, MySQL, SQL Server or Convex) to replicate data. Before setting up PowerSync, you need to configure your database with the appropriate permissions and replication settings.
Using the PowerSync CLI and want an automatically integrated Postgres instance for local development? You can skip to Step 2 and set one up with the CLI (Self-Hosted) tab.
Configuring Postgres for PowerSync involves three main tasks:
  1. Enable logical replication: PowerSync reads the Postgres write-ahead log (WAL) using logical replication. Set wal_level = logical in your Postgres configuration.
  2. Create a PowerSync database user: Create a role with replication privileges and read-only access to your tables.
  3. Create a powersync publication: Create a logical replication publication named powersync to specify which tables to replicate.
PowerSync requires Postgres version 11 or greater.
Learn More
  • For more details on Postgres setup, including provider-specific guides (Supabase, AWS RDS, etc.), see Source Database Setup.
  • Self-hosting PowerSync? See the Self-Host-Demo App for a complete working example of connecting a Postgres source database to PowerSync.

2. Set Up PowerSync Service Instance

PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be self-hosted (PowerSync Open Edition or PowerSync Enterprise Self-Hosted Edition).
If you haven’t yet, sign up for a free PowerSync Cloud account here.After signing up, you will be taken to the PowerSync Dashboard.Here, create a new project. PowerSync creates Development and Production instances of the PowerSync Service by default in the project.

3. Connect PowerSync to Your Source Database

The next step is to connect your PowerSync Service instance to your source database.
In the PowerSync Dashboard, select your project and instance, then go to Database Connection:
  1. Select the appropriate database type tab (Postgres, MongoDB, MySQL, SQL Server or Convex). For Azure DocumentDB, select MongoDB.
  2. Fill in your connection details:
    Use the username (e.g., powersync_role) and password you created in Step 1: Configure your Source Database.
    • Postgres: Host, Port (5432), Database name, Username, Password, SSL Mode
    • MongoDB: Connection URI (e.g., mongodb+srv://user:pass@cluster.mongodb.net/database)
    • Azure DocumentDB: Connection URI (e.g., mongodb+srv://user:pass@cluster.windows.net/database)
    • MySQL: Host, Port (3306), Database name, Username, Password
    • Convex: Deployment URL and deploy key. See Convex Source Database Setup.
    • SQL Server: Name, Host, Port (1433), Database name, Username, Password
  3. Click Test Connection to verify
  4. Click Save Connection
PowerSync will now deploy and configure an isolated cloud environment, which can take a few minutes.
Learn MoreFor more details on database connections, including provider-specific connection details (Supabase, AWS RDS, MongoDB Atlas, etc.), see Source Database Connection.

4. Define Sync Streams

PowerSync uses Sync Streams to control which data gets synced to which users/devices, using SQL-like queries defined in YAML format. Start with simple auto-subscribed streams that sync data to all users by default:
Learn more: Sync Streams documentation

Deploy Your Configuration

In the PowerSync Dashboard:
  1. Select your project and instance
  2. Go to the Sync Streams view
  3. Edit the YAML directly in the dashboard
  4. Click Deploy to validate and deploy your Sync Streams
Table/collection names in your configuration must match the table names defined in your client-side schema (defined in a later step below).

5. Enable Development Tokens

Development tokens are temporary tokens that let you test sync and connect your app before you set up authentication. Enable them on your instance now. You’ll need them in one of the next steps.
  1. In the PowerSync Dashboard, select your project and instance
  2. Go to the Client Auth view
  3. Check the Development tokens setting and save your changes

6. [Optional] Test Sync

Before implementing the PowerSync Client SDK in your app, you can validate that syncing is working correctly. If you’re on PowerSync Cloud, use Sync Test in the PowerSync Dashboard. If you self-host, generate a development token and use our Sync Diagnostics Client.
  1. In the PowerSync Dashboard, select your project and instance
  2. Go to the Sync Test view
  3. Enter a user ID
  4. Click Connect
Sync Test connects a client in your browser as that user and shows PowerSync DevTools for it. It generates a development token for the user, so you do not need to generate one yourself.
Both tools show the synced data and let you query the client-side SQLite database. The Sync Diagnostics Client shows this information and has a SQL console. In Sync Test, use the DevTools Data Inspector tab.
Checkpoint:Inspect your synced tables in Sync Test or the Sync Diagnostics Client. These should match the Sync Streams you defined previously. This confirms your setup is working correctly before integrating the client SDK into your app.

7. Use the Client SDK

Now it’s time to integrate PowerSync into your app. This involves installing the Client SDK, defining your client-side schema, instantiating the database, connecting to your PowerSync Service instance, and reading/writing data.

Install the Client SDK

Add the PowerSync Client SDK to your app project. PowerSync provides SDKs for various platforms and frameworks.
Add the PowerSync Web NPM package to your project:

Define Your 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. PowerSync Cloud: The easiest way to generate your schema is using the PowerSync Dashboard. Click the Connect button in the top bar to generate the client-side schema based on your Sync Streams in your preferred language. Here’s an example schema for a simple todos table:
Note: The schema does not explicitly specify an id column, since PowerSync automatically creates an id column of type text. PowerSync recommends using UUIDs.
Learn MoreThe client-side schema uses three column types: text, integer, and real. These map directly to values from your Sync Streams and are automatically cast if needed. For details on how backend database types map to SQLite types, see Types.

Instantiate the PowerSync Database

Now that you have your client-side schema defined, instantiate the PowerSync database in your app. This creates the client-side SQLite database that PowerSync keeps in sync with your source database based on your Sync Streams.

Connect to PowerSync Service Instance

Connect your client-side PowerSync database to the PowerSync Service instance you created in step 2 by defining a backend connector and calling connect(). The backend connector handles authentication and uploading mutations to 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.
You can start by connecting and reading synced data. The upload methods in the examples below are placeholders: they mark local writes as uploaded without sending them anywhere, so a write you make reverts after the next sync. When you’re ready to upload writes to your backend, see Choosing Your Setup.
For development, you can use a development token. For production, implement JWT authentication as described in Authentication Setup. First, generate a development token:
  1. In the PowerSync Dashboard, click the Connect button in the top bar
  2. Enter a user ID as the token subject. Your Sync Streams from step 4 sync the same data to all users, so any value works, such as test-user.
  3. Click Generate token and copy the token
Development tokens expire after 12 hours.
Then define a backend connector that returns the token, and call connect():
Once connected, you can read from and write to the client-side SQLite database. PowerSync automatically syncs changes from your source database down into the SQLite database.

Read Data

Read data using SQL queries. The data comes from your client-side SQLite database:
Learn More

Write Data

Write data using SQL INSERT, UPDATE, or DELETE statements. PowerSync automatically queues changes to synced tables. To upload those changes to your backend, implement uploadData() in your backend connector, using one of the setups in Choosing Your Setup.
Best practice: Use UUIDs when inserting new rows on the client side. UUIDs can be generated offline/locally, allowing for unique identification of records created in the client database before they are synced to the server. See Client ID for more details.
Learn MoreFor more details, see the Writing Data page.

Next Steps

For production deployments, you’ll need to:
  1. Implement Authentication: Replace development tokens with proper JWT-based authentication. PowerSync supports various authentication providers including Supabase, Firebase Auth, Auth0, Clerk, and custom JWT implementations.
  2. Set Up Uploads to Your Backend: Choose how your app’s writes reach your source database.

Additional Resources

Questions?

Try “Ask AI” on this site which is trained on all our documentation, repositories and Discord discussions. Also join us on our community Discord server where you can browse topics from the PowerSync community and chat with our team.