# Connect Supabase

> Monitor Supabase from your Mac's notch. A paused or unhealthy project, a new security lint or a row your SQL finds reaches you, with nothing but a personal access token.

Source: https://coisland.app/docs/connect-supabase/

## What you need

- **You need:** Personal access token, from Account › Access Tokens (https://supabase.com/dashboard/account/tokens)
- **The form asks:** Project, Connector name, Access token
- **You can watch:** Read-only SQL, Project health, Advisor lints
- **Access:** SQL as the read-only role, and reads of health and advisors

To connect Supabase to CoIsland, you create a personal access token in the Supabase dashboard, add it as a Supabase connector with your project's address, then pick what to watch: read-only SQL, the project's health, or the security and performance advisors. You do it alone: no admin, no project API key, no database password.

CoIsland calls Supabase's Management API (`api.supabase.com`) straight from your Mac. The token stays in your login Keychain, and CoIsland only reads: SQL runs as your project's read-only role, so Postgres itself refuses any write.

## Create a personal access token

1. Sign in at supabase.com and open **Account › Access Tokens**.
2. Click **Generate new token**, name it `CoIsland`, and copy it (`sbp_…`). Supabase shows it once.

A personal access token acts as you: it reaches the projects of every organization you belong to, with your role there. CoIsland only uses it on the project you give each connector.

A project key (`sb_publishable_…`, `sb_secret_…`, or a JWT) is not a personal access token: CoIsland refuses it.

## Connect Supabase in CoIsland

1. Open **Settings › Connectors** and click **+** (Add Connector).
2. Choose **Supabase**, fill in the fields, then click **Test connector**.
3. Click **Add Connector**.

| Field | What to enter |
|---|---|
| Project | The project's dashboard address (`https://supabase.com/dashboard/project/<ref>/…`), its API address (`https://<ref>.supabase.co`) or its ref (Project Settings › General › Project ID) |
| Connector name | What monitors call it. CoIsland suggests `supabase-` and the ref's first letters |
| Access token | The token you copied |

**Test connector** reads your profile and the project, and says its name, region and status.

## Watch Supabase: the three monitor kinds

| Kind | What you write | What alerts |
|---|---|---|
| Read-only SQL | Any SQL | A new row, or a row count crossing a number |
| Project health | Services to watch | The project paused or down, or a service unhealthy |
| Advisor lints | Advisors and levels | A new lint from the security or performance advisor |

### Read-only SQL

The SQL runs as `supabase_read_only_user`, through the Management API. Qualify every table with its schema (`public.orders`, `auth.users`): the endpoint requires it. Example in the app:

```sql
SELECT id, email, created_at
FROM auth.users
WHERE created_at > now() - interval '1 day'
```

Columns keep the order you wrote them in. New SQL monitors check every 15 minutes.

### Project health

```text
services:db,auth,rest,realtime,storage
```

The project's own status is always watched: paused, pausing, restoring or failed alerts once. While the project is up, each service picked (database, auth, Data API, realtime, storage, pooler) alerts when Supabase reports it unhealthy, and again if it breaks after recovering. The alert page shows every service now, and **Recovered** once it is healthy.

### Advisor lints

```text
type:security
type:security,performance level:error,warn
```

The same lints as the dashboard's **Advisors**: RLS disabled on a public table, a leaked password protection left off, an unindexed foreign key. Each new lint alerts once; the alert page explains it, links **How to fix**, and says **Fixed** once it is gone. New advisor monitors check every hour. Supabase marks this endpoint experimental.

## A Supabase monitor is a watch file

```text
-- name: Shop down or paused
-- kind: supabase.health
-- connector: shop
-- every: 5m
-- alert: new-rows

services:db,auth,rest,realtime,storage
```

| `-- kind:` | Monitor kind |
|---|---|
| `supabase.sql` | Read-only SQL |
| `supabase.health` | Project health |
| `supabase.advisors` | Advisor lints |

## Troubleshooting Supabase connector errors

- **"The access token was refused."** Create a new one at supabase.com/dashboard/account/tokens and edit the connector.
- **"Not allowed: …"** Your role in the project's organization does not allow it.
- **"Project … was not found."** It was deleted, or it belongs to an organization you are not in.
- **"Supabase refused the query: …"** A SQL mistake, in Postgres's words; a write is refused here too.
- **Rate limited.** The Management API allows 120 requests a minute; CoIsland waits and tries again.

## Frequently asked questions

### Can CoIsland change anything in my Supabase project?

No. It reads the project, its health and its advisors, and runs SQL as the read-only role.

### Do I need the database password or a connection string?

No. The personal access token is enough. If you prefer a direct Postgres connection, the Postgres connector takes the project's connection string.

### Where does CoIsland keep my Supabase token?

In your login Keychain. `connectors.json` holds the connector's name and project ref, never the token.