> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/destinations/supabase.md).

# Supabase

Connect a Supabase project through OAuth so Terra writes events to its Postgres tables and storage bucket.

[Supabase](https://supabase.com/) combines [storage buckets](https://supabase.com/docs/guides/storage) for raw payloads and [Postgres tables](https://supabase.com/docs/guides/database/tables) for structured metadata in one platform. Terra connects to your project through OAuth and provisions everything it needs.

## Before you begin

* A Supabase account. You can pick an existing project or create one while connecting.

## Add the destination in Terra

Terra integrates with Supabase via OAuth. Everything is provisioned automatically:

1. On the [Connections page](https://dashboard.tryterra.co/dashboard/connections) in your Terra dashboard, click **Add New** and select **Supabase**.
2. You'll be redirected to Supabase to authorize Terra.
3. Select an existing project or create a new one.
4. Terra automatically provisions the following in your project:
   * A **`terra-payloads`** storage bucket for raw data files
   * Access via your project's **service role key** for secure write operations
   * Three database tables (see [What Terra writes](#what-terra-writes) below)

No manual setup is required.

## What Terra writes

### Database tables

Terra creates three tables in your Supabase project's Postgres database:

```sql
CREATE TABLE terra_users (
    user_id TEXT PRIMARY KEY,
    reference_id TEXT,
    created_at TIMESTAMPTZ,
    granted_scopes TEXT,
    provider TEXT,
    state TEXT
);

CREATE TABLE terra_data_payloads (
    payload_id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    data_type TEXT,
    created_at TIMESTAMPTZ,
    start_time TIMESTAMPTZ,
    end_time TIMESTAMPTZ,
    FOREIGN KEY (user_id) REFERENCES terra_users(user_id)
        ON DELETE CASCADE ON UPDATE CASCADE
);

CREATE TABLE terra_misc_payloads (
    payload_id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    data_type TEXT,
    payload_type TEXT,
    created_at TIMESTAMPTZ,
    FOREIGN KEY (user_id) REFERENCES terra_users(user_id)
        ON DELETE CASCADE ON UPDATE CASCADE
);
```

* **`terra_users`**: created or updated on authentication events. The `state` column tracks the user's lifecycle (`active`, `deauth`, `user_reauth`, etc.).
* **`terra_data_payloads`**: one row per record inside a payload's `data` array, not one row per webhook event. An event covering 30 days of `daily` data writes 30 rows. Rows are keyed on `payload_id`, so each distinct `summary_id` gets its own row. Records without a `summary_id` (`daily`, for example) are keyed by the user's provider account (not the Terra `user_id`), data type and `start_time` date instead, so several records for the same provider account, type and day collapse into one row (last write wins). Records carrying no `start_time` or `end_time` are written to neither this table nor the storage bucket.
* **`terra_misc_payloads`**: non-data events (deauth, access revoked, etc.).

Foreign keys use `ON DELETE CASCADE` and `ON UPDATE CASCADE`, so deleting or updating a user automatically propagates to their payloads.

### Storage bucket

Raw JSON payloads are uploaded to the `terra-payloads` bucket with the path:

```
{data_type}/{payload_id}.json
```

For example: `activity/3a4b5c6d7e8f9012.json`

## Row Level Security (RLS)

RLS is **disabled** on the Terra tables by default. This is intentional:

* Terra writes data using a **service role key**, which bypasses RLS regardless.
* Enabling RLS without policies would block your client-side reads (Supabase defaults to deny-all when RLS is on with no policies).

You're free to enable RLS and add your own policies to control how your frontend or users access the data. Terra's writes will continue to work regardless.

## User lifecycle

Terra automatically manages user state transitions in your Supabase tables:

* **Re-authentication**: when a user re-authenticates, Terra migrates their existing payloads to the new user ID and updates all foreign key references.
* **Deauthentication**: when a user disconnects, Terra deletes their record from `terra_users` (cascading to all payload rows) and removes their files from the storage bucket.

## Next steps

* [User authentication](/unified-api/authentication-flow.md): link a user's wearable so events start flowing.
* [Event delivery](/destinations/events.md): see what each delivery status means and how retries work.
* [Health data events](/unified-api/receiving-data-updates.md): process the data Terra delivers.
