Supabase + PowerSync

Used in conjunction with Supabase, PowerSync enables developers to build local-first & 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.

​

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 configured sync rules 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.

​

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 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.)

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;

​

Configuring PowerSync

​

Create a PowerSync Cloud Instance

1. In the PowerSync Dashboard Project tree, click on “Create new instance”:

2. Give your instance a name, such as “Testing”.
3. Under the “General” tab, you can change the default cloud region from US to EU, JP (Japan), or AU (Australia) if desired.
   • Note: More cloud regions are available, contact us if you need a different region.
4. Under the “DB Connections” tab, click on the + icon and select your database technology.

​

Connect PowerSync to Your Supabase

1. In your Supabase Dashboard, click Connect in the top bar:

   • Under Direct connection, 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.

2. Click Test Connection and fix any errors.

3. Under the Client Auth tab, enable Use Supabase Auth and enter your Supabase JWT Secret:

4. Click Save and deploy to deploy the updates to your instance.

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.

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

bucket_definitions:
  user_lists:
    # Separate bucket per todo 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

1. In the top right, click “Validate sync rules” and ensure there are no errors. This validates your sync rules against your Postgres database.
2. In the top right, click “Deploy sync rules” and select your Instance

3. 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:

​

Configure the demo app to use your PowerSync instance

Locate the relevant config file for your framework:

1. 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”)
2. For the value of powersyncUrl, click the copy icon on your instance to copy its URL:

​

Run the app

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();