Supabase + PowerSync

Build offline-first apps with Supabase and PowerSync across Flutter, React Native, Web, Kotlin, and Swift.

This guide shows you how to configure PowerSync with Supabase. PowerSync syncs your Supabase Postgres database to a local SQLite database on each client, so your app reads and writes locally and stays highly responsive even in poor network conditions.

This guide takes 10-15 minutes to complete.

Note: We are currently investigating an issue with Supabase logical replication where unused/idle instances have excessive WAL growth, resulting in maxed out disk usage. Supabase seem to have updated the default archive_timeout setting to 2 min, which seems to be part of the issue. The current recommendation for pet/hobby projects is to set a smaller max_wal_size and max_slot_wal_keep_size:

supabase --experimental \
  --project-ref <project-ref> \
  postgres-config update --config max_wal_size=1GB

and also:

supabase --experimental \
  --project-ref <project-ref> \
  postgres-config update --config max_slot_wal_keep_size=1GB

Before you start, make sure you have:

• A Supabase account
• A PowerSync Cloud account
• For mobile/desktop apps: Flutter, React Native, Kotlin, or Xcode set up for your platform of choice
• For web apps: pnpm installed

Architecture

Upon successful integration of Supabase + PowerSync, your system architecture will look like this: (click to enlarge image)

The local SQLite database embedded in the PowerSync SDK is automatically kept in sync with the Supabase Postgres database (based on your Sync Streams as you will see later in this guide). Client-side data modifications are persisted in the local SQLite database as well as stored in an upload queue that gets processed via the Supabase client library when network connectivity is available. Therefore reads and writes can happen in the app regardless of whether the user is online or offline, by using the local SQLite database.

For more details on PowerSync’s general architecture, see here.

Integration Guide/Tutorial Overview

We will follow these steps to get an offline-first ‘To-Do List’ demo app up and running:

1. Configure Supabase:

   • Create the demo database schema
   • Create the Postgres user and publication
2. Configure PowerSync:

   • Create connection to Supabase
   • Configure Sync Streams
3. Test the configuration

   Test the configuration using our provided PowerSync-Supabase ‘To-Do List’ demo app with your framework of choice.

Configure Supabase

Create a new Supabase project (or use an existing project if you prefer) and follow the below steps.

Before You Start: Project Creation Settings

When you create a new Supabase project, two settings on the project creation screen affect how the demo app behaves. Reviewing them now saves debugging later.

Automatically expose new tables and functions

This controls whether tables you create in the public schema are reachable via the Supabase Data API. The Data API is the auto-generated REST and GraphQL layer that the Supabase client libraries (such as supabase-js) call. In this integration, PowerSync handles the download path by replicating data from Postgres to client SQLite databases, but client writes still go back to Postgres through the Data API using supabase-js. If the tables are not exposed, the demo app cannot write changes back to your database. Supabase is rolling out a new default:

• From April 28, 2026: the setting is available as an opt-in. New projects can choose to require explicit grant statements.
• From May 30, 2026: the new default for all new projects is that tables in public are not exposed to the Data API on creation.
• From October 30, 2026: the new default is enforced on all existing projects.

The schema SQL in this guide includes explicit grant statements, so the demo app works under either default. See this for more details.

Enable automatic RLS

This adds an event trigger that automatically enables Row Level Security on every new table created in the public schema. Enabling it is recommended because RLS is the authoritative security layer for any writes that reach Postgres through the Data API. If you leave it disabled, you can still enable RLS per table as the schema SQL in this guide does.

Without RLS, any user with the anon or authenticated key can read and write every row in the table, regardless of who created it.

Create the Demo Database Schema

To set up the Postgres database for our To-Do List demo app, we will create two new tables: lists and todos. The demo app will have access to these tables even while offline.

Run the below SQL statements in your Supabase SQL Editor:

create table
  public.lists (
    id uuid not null default gen_random_uuid (),
    created_at timestamp with time zone not null default now(),
    name text not null,
    owner_id uuid not null,
    constraint lists_pkey primary key (id),
    constraint lists_owner_id_fkey foreign key (owner_id) references auth.users (id) on delete cascade
  ) tablespace pg_default;

create table
  public.todos (
    id uuid not null default gen_random_uuid (),
    created_at timestamp with time zone not null default now(),
    completed_at timestamp with time zone null,
    description text not null,
    completed boolean not null default false,
    created_by uuid null,
    completed_by uuid null,
    list_id uuid not null,
    constraint todos_pkey primary key (id),
    constraint todos_created_by_fkey foreign key (created_by) references auth.users (id) on delete set null,
    constraint todos_completed_by_fkey foreign key (completed_by) references auth.users (id) on delete set null,
    constraint todos_list_id_fkey foreign key (list_id) references lists (id) on delete cascade
  ) tablespace pg_default;

-- Grant Data API access so supabase-js can read and write these tables.
grant select, insert, update, delete on public.lists to authenticated;
grant select, insert, update, delete on public.todos to authenticated;
grant select, insert, update, delete on public.lists to service_role;
grant select, insert, update, delete on public.todos to service_role;

-- Enable Row Level Security and add policies so each user can only access their own data.
alter table public.lists enable row level security;
alter table public.todos enable row level security;

create policy "owned lists" on public.lists
  for all to authenticated
  using (auth.uid() = owner_id);

create policy "todos in owned lists" on public.todos
  for all to authenticated
  using (
    auth.uid() in (
      select lists.owner_id from public.lists where lists.id = todos.list_id
    )
  );

Grants and RLS do different jobs, and you need both. Grants control which Postgres roles can touch a table through the Data API. Without a grant, supabase-js returns a 42501: permission denied for table error before RLS is ever evaluated. RLS runs after the grant succeeds and filters which rows that role can read or modify. Skipping RLS means any user with the anon or authenticated key can read and write every row.

This guide grants authenticated because the demo app requires sign-in. The anon role is intentionally left ungranted. If you wanted to expose a table for public read-only access (for example, a shared catalog visible to signed-out users), you would add grant select on public.your_table to anon along with an RLS policy scoping which rows anon can read.

PowerSync’s Sync Streams (configured later in this guide) control which rows get downloaded to each client and generally mirror your RLS setup. For more on how these work together, see RLS and Sync Streams.

Create a PowerSync Database User

PowerSync uses the Postgres Write Ahead Log (WAL) to replicate data changes in order to keep PowerSync SDK clients up to date.

Run the below SQL statement in your Supabase SQL Editor to create a Postgres role/user with replication privileges:

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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 below SQL statement in your Supabase SQL Editor to create a Postgres publication:

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

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 / Sync Rules definitions. 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.

2. Give your instance a name, such as “Production”.
3. [Optional] You can change the default cloud region from US to EU, JP (Japan), AU (Australia) or BR (Brazil) if desired.
   • 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.
4. Click Create Instance.

Connect PowerSync to Your Supabase

1. From your Supabase Dashboard, select Connect in the top navigation bar (or follow this link):

   

2. In the Direct connection section, copy the complete connection string (including the [YOUR-PASSWORD] placeholder):

   

3. In the PowerSync Dashboard, select your project and instance and go to Database Connections.

4. Click Connect to Source Database and ensure the Postgres tab is selected.

5. Paste the connection string into the URI field. PowerSync will automatically parse this URI to populate the database connection details.

6. Update the Username and Password fields to use the powersync_role and password you created when configuring your Supabase for PowerSync (see Source Database Setup).

7. Note: PowerSync includes Supabase’s CA certificate by default, so you can use verify-full SSL mode without additional configuration.

7. Verify your setup by clicking Test Connection and resolve any errors.
8. Click Save Connection.

PowerSync will now create an isolated cloud environment for your instance. This typically takes a minute or two.

Enable Supabase Auth

After your database connection is configured, enable Supabase Auth:

1. In the PowerSync Dashboard, go to Client Auth for your instance.
2. Enable the Use Supabase Auth checkbox.
3. If your Supabase project uses the legacy JWT signing keys, copy your JWT Secret from your Supabase project’s settings (JWT Keys) and paste the secret into the Supabase JWT Secret (optional) Legacy field in the PowerSync Dashboard. If you’re using Supabase’s new JWT signing keys, you can leave this field empty (PowerSync will auto-configure the JWKS endpoint for your project).
4. Click Save and Deploy to apply the changes.

Configure Sync Streams

Sync Streams (or legacy Sync Rules) allow developers to control which data gets synced to which user devices using a SQL-like syntax in a YAML file. For the demo app, we’re going to specify that each user can only see their own to-do lists and list items.

1. In the PowerSync Dashboard, select your project and instance and go to the Sync Streams view (shown as Sync Rules if using legacy Sync Rules).

2. Edit the Sync Streams in the editor and replace the contents with the below:

Sync Streams (Recommended)

config:
  edition: 3
streams:
  user_data:
    auto_subscribe: true
    queries:
    - SELECT * FROM lists WHERE owner_id = auth.user_id()
    - SELECT todos.* FROM todos INNER JOIN lists ON todos.list_id = lists.id WHERE lists.owner_id = auth.user_id()
    

Sync Rules (Legacy)

bucket_definitions:
  user_lists:
    # Separate bucket per To-Do list
    parameters: select id as list_id from lists where owner_id = request.user_id()
    data:
      - select * from lists where id = bucket.list_id
      - select * from todos where list_id = bucket.list_id

3. Click “Validate” and ensure there are no errors. This validates your Sync Config against your Postgres database.
4. Click “Deploy” to deploy your Sync Config.

• For additional information on PowerSync’s Sync Streams, refer to the Sync Streams documentation.
• For legacy Sync Rules, refer to the Sync Rules documentation.
• If you’re wondering how Sync Streams relate to Supabase Postgres RLS, see this subsection.

Test Everything (Using Our Demo App)

In this step you’ll test your setup using a ‘To-Do List’ demo app provided by PowerSync.

Clone the Demo App

Clone the demo app based on your framework:

Flutter

git clone https://github.com/powersync-ja/powersync.dart.git
cd powersync.dart/demos/supabase-todolist/

Configure the Demo App to Use Your PowerSync Instance

Locate the relevant config file for your framework:

Flutter

cp lib/app_config_template.dart lib/app_config.dart

# Edit `lib/app_config.dart` and insert the necessary credentials as detailed below.

Supabase has replaced the legacy anon key with publishable keys (prefixed sb_publishable_…) by default on new projects. The demos still read environment variables named SUPABASE_ANON_KEY / supabaseAnonKey, but the value is interchangeable: paste your publishable key into the same variable. Existing projects that still use legacy JWT keys can continue to use the anon key directly.

1. In the relevant config file, replace the values for supabaseUrl (from the Project URL section in the Supabase dashboard) and supabaseAnonKey (from the API Keys section in the Supabase dashboard).
2. For the value of powersyncUrl, click Connect in the top bar of the PowerSync Dashboard and copy the instance URL from the dialog.

Run the App

Flutter

# Ensure you have [melos](https://melos.invertase.dev/~melos-latest/getting-started) installed.

melos bootstrap
flutter run

For ease of use of the demo app, you can disable email confirmation in your Supabase Auth settings. In your Supabase project, go to “Authentication” -> “Providers” -> “Email” and then disable “Confirm email”. If you keep email confirmation enabled, the Supabase user confirmation email will reference the default Supabase Site URL of http://localhost:3000 — you can ignore this.

Once signed in to the demo app, you should see a blank list of to-do lists, so go ahead and create a new list. Try placing your device into airplane mode to test out the offline capabilities. Once the device is back online, you should see the data automatically appear in your Supabase dashboard (e.g. in the Table Editor).

For more information, explore the PowerSync docs or join us on our community Discord where our team is always available to answer questions.

Bonus: Optional Extras

If you plan on sharing this demo app with other people, you may want to set up demo data triggers so that new user signups don’t see an empty screen.

It’s useful to have some data when a user signs up to the demo app. The below trigger automatically creates some sample data when a user registers (you can run it in the Supabase SQL Editor). See Supabase: Managing User Data for more details.

create function public.handle_new_user_sample_data()
returns trigger as $$
declare
  new_list_id uuid;
begin
  insert into public.lists (name, owner_id)
    values ('Shopping list', new.id)
    returning id into new_list_id;

  insert into public.todos(description, list_id, created_by)
    values ('Bread', new_list_id, new.id);

  insert into public.todos(description, list_id, created_by)
    values ('Apples', new_list_id, new.id);

  return new;
end;
$$ language plpgsql security definer;

create trigger new_user_sample_data after insert on auth.users for each row execute procedure public.handle_new_user_sample_data();