# Connect EMQX Agents to Supabase

The Supabase connector lets EMQX Agents query database tables, execute SQL, inspect table schemas, and list or invoke Edge Functions. Use it to combine application data and serverless functions with EMQX agent workflows.

## Common Use Cases

- Read application records related to an MQTT device event.
- Inspect table schemas before generating a query.
- Write a workflow result to a database table through SQL.
- Invoke an Edge Function after an agent validates an event.

Example chat prompt:

```text
Use the app-supabase connector to list the available tables, inspect the device_alerts schema, and query the five most recent critical alerts.
```

## Prerequisites

Before adding the connector, prepare:

- A Supabase account with access to the required organization and project, or permission to create them during authorization.
- Permission to authorize database and Edge Function operations.
- Database privileges for the tables and SQL operations required by the workflow.

## Add a Supabase Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **Supabase** and click **Add**.
3. Enter a descriptive connector name.
4. Click **Confirm**. The Supabase authorization flow opens in a dialog.
5. In **Base URL**, keep the default value, `https://api.supabase.com`, unless you use a self-hosted Supabase deployment.
6. Click **Connect Account**.
7. Sign in to Supabase. Select an available sign-in method, such as GitHub, SSO, or email and password. If you do not have a Supabase account, click **Sign up** and create one.
8. If you sign in with GitHub, review the access request and click **Authorize supabase**.

If you already have a Supabase organization and project, continue to [Authorize Composio](#authorize-composio). Otherwise, create them before completing authorization.

### Create a Supabase Organization and Project If Required

1. If Supabase reports that no organizations are available, click **Create an organization**.
2. On the **Create a new organization** page, enter the organization **Name**, select its **Type** and **Plan**, and click **Create organization**.
3. On the **Create a new project** page, select the organization. Optionally connect GitHub.
4. Enter the **Project name** and a strong **Database password**.
5. Select a **Region**.
6. Review the **Security** settings, including **Enable Data API**, **Automatically expose new tables**, and **Enable automatic RLS**.
7. Click **Create new project**.

### Authorize Composio

1. Return to the **Authorize Composio** page and select the organization to connect.
2. Review the requested read and write access to the selected organization, including its database, secrets, authentication, Edge Functions, environment, projects, domains, PostgREST, analytics, and storage.
3. Click **Authorize Composio**.
4. Wait for the success message and return to EMQX Agents.
5. On the **Added** tab, verify that the connector status is **Authorized**.

<!-- TODO: Confirm whether Supabase authorization can be restricted to individual projects, the database role used by the connector, Row Level Security behavior, and whether writable SQL or Edge Function calls require per-action approval. -->

## Supported Tools

### Database

| Tool | Access | Description |
|---|---|---|
| `SUPABASE_BETA_RUN_SQL_QUERY` | Write | Executes a SQL query in the Supabase project database. |
| `SUPABASE_RUN_READ_ONLY_QUERY` | Read | Executes a read-only SQL query. |
| `SUPABASE_SELECT_FROM_TABLE` | Read | Queries rows from a selected database table. |
| `SUPABASE_GET_TABLE_SCHEMAS` | Read | Gets database table schemas. |
| `SUPABASE_LIST_TABLES` | Read | Lists tables in the database. |

### Edge Functions

| Tool | Access | Description |
|---|---|---|
| `SUPABASE_GET_FUNCTION` | Read | Gets details about an Edge Function. |
| `SUPABASE_INVOKE_EDGE_FUNCTION` | Write | Invokes an Edge Function. |
| `SUPABASE_LIST_FUNCTIONS` | Read | Lists Edge Functions in the project. |

::: warning Important Notice
The writable SQL tool can modify or delete database data when the authorized role permits it. Use read-only queries and least-privilege database access for workflows that do not require writes.
:::

## Use the Connector in a Chat

1. In the chat input area, click the connector icon.
2. Select the authorized **Supabase** connector.
3. In the prompt, identify the external resource and operation that the agent should use.
4. Review the generated agent definition and confirm that it contains only the required tools.

## Permissions and Data Access

The connector uses the authorized Supabase organization and account permissions. Database roles, Row Level Security policies, table privileges, and Edge Function authorization determine accessible data and operations.

Do not include external service credentials or access tokens in the chat prompt or agent instructions.

## Limitations

- Supabase API and database limits apply.
- Row Level Security can restrict query results or write operations.
- Edge Function availability and behavior depend on the selected project and function configuration.

<!-- TODO: Confirm service-specific result size limits, file limits, API rate limits, plan restrictions, and unsupported resource types. -->

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector remains **Unauthorized**. | Retry authorization, confirm the **Base URL**, sign in to Supabase, select an organization, and click **Authorize Composio**. |
| The authorization page reports that no organizations are available. | Click **Create an organization**, create a project if needed, then return to the authorization page. |
| A tool returns a permission error. | Verify the authorized account's access to the selected organization, target project, resource, and operation. |
| A required tool is unavailable. | Verify that the tool is supported and approved for this connector, then select the connector again in the chat. |
| Requests are rejected intermittently. | Check the external service status, API quota, rate limits, and account plan. |

## Related Links

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)