Video walkthrough of the integration guide.
- A Supabase account
- A PowerSync Cloud account
- For mobile and desktop apps: Flutter, React Native, Kotlin, or Xcode set up for your platform
- For web apps: pnpm installed
Architecture

Supabase + PowerSync architecture
uploadData() function, which sends queued changes to Supabase through the Supabase client library. For more on how PowerSync works, see the Architecture Overview.
Overview
1
Configure Supabase
- Create a Supabase project
- Create the demo database schema
- Create the PowerSync database user and publication
2
Configure PowerSync
- Connect PowerSync to Supabase
- Configure Supabase Auth
- Configure Sync Streams
3
Run the Demo App
Configure and run the to-do list demo app for your framework, then test sync.
Configure Supabase
Create a Supabase Project
You can use a new or existing project with its default settings.- Web UI
- CLI
In the Supabase Dashboard, create a project.
Create the Demo Database Schema
The demo app uses two tables,lists and todos. Run the following SQL to create them:
Create a PowerSync Database User
PowerSync uses Postgres logical replication to read changes from your database. Run the following SQL to create a Postgres role with replication privileges:SELECT privilege, and for the publication mentioned in the next step (as well as for any other publications that may exist).
Create the Postgres Publication
Run the following SQL to create a Postgres publication:Configure PowerSync
Create a PowerSync Cloud Instance
- Web UI
- CLI
When creating a project in the PowerSync Dashboard, Development and Production instances of the PowerSync Service will be created by default. Select the instance you want to configure.If you need to create a new instance, follow the steps below.
- In the dashboard, select your project and open the instance selection dropdown. Click Add Instance.

- Give your instance a name, such as “Production”.
- [Optional] You can change the default cloud region. Available regions are US, EU, JP (Japan), AU (Australia), BR (Brazil), and IN (India).
- Note: Additional cloud regions will be considered on request, especially for customers on our Enterprise plan. Please contact us if you need a different region.
- Click Create Instance.
Connect PowerSync to Your Supabase
- Web UI
- CLI
- In your Supabase Dashboard, click Connect in the top navigation bar, or open this link.
- Select Direct, keep Direct connection as the connection method, and copy the connection string, including the
[YOUR-PASSWORD]placeholder. - In the PowerSync Dashboard, select your project and instance and go to the Database Connection view.
- Select the Postgres tab.
- Paste the connection string into the URI field. PowerSync fills in the other connection fields from the URI.
- Change Username and Password to the
powersync_roleand password you created when you set up Supabase for PowerSync. See Source Database Setup. - Keep SSL Mode set to
verify-full. PowerSync trusts Supabase’s certificate by default, so you don’t need to add a server certificate. - Click Test Connection and fix any errors.
- Click Save Connection.
Configure Supabase Auth
- Web UI
- CLI
- In the PowerSync Dashboard, go to the Client Auth view.
- Select Use Supabase Auth.
- If your Supabase project uses legacy JWT secrets, copy the JWT secret from your project’s JWT Keys settings into Supabase JWT Secret (optional). If your project uses JWT signing keys, leave this field empty. PowerSync configures your project’s signing keys automatically.
- Click Save and Deploy.
Configure Sync Streams
Sync Streams define which data syncs to which users’ devices. In the demo app, each user syncs their own lists and to-dos. Use the following Sync Config:- Web UI
- CLI
- In the PowerSync Dashboard, select your project and instance and go to the Sync Streams view.
- Replace the contents of the editor with the Sync Config above.
- Click Validate and fix any errors.
- Click Deploy.
Run the Demo App
Clone the Demo App
Clone the to-do list demo app for your framework:Configure the Demo App
Create or open the config file for your framework:- Supabase URL: Your project URL,
https://<project-ref>.supabase.co. Find it in the Supabase Dashboard under Project URL. - Supabase key: Your project’s publishable key, or its legacy anon key. Find it under API Keys, or run
supabase projects api-keys --project-ref <project-ref>. - PowerSync URL: Your instance URL. Click Connect in the top bar of the PowerSync Dashboard and copy it. If you use the CLI, the URL is
https://<instance-id>.powersync.journeyapps.com, where<instance-id>is theinstance_idvalue inpowersync/cli.yaml.
Run the App

The sign-in screen of the Flutter demo app
Optional: Add Sample Data for New Users
If you share the demo app with other people, you can add sample data for each new user, so that they don’t start with an empty screen. The following trigger creates a list with two to-dos when a user signs up. Run it like the other SQL in this guide. See Supabase: Managing User Data.Troubleshooting
Uploads Fail With Error 42501
If changes from the app don’t reach Supabase and your app logs error 42501, the Data API rejected the upload. Check the error message:
permission denied for table: Theauthenticatedrole has no grant on the table. Grant access to each table that your app writes to, for examplegrant select, insert, update, delete on public.lists to authenticated;.new row violates row-level security policy: An RLS policy rejected the write. Check that the row belongs to the signed-in user, for example thatowner_idmatches the user’s ID.
Disk Fills Up on an Idle Project
If your Supabase project’s WAL settings are large for its disk, Postgres can keep a growing amount of write-ahead log (WAL) while PowerSync is connected, even when the database is idle. This can fill the disk, especially on Free plan projects with a small disk. Checkmax_wal_size and max_slot_wal_keep_size with SHOW max_wal_size; and SHOW max_slot_wal_keep_size;. Lower any value that is more than half of your disk size. For example, on a 2 GB disk where both values are 4 GB, set both to 1 GB:
max_slot_wal_keep_size leaves less room for replication lag. If the lag exceeds it, Postgres invalidates PowerSync’s replication slot. See Recovering from an Invalidated Slot.
