Supabase + PowerSync

Tutorial-style integration guide for creating offline-first apps with Supabase and PowerSync, using a demo to-do list app in Flutter, React Native or JS Web.

Used in conjunction with Supabase, PowerSync enables developers to build offline-first apps that are robust in poor network conditions and that have highly responsive frontends while relying on Supabase for their backend. This guide provides instructions for how to configure PowerSync for use with your Supabase project.

Before you proceed, this guide assumes that you have already signed up for free accounts with both Supabase and PowerSync. If you haven't signed up for a PowerSync account yet, click here (and if you haven't signed up for Supabase yet, click here).

For mobile/desktop apps, this guide assumes that you already have Flutter / React Native set up.

For web apps, this guide assumes that you have pnpm installed.

This guide takes 10-15 minutes to complete.

Architecture

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

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:

Configure Supabase:
- Create the demo database schema
- Create the Postgres publication
Configure PowerSync:
- Create connection to Supabase
- Configure Sync Rules
Test the configuration using our provided PowerSync-Supabase 'To-Do List' demo app.

Configure Supabase

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

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: (if you get a warning about a "potentially destructive operation", that's a false positive that you can safely ignore.)

--hover to copy

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;

Create the Postgres Publication

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:

-- Create publication for powersync
create publication powersync for table public.lists, public.todos;

Note: this guide uses the default postgres user in your Supabase account for replicating changes to PowerSync, since elevating custom roles to replication has been disabled in Supabase. If you want to use a custom role for this purpose, contact the Supabase support team.

Configuring PowerSync

Connect PowerSync to Your Supabase

In the PowerSync dashboard Project tree, click on "Create new instance":

Give your instance a name, such as "Supabase Testing".
Under the "General" tab, you can change the default cloud region from US to EU or JP if desired (more cloud regions are available, contact us if you need a different region).
Under the "DB Connections" tab, click on the + icon.
Now we get the connection details from Supabase:
- In your Supabase dashboard, navigate to "Project Settings" -> "Database" -> "Connection string" and select the "URI" tab.
- Uncheck the "Display connection pooler" checkbox. PowerSync needs to connect to the database directly and cannot use the pooler.
- Copy the connection string. The hostname should be db.<PROJECT-ID>.supabase.co, and not, for example, aws-0-us-west-1.pooler.supabase.com.
- Paste this URI in PowerSync instance URI field.
- Enter the password for the postgres user in your Supabase database: (Supabase also refers to this password as the database password or project password).
- PowerSync has the Supabase CA certificate pre-configured — verify-full SSL mode can be used directly, without any custom certificates.
Click "Test Connection" and fix any errors.
Under the "Client Auth" tab, enable "Use Supabase Auth".
Click "Save".

PowerSync deploys and configures an isolated cloud environment for you, which will take a few minutes to complete.

Configure Sync Rules

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. To update your sync rules, open the sync-rules.yaml file.

Replace the sync-rules.yaml file's contents with the below:

# hover to copy

bucket_definitions:
  user_lists:
    # Separate bucket per todo list
    parameters: select id as list_id from lists where owner_id = token_parameters.user_id
    data:
      - select * from lists where id = bucket.list_id
      - select * from todos where list_id = bucket.list_id

In the top right, click "Validate sync rules" and ensure there are no errors. This validates your sync rules against your Postgres database.
In the top right, click "Deploy sync rules" and select your instance
Confirm in the dialog and wait a couple of minutes for the deployment to complete.

For additional information on PowerSync's sync rules, refer to the Sync Rules documentation.

If you're wondering how Sync Rules 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:

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

git clone https://github.com/powersync-ja/powersync-js.git
cd powersync-js/demos/react-native-supabase-todolist

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

Configure the demo app to use your PowerSync instance

Locate the relevant config file for your framework:

cp lib/app_config_template.dart lib/app_config.dart

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

Edit the .env file and insert the necessary credentials as detailed below.

cp .env.local.template .env.local

Edit .env.local and insert the necessary credentials as detailed below.

In the relevant config file, replace the values for supabaseUrl and supabaseAnonKey (you can find these under "Project Settings" -> "API" in your Supabase dashboard — under the "URL" section, and anon key under "Project API keys")
For the value of powersyncUrl, follow these steps:
1. In the project tree on the PowerSync dashboard, right click on the instance you created earlier:
2. Click "Edit instance"
3. Click on "Instance URL" to copy the value:

Run the app

Ensure you have melos installed.

melos bootstrap
flutter run

Run

yarn install

To run on iOS:

yarn ios

To run on Android:

yarn android

In the repo directory:

pnpm install
pnpm build:packages

In demos/react-supabase-todolist:

pnpm dev

You should now see the demo app running.

The demo app requires you to sign up first and then log in (this uses Supabase Auth).

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 ofhttp://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();

PreviousIntegrations Overview NextHandling Attachments

Last updated 6 days ago