Skip to main content
This guide shows you how to set up PowerSync with Supabase and run a to-do list demo app. The app reads and writes a local SQLite database, so it responds instantly and keeps working without a network connection.
Try our new guided Supabase setup in the PowerSync Dashboard. It configures your Supabase project and PowerSync Cloud instance for you.Look for the Set Up with Supabase button in your instance’s Health or Database Connection view, then follow the on-screen steps.
Using Supabase? banner with a Set Up with Supabase button.

The Set Up with Supabase button in the PowerSync Dashboard

To set up Supabase manually instead, follow the steps below.
If you use guided setup, still follow this guide to create the demo schema, configure Sync Streams, and run the demo app. Tips mark the steps that guided setup replaces.

Video walkthrough of the integration guide.

Before you start, make sure you have:
  • 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

Diagram of the PowerSync Service syncing data from Supabase Postgres to SQLite in the app, and the app uploading writes to Supabase through the Supabase client library

Supabase + PowerSync architecture

The PowerSync Service replicates data from Supabase Postgres and syncs it to each client’s SQLite database, based on your Sync Streams. When the app writes to SQLite, the PowerSync SDK also adds the change to an upload queue. While the device is online, the SDK calls the app’s 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.
In the Supabase Dashboard, create a project.
Each of the following steps runs SQL. Run it in the Supabase SQL Editor, or save it to a file and run it with the Supabase CLI:

Create the Demo Database Schema

The demo app uses two tables, lists and todos. Run the following SQL to create them:
Sync Streams, which you configure later, control which rows sync to each client. They usually mirror your RLS policies. See RLS and Sync Streams.

Create a PowerSync Database User

Using guided Supabase setup in the Dashboard? Skip this step and the next one. Guided setup creates the database user and publication for you. Continue at Create a PowerSync Cloud Instance.
PowerSync uses Postgres logical replication to read changes from your database. Run the following SQL to create a Postgres role with replication privileges:
To restrict read access to specific tables, explicitly list allowed tables for both the 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:
Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.
The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Configure PowerSync

Create a PowerSync Cloud Instance

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.
  1. In the dashboard, select your project and open the instance selection dropdown. Click Add Instance.
  1. Give your instance a name, such as “Production”.
  2. [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.
  3. Click Create Instance.

Connect PowerSync to Your Supabase

Using guided Supabase setup in the Dashboard? Run it now instead of the steps below. Click Set Up with Supabase in your instance’s Health or Database Connection view and follow the on-screen steps. Then continue at Configure Sync Streams.
  1. In your Supabase Dashboard, click Connect in the top navigation bar, or open this link.
  2. Select Direct, keep Direct connection as the connection method, and copy the connection string, including the [YOUR-PASSWORD] placeholder.
  3. In the PowerSync Dashboard, select your project and instance and go to the Database Connection view.
  4. Select the Postgres tab.
  5. Paste the connection string into the URI field. PowerSync fills in the other connection fields from the URI.
  6. Change Username and Password to the powersync_role and password you created when you set up Supabase for PowerSync. See Source Database Setup.
  7. Keep SSL Mode set to verify-full. PowerSync trusts Supabase’s certificate by default, so you don’t need to add a server certificate.
  8. Click Test Connection and fix any errors.
  9. Click Save Connection.
PowerSync now creates an isolated cloud environment for your instance. This typically takes a minute or two.

Configure Supabase Auth

  1. In the PowerSync Dashboard, go to the Client Auth view.
  2. Select Use Supabase Auth.
  3. 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.
  4. 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:
  1. In the PowerSync Dashboard, select your project and instance and go to the Sync Streams view.
  2. Replace the contents of the editor with the Sync Config above.
  3. Click Validate and fix any errors.
  4. 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:
Set these values in the config file:
  • 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 the instance_id value in powersync/cli.yaml.

Run the App

To sign up without confirming your email address, turn off Confirm email in your Supabase project under Authentication > Sign In / Providers.
Flutter demo app sign-in screen with email and password fields

The sign-in screen of the Flutter demo app

Sign up and create a list. Then put your device in airplane mode and add a to-do. When the device is back online, the SDK uploads the queued changes, and they appear in the Supabase Dashboard’s Table Editor. If you run into problems, ask us on Discord.

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: The authenticated role has no grant on the table. Grant access to each table that your app writes to, for example grant 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 that owner_id matches the user’s ID.
The demo schema SQL shows both the grants and the RLS policies.

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. Check max_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:
To change only one setting, pass only that key. The command restarts your database, so expect a brief interruption. A lower 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.

Unused Replication Slots

If you stop or deprovision your PowerSync instance, its replication slot stays in your Supabase database and keeps WAL. Drop slots that you no longer need. See Logical Replication Slots.