FlutterFlow + PowerSync

​

Guide Overview

1. Configure Supabase and PowerSync Prerequisites
2. Initialize Your FlutterFlow Project
3. Build a Sign-in Screen
4. Read Data
5. Create Data
6. Update Data (Guide coming soon)
7. Delete Data
8. Sign Out
9. (New) Display Connectivity and Sync Status
10. Secure Your App
11. Enable RLS in Supabase
12. Update Sync Rules in PowerSync

​

Configure Supabase

1. Create a new project in Supabase.
2. To set up the Postgres database for our demo app, we will create a lists table. The demo app will have access to this table even while offline. Run the below SQL statement 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
   
3. 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).
4. Create a Postgres publication using the SQL Editor. This will enable data to be replicated from Supabase so that your FlutterFlow app can download it.
   -- 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. 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

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. You can’t change the region after you create the instance. See Regions for details.
4. Click Create Instance.

​

Connect PowerSync to Your Supabase

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.

​

Enable 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 Rules

1. In the PowerSync Dashboard, select your project and instance and go to the Sync Rules view.
2. Edit the Sync Rules in the editor and replace the contents with the below:
   # This will sync the entire table to all users - we will refine this later
   bucket_definitions:
      global:
         data:
               - SELECT * FROM lists
   
3. Click “Validate” and ensure there are no errors. This validates your Sync Rules against your Postgres database.
4. Click “Deploy” to deploy your Sync Rules.
5. Confirm in the dialog and wait a couple of minutes for the deployment to complete.

​

Initialize Your FlutterFlow Project

1. Create a new Blank project in FlutterFlow.
2. Under “App Settings” -> “Integrations”, enable “Supabase”.
   1. Enter your Supabase “API URL” and public “Anon Key”. You can find these under “Project Settings” -> “API Keys” -> anon public in your Supabase dashboard.
   2. Click “Get Schema”.
3. Add the PowerSync Library to your FlutterFlow account.
4. Under “App Settings” -> “Project Dependencies” -> “FlutterFlow Libraries” click “Add Library”.
   1. Select the “PowerSync” library.
   2. Add your schema:
      1. In the PowerSync Dashboard, select your project and instance and click the Connect button in the top bar to generate the client-side schema based on your Sync Rules. Select “FlutterFlow” as the language.
      
      2. Copy and paste the generated schema into the “PowerSyncSchema” field.
   3. Copy and paste your PowerSync instance URL into the “PowerSyncUrl” field.
   
   4. Note: The default path for the “HomePage” field under “Library Pages” can be left as is and ignored. FlutterFlow does not currently provide a way to remove it.
   5. Close the library config.
5. Under “Custom Pub Dependencies”, add a dependency on powersync_core:1.3.0:

​

Build A Sign-In Screen

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.
   
2. Select the “Auth 1” template and name the page Login.
3. Delete the Sign Up, Forgot Password and Social Login buttons — we will only be supporting Sign In for this demo app.

4. Under “App Settings” -> “App Settings” -> “Authentication”:
   1. Enable Authentication.
   2. Set “Authentication Type” to “Supabase”.
   3. Set “Entry Page” to the Login page you just created.
   4. Set “Logged In Page” to “HomePage”.

5. In your Supabase Dashboard, under “Authentication”, click on “Add User” -> “Create new user” and create a user for yourself to test with:

6. Test your app with test mode:

Checkpoint: You should now be able to log into the app using the Supabase user account you just created. After logging in you should see a blank screen.

​

Read Data

1. Auto-updating queries for Layout Elements with Dynamic Children e.g. the ListView Element
   • This uses the library’s PowerSyncQuery component.
2. Auto-updating queries for basic Layout Elements e.g. Text Elements.
   • This uses the library’s PowerSyncStateUpdater component.
3. Once-off reads for static data.
   • This uses the library’s PowerSyncQueryOnce custom action.

​

Prepare Supabase Tables for Reads

1. Navigate to “Custom Code” and add a Custom Function.
2. Name the function supabaseRowsToList (if your Supabase table name is “Customers”, you would name this supabaseRowsToCustomers).
3. Under Function Settings on the right, set the “Return Value” to Supabase Row
   1. Check “Is List”.
   2. Uncheck “Nullable”.
   3. Under “Table Name”, select lists.
4. Also under Function Settings, click “Add Arguments”.
   1. Set its “Name” to supabaseRows
   2. Set its “Type” to “JSON”.
   3. Check “Is List”.
   4. Uncheck “Nullable”.
5. In the Function Code, paste the following code:
   /// MODIFY CODE ONLY BELOW THIS LINE
   return supabaseRows.map((r) => ListsRow(r)).toList();
   
6. Click “Save Function”.

​

1. Auto-Updating Queries for Layout Elements with Dynamic Children

​

Create a Component to Display List Items

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.
2. Select the “New Component” tab.
3. Select “Create Blank” and call the component ListItems.
4. Under the “Widget Palette”, drag a “ListView” widget into the ListItems component.
5. Still under the “Widget Palette”, drag a “ListTile” into the ListView widget.

   

6. Under the “Widget Tree”, select the ListItems component.
   1. At the top right under “Component Parameters” click “Add Parameters”.
   2. Click “Add Parameter”.
   3. Set its “Name” to lists.
   4. Set its “Type” to Supabase Row.
   5. Check “Is List”.
   6. Under “Table Name”, select lists.
   7. Click “Confirm”.
7. Still under the “Widget Tree”, select the “ListView” widget.
   1. Select the “Generate Dynamic Children” panel on the right.
   2. Set the “Variable Name” to listItem.
   3. Set the “Value” to the component parameter created in the previous step (lists).
   4. Click “Confirm”.
   5. Click “Save”.
   6. Click “Ok” when being prompted about the widget generating its children dynamically.

   

8. Still under the “Widget Tree”, select the ListTile widget.
   1. In the “Properties” panel on the right, under “Title”, click on the settings icon next to “Text”.
   2. Set as “listItem Item”.
   3. Under “Available Options”, select “Get Row Field”.
   4. Under “Supabase Row Fields”, select “name”.
   5. Click “Confirm”.

   

9. Repeat Step 8 above for the “Subtitle”, setting it to “created_at”.

​

Display the List Component and Populate it with Data

1. Under the “Page Selector”, select your HomePage.
2. Under the “Widget Palette”, select the “Components and custom widgets imported from library projects” panel.
   
3. Drag the PowerSyncQuery library component into your page.
4. In the Properties panel on the right, under “Component Parameters” -> “child”:
   
   1. Click on “Unknown”.
   2. Select ListItems we previously created.
   3. Click on lists.
   4. Set the “Value” to “Custom Functions” -> supabaseRowsToList we created previously.
   5. Under the supabaseRows argument, set the “Value” to “Widget Builder Parameters” -> rows.
   6. Click “Confirm”.
   7. Click “Confirm”.
5. Still under “Component Parameters” add the SQL query to fetch all list items from the SQLite database:
   1. Paste the following into the “sql [String]” field: select * from lists order by created_at;
   2. For this query there are no parameters - this will be covered further down in the guide.
6. Still under “Component Parameters”, check “watch [Boolean]”. This ensures that the query auto-updates.

​

Test Your App

1. Check that there are no project issues or errors.
2. Reload your app or start another test session.
3. Notice that your homepage is still blank. This is because the lists table is empty in Supabase. Create a test row in the table by clicking on “Insert” -> “Insert Row” in your Supabase Table Editor.
   1. Leave id and created_at blank.
   2. Enter a name such as “Test from Supabase”.
   3. Click “Select Record” for owner_id and select your test user.

Checkpoint: You should now see your single test row magically appear in your app:

​

2. Auto-Updating Queries for Basic Layout Elements

​

Create a Page Parameter

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.

2. Create a blank page and name it Todos.
3. Under the “Widget Tree”, select your Todos page.
4. At the top right of the “Properties” panel on the right, click on the plus icon for Page Parameters.
5. Click “Add Parameter”.
6. Set the “Parameter Name” to id.
7. Set the “Type” to “String”.
8. Click “Confirm”.

​

Create a Local Page State Variable

1. Still in the “Widget Tree” with the Todos page selected:
2. Select the “State Management Panel” on the right.

3. Click on “Add Field”.
4. Set “Field Name” to list.
5. Set the “Type” to “Supabase Row”.
6. Under “Table Name”, select lists.
7. Click “Confirm”.

​

Bind the Page Title to the Page State

1. Under the “Widget Palette”, select the “Components and custom widgets imported from library projects” panel.
   
2. Drag the PowerSyncStateUpdater library component into your page.
3. Under the “Widget Tree”, select the PowerSyncStateUpdater component.
4. In the “Properties” panel on the right, under “Component Parameters”:
   1. Add the SQL query to fetch the selected list from the SQLite database. Paste the following into the “sql [String]” field: select * from lists where id = :id;
   2. Click on “parameters [Json]” select “Create Map (JSON)” as the variable.
      1. Under “Add Map Entries”, click “Add Key Value Pair”.
      2. Set the “Key” to id.
      3. Set the “Value” to the page parameter created previously called id.
      4. Check “watch [Boolean]”. This ensures that the query auto-updates.
      5. Click “Confirm”.
      
5. Still under “Component Parameters”, configure the onData action:
   1. Open the “Action Flow Editor”.
   2. Select the “Callback” trigger type.
   3. Click “Add Action”.
   4. Search for “update page” and select “Update Page State”.
   5. Click “Add Field”.
   6. Select your list page state variable.
   7. Set “Select Update Type” to “Set Value”.
   8. Set “Value to set” to “Custom Functions” -> supabaseRowsToList.
   9. Set the “Value” to “Callback Parameters” -> rows
   10. Click “Confirm”.
   11. Under “Available Options”, select “Item at Index”.
   12. Set “List Index Options” to “First”
   13. Click “Confirm”.
   
   14. Close the Action Flow Editor.
6. Still under the “Widget Tree”, select the “AppBar” -> “Text” widget.
   1. In the “Properties” panel on the right, click on settings icon next to “Text”.
   2. Click on “Page State” -> “List”.
   3. Set “Supabase Row Fields” to “name”.
   4. (Optional) Set the “Default Variable Value” to List Name.
   5. Click “Confirm”.

​

Make the ListView Component Clickable

1. Under the “Page Selector”, select your ListItems component.
2. Under the “Widget Tree”, select the ListTile widget.
3. In the “Actions” panel on the right, click “Add Action”. “On Tap” should be selected by default.
4. In the “Navigation” subsection, select “Navigate To”.
5. Select the “Todos” page.
6. Under “Parameters” click “Pass”.
7. “id” should be auto-selected, click on it.
8. Click on the settings icon next to “Value”
9. Set it to “listItem Item”.
10. Under “Available Options” select “Get Row Field”
11. Under “Supabase Row Fields” select “id”.
12. Click “Confirm”.
13. (Optional) Enable the back button to navigate back:
    1. Under the “Page Selector”, select your Todos page.
    2. Under the “Widget Tree”, select the “AppBar” component.
    3. In the “Properties” panel on the right, enable “Show Default Button”.

​

Test Your App

Checkpoint: You should now be able to click on a list item and it should navigate you to a new page showing the name of the list in the title bar:

​

3. Once-Off Reads for Static Data

​

Create Data

1. Under the “Page Selector”, select your HomePage page.
2. Under the “Widget Palette”, search for “float” and drag the “FAB” widget onto your page.
3. In the “Actions” panel on the right, click “Add Action”.
   1. Under “Custom Action” -> “PowerSync”, select powersyncWrite.
   2. Under the “Set Action Arguments” -> “sql” section, add the SQL query to create a new list item. For the purpose of this guide we are hardcoding the list’s name, normally you would build UI for this.
      1. Paste the following into the “Value” field: INSERT INTO lists(id, created_at, name, owner_id) VALUES(uuid(), datetime(), 'new item', :userId);
   3. Under the “parameters” section, set the userId parameter we’re using the above query:
      1. Click on “UNSET”.
      2. Select “Create Map (JSON)” as the variable.
      3. Under “Add Map Entries”, click “Add Key Value Pair”.
      4. Set the “Key” to userId.
      5. Set the “Value” to “Authenticated User” -> “User ID”.
      6. Click “Confirm”.

Checkpoint: Reload your app and click on the + floating action button. A new list item should appear, which also automatically syncs to Supabase:

​

Update Data

​

Delete Data

1. Under the “Page Selector”, select your ListItems component.
2. Under the “Widget Tree”, select the ListTile widget.
3. In the “Properties” panel on the right, enable “Slidable”.
4. Click “Open Slidable”.
5. Select the “SlidableActionWidget”.
   
6. In the “Actions” panel on the right, click “Add Action”.
   1. Under “Custom Action” -> “PowerSync”, select powersyncWrite.
   2. Under the “Set Action Arguments” -> “sql” section, add the SQL query to delete the list item.
      1. Paste the following into the “Value” field: delete from lists where id = :id;
   3. Under the “parameters” section, set the id parameter we’re using the above query:
      1. Click on “UNSET”.
      2. Select “Create Map (JSON)” as the variable.
      3. Under “Add Map Entries”, click “Add Key Value Pair”.
      4. Set the “Key” to id.
      5. Set the “Value” to “listItem Item”.
      6. Under “Available Options” select “Get Row Field”.
      7. Under “Supabase Row Fields” select “id”.
      8. Click “Confirm”.
      9. Click “Confirm”.

​

Sign Out

1. Navigate to “Custom Code” and create a new Custom Action called signOut without Arguments or Return Values and paste the below code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import "package:power_sync_b0w5r9/backend/schema/structs/index.dart"
    as power_sync_b0w5r9_data_schema;
import 'package:ff_theme/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart'
    as ps;

Future signOut() async {
  final database = await ps.getOrInitializeDatabase();
  //await database.disconnectAndClear(); // this will completely delete all the local data, use with caution as there may be items still in the upload queue
  await database
      .disconnect(); //this will simply disconnect from the PowerSync Service and preserve all local data
}

// Set your action name, define your arguments and return parameter,
// and then add the boilerplate code using the green button on the right!

2. Click “Save Action”.
3. Under the “Page Selector”, select your HomePage page.
4. Under the “Widget Palette”, drag a “Button” onto the right of your “AppBar”.
   
5. In the “Properties” panel on the right, rename the “Button Text” to Sign Out.
6. Switch to the “Actions” panel and open the “Action Flow Editor”.
7. Select “On Tap” as the action trigger.
8. Click “Add Action” and add a call to the signOut Custom Action.
9. Chain another Action and call to “Supabase Authentication” -> “Log Out”:

10. Click “Close”.

​

(Optional) Display Connectivity and Sync Status

1. Under the Widget Palette, select the “Components and custom widgets imported from library projects” panel.
   
2. Drag the PowerSyncConnectivity component into your home page’s “AppBar”.
   

​

Secure Your App

• RLS should be used as the authoritative set of security rules applied to your users’ CRUD operations that reach Postgres.
• Sync Rules are only applied for data that is to be downloaded to clients — they do not apply to uploaded data.
  • Sync Rules can typically be considered to be complementary to RLS, and will generally mirror your RLS setup.

​

Enable RLS in Supabase

alter table public.lists
  enable row level security;

create policy "owned lists" on public.lists for ALL using (
  auth.uid() = owner_id
)

​

Update Sync Rules

1. In the PowerSync Dashboard, select your project and instance and go to the Sync Rules view.
2. Edit the Sync Rules in the editor and replace the contents with the below:

bucket_definitions:
  user_lists:
    parameters: select request.user_id() as user_id
    data:
      - select * from lists where owner_id = bucket.user_id

3. Click “Validate”.
4. Click “Deploy” to deploy your Sync Rules.
5. Wait for the deploy to complete.

​

Arrays, JSON and Other Types

CREATE TABLE public.lists (
  # ... existing columns,
  tags text[] DEFAULT '{"default", "tags"}'
);

/// MODIFY CODE ONLY BELOW THIS LINE
return supabaseRows.map((r) {
  return ListsRow({
    ...r,
    'tags': jsonDecode(r['tags'] as String),
  });
}).toList();

import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart';

Future applyPowerSyncOptions() async {
  // Add your function code here!
  powerSyncOptions.transformData = (table, data) {
    switch (table) {
      case 'lists':
        data['tags'] = jsonDecode(data['tags'] as String);
    }
  };
}

​

Custom Backend Connectors

import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart';
import 'package:powersync/powersync.dart' as ps;

Future applyPowerSyncOptions() async {
  // Disable the default Supabase integration
  powerSyncOptions.useSupabaseConnector = false;
  final db = await getOrInitializeDatabase();

  // TODO: Write your own connector and call connect/disconnect when a user logs
  // in.
  db.connect(connector: _MyCustomConnector());
}

final class _MyCustomConnector extends ps.PowerSyncBackendConnector {
  @override
  Future<ps.PowerSyncCredentials?> fetchCredentials() {
    // TODO: implement fetchCredentials
    throw UnimplementedError();
  }

  @override
  Future<void> uploadData(ps.PowerSyncDatabase database) {
    // TODO: implement uploadData
    throw UnimplementedError();
  }
}

​

Known Issues, Limitations and Gotchas

1. Deploying to the Apple App Store currently requires some workarounds due to limitations in FlutterFlow:
   1. Download the code from FlutterFlow.
   2. Open the Podfile located in the ios/ directory.
   3. The following option in the Podfile needs to be updated from use_frameworks! :linkage => :static to use_frameworks! (remove everything after the exclamation sign).
   4. After removing that option, clean the build folder and build the project again.
   5. You should now be able to submit to the App Store.
2. Exporting the code from FlutterFlow using the “Download Code” action in FlutterFlow requires the same workaround listed above.
3. The PowerSync FlutterFlow Library does not currently support encryption at rest.
4. Other common issues and troubleshooting techniques are documented here: Troubleshooting.