Supabase

Supabase Connector Guide

This guide provides an overview of how to connect Whalesync to Supabase and answers common questions.

Connecting to Supabase

To connect your Supabase database to Whalesync, you'll need to authenticate using OAuth. This is a secure way to grant Whalesync access to your Supabase data without sharing your password. Whalesync will request access to your Supabase organization. After you select an organization, Whalesync will show you a list of your Supabase projects.

Once you select a project, Whalesync creates a dedicated read-write service account in that Supabase project. This allows Whalesync to access your data to perform syncs. The service account is granted permissions on the public schema by default, which is where it can create and update records.

Syncing Data

Automatic Table and Field Creation

Whalesync can automatically create tables and fields in Supabase to match the structure of the other app you're syncing with.

Things to Keep in Mind

Primary Keys

For a table to be syncable, it must have a primary key that can uniquely identify each row. Whalesync will automatically detect the primary key on your table. If your table does not have a suitable primary key (e.g., an auto-incrementing number), Whalesync can add a synthetic primary key column to enable syncing.

Primary keys must be auto-generated (i.e. have a default value). To ensure data consistency, we require primary keys have default values. See Adding default values to primary keys.

Schema changes

Danger

Renaming schema, tables, or columns will break Whalesync mappings
If you rename a table/column, you'll need to remap the impacted table/column in Whalesync.

Foreign Keys

We support foreign keys (including two-way sync)! In order to sync a foreign key column, you'll need to also sync the table the column references.

Permissions

The service account created by Whalesync has read and write permissions on the public schema. If you want to sync tables in other schemas, you may need to grant permissions to the whalesync_service_account role in your Supabase project manually.

Schema Changes

After making schema changes in Supabase, like adding or removing a column, you should refresh the schema in Whalesync to see those changes reflected.

HTML and Markdown

Note

Adding "_html" to the end of a column name will preserve HTML
For example, "text_html", will preserve that column's values as HTML while syncing.

See HTML and Markdown Field Extensions for a way to sync HTML or Markdown into a rich text field.

Network and SSL

If your database only accepts connections from known IP addresses, allowlist Whalesync's static IP. See Allowlisting Whalesync IP addresses.

Note that Whalesync does not yet support custom SSL/TLS certificates.

Supported Schemas

In general, Whalesync supports syncing custom Supabase tables. We want to prevent interfering with internal Supabase data, so we don't support syncing Postgres schemas that Supabase uses for its own internal purposes.

Schema	Status
public	✅ Supported
Any other non-Supabase provided schema	✅ Supported
auth	✖️ Not Supported
extensions	✖️ Not Supported
graphql	✖️ Not Supported
graphql_public	✖️ Not Supported
pgbouncer	✖️ Not Supported
pgsodium	✖️ Not Supported
pgsodium_masks	✖️ Not Supported
realtime	✖️ Not Supported
storage	✖️ Not Supported
vault	✖️ Not Supported

Supported Fields

Field	Status
🏷️ Array	✅ Supported
#️⃣ Bigint	✅ Supported
📝 Bit	✅ Supported
☑️ Boolean	✅ Supported
📝 Composite	➡️ Supported (1-Way)
📅 Date	✅ Supported
📅 Daterange	➡️ Supported (1-Way)
🔗 Domain	➡️ Supported (1-Way)
🔘 Enum	✅ Supported
🖇️ Foreign Key	✅ Supported
#️⃣ Geometric	➡️ Supported (1-Way)
#️⃣ Integer	✅ Supported
#️⃣ Interval	➡️ Supported (1-Way)
🗃️Json	✅ Supported
💱 Money	✅ Supported
📝 Network	✅ Supported
#️⃣ Numeric	✅ Supported
⏱️ Range	➡️ Supported (1-Way)
📝 Text	✅ Supported
📝 Textsearch	➡️ Supported (1-Way)
⏱️ Time	➡️ Supported (1-Way)
⏱️ Timestamp	✅ Supported
🆔 Uuid	✅ Supported
🗃️ XML	✅ Supported
🔦 Binary	✖️ Not Yet