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.- Postgres
- MongoDB Atlas
- Azure DocumentDB
- MySQL
- SQL Server
- Convex
Configuring Postgres for PowerSync involves three main tasks:
- Enable logical replication: PowerSync reads the Postgres write-ahead log (WAL) using logical replication. Set
wal_level = logicalin your Postgres configuration. - Create a PowerSync database user: Create a role with replication privileges and read-only access to your tables.
- Create a
powersyncpublication: Create a logical replication publication namedpowersyncto specify which tables to replicate.
PowerSync requires Postgres version 11 or greater.
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).- Dashboard (Cloud)
- CLI (Cloud)
- CLI (Self-Hosted)
- Manual (Self-Hosted)
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.- Dashboard (Cloud)
- CLI (Cloud)
- CLI (Self-Hosted)
- Manual (Self-Hosted)
In the PowerSync Dashboard, select your project and instance, then go to Database Connection:
- Select the appropriate database type tab (Postgres, MongoDB, MySQL, SQL Server or Convex). For Azure DocumentDB, select MongoDB.
- 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
- Click Test Connection to verify
- Click Save 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:Deploy Your Configuration
- Dashboard (Cloud)
- CLI (Cloud)
- CLI (Self-Hosted)
- Manual (Self-Hosted)
In the PowerSync Dashboard:
- Select your project and instance
- Go to the Sync Streams view
- Edit the YAML directly in the dashboard
- 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.- Dashboard (Cloud)
- CLI (Cloud)
- Self-Hosted
- In the PowerSync Dashboard, select your project and instance
- Go to the Client Auth view
- 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.- PowerSync Cloud
- Self-Hosted
- In the PowerSync Dashboard, select your project and instance
- Go to the Sync Test view
- Enter a user ID
- Click Connect
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.- JavaScript Web
- React Native / Expo
- Node.js
- Capacitor
- Tauri
- Dart/Flutter
- Kotlin
- Swift
- .NET
- Rust
Add the PowerSync Web NPM package to your project:
- npm
- yarn
- pnpm
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 simpletodos 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.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 callingconnect(). The backend connector handles authentication and uploading mutations to your backend.
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.
- Dashboard (Cloud)
- CLI (Cloud)
- Self-Hosted
- In the PowerSync Dashboard, click the Connect button in the top bar
- 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. - Click Generate token and copy the token
Development tokens expire after 12 hours.
connect():
Read Data
Read data using SQL queries. The data comes from your client-side SQLite database:Write Data
Write data using SQLINSERT, 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.
Next Steps
For production deployments, you’ll need to:- 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.
- Set Up Uploads to Your Backend: Choose how your app’s writes reach your source database.
Additional Resources
- Learn more about Sync Streams for controlling partial syncing.
- Explore Live Queries / Watch Queries for reactive UI updates.
- Check out Example Projects for complete implementations.
- Review the Client SDK References for client-side platform-specific details.
