> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase

> Query and modify data, explore tables, and execute Supabase RPC functions from your flows in Brain Studio.

**Supabase** is an open-source backend platform built on **PostgreSQL** that lets you manage databases, authentication, and functions from one interface. Unlike CRM or ERP integrations (which work on predefined models), Supabase connects Brain Studio directly to **your own tables and functions**, while respecting the access policies and logic you already defined in the database.

In **Brain Studio**, the integration lets your flows query data, insert and update records, and execute RPC functions from the conversation. Control remains in Supabase: permissions, RLS, and centralized logic.

## What Supabase enables

When you connect **Supabase**, you can:

* **Respond with real data from your database** - query tables with filters so the agent does not hallucinate or request information that already exists
* **Register business events immediately** - insert rows when the conversation creates a lead, order, request, or any relevant event
* **Update operational states** - change columns (order status, onboarding stage, verification result) based on what happens in the flow
* **Run centralized business logic** - call PostgreSQL RPC functions for calculations, validations, or transactions that should not live in the flow
* **Explore structure before acting** - list tables and review columns so the agent knows where to write

***

## Installation

### Prerequisites

1. An active **Supabase project** (hosted) with the tables and functions you plan to use.
2. The **two values** requested by the Brain Studio modal, from that same project:
   * **Supabase url**
   * **Api Key**
3. **RLS (Row Level Security)** policies and permissions aligned with what the flow should be allowed to do with the configured key.

### How to get credentials

To connect **Supabase** in Brain Studio, you need two project values:

* **Supabase url** - the project URL, also shown in Supabase as **Project URL**
* **Api Key** - a public key for project API access

In the Supabase dashboard, open your project and go to **Settings -> API** or **API Keys**.

<Steps>
  <Step title="Copy the Supabase url">
    Find your project's **Project URL** (for example `https://<your-project>.supabase.co`) and paste it into the **Supabase url** field in Brain Studio.
  </Step>

  <Step title="Copy the correct Api Key">
    Use a **low-privilege** key associated with public project access:

    * **`anon` public key** if your project uses legacy keys
    * **Publishable key** (`sb_publishable_...`) if your project already uses the new key model

    Put this value in the **Api Key** field in the installation modal.

    <Warning>
      Do not use **`service_role`** or a **secret key** in this integration. Those keys have elevated privileges, can bypass RLS policies, and should not be exposed in conversational flows.
    </Warning>
  </Step>

  <Step title="Verify permissions and RLS">
    Before connecting in production, verify that your project's **RLS policies** and permissions allow exactly the operations your flow must execute.
  </Step>
</Steps>

<Check>
  With **Supabase url** and **Api Key** you can complete the Supabase connection modal in Brain Studio.
</Check>

### How to connect it

The most direct way is to use [**Jelou Agent**](/en/guides/getting-started/jelou-agent): describe what you need and the agent connects **Supabase** automatically inside the flow.

If you prefer manual installation, open **Marketplace** and follow these steps with the URL and API Key from the previous section.

<Steps>
  <Step title="Open Marketplace">
    In Brain Studio, open **Marketplace** from the side menu.
  </Step>

  <Step title="Find Supabase">
    Find the integration and click **Connect**.
  </Step>

  <Step title="Fill Supabase url and Api Key">
    Paste the **Supabase url** (Project URL) and **Api Key** (**anon** or **Publishable**, never `service_role` or secret keys for this use case).
  </Step>

  <Step title="Confirm installation">
    The integration appears as **connected**.

    <Check>
      You can use it in **Canvas** or add it as a tool in **AI Agent**.
    </Check>
  </Step>
</Steps>

***

## Available tools

This integration exposes **7 tools** in Brain Studio. Names match the node editor. JSON examples are **illustrative**: always confirm exact fields in the tool panel.

<AccordionGroup>
  <Accordion title="List tables">
    Lists project tables. Use it at the **start** of a flow or when the agent should **confirm** which tables it can operate on.

    **Inputs in prose:** according to the node editor (often empty body or empty object).

    **Illustrative example:**

    ```json theme={null}
    {}
    ```
  </Accordion>

  <Accordion title="Describe table">
    Returns table structure (columns, types, relevant constraints). Use it before **insert/update** to avoid errors caused by types or required fields.

    **Inputs in prose:** table name; confirm exact identifier in the editor.

    **Illustrative example:**

    ```json theme={null}
    {
      "table_name": "customers"
    }
    ```
  </Accordion>

  <Accordion title="Query table">
    Reads rows with filters and limit. This is the base tool to **respond with data** or **branch logic** based on what's stored in Supabase.

    **Inputs in prose:** table; filters (equality or other operators if available in editor); optional limit.

    **Illustrative example:**

    ```json theme={null}
    {
      "table_name": "orders",
      "filters": {
        "status": "paid"
      },
      "limit": 25
    }
    ```
  </Accordion>

  <Accordion title="Insert row">
    Creates a new record. Fits **create** operations from chat (leads, events, fact rows).

    **Inputs in prose:** table and `data` object with columns and values.

    **Illustrative example:**

    ```json theme={null}
    {
      "table_name": "leads",
      "data": {
        "name": "Ana Perez",
        "email": "ana@example.com",
        "source": "whatsapp"
      }
    }
    ```
  </Accordion>

  <Accordion title="Update row">
    Updates rows matching filters. Fits **state changes** or corrections after user validation.

    **Inputs in prose:** table; filters selecting target records; `data` with fields to update.

    **Illustrative example:**

    ```json theme={null}
    {
      "table_name": "orders",
      "filters": {
        "id": "ord_987"
      },
      "data": {
        "status": "fulfilled"
      }
    }
    ```
  </Accordion>

  <Accordion title="Delete row">
    Deletes rows matching filters. **Destructive** operation: use only with very constrained criteria, and if possible route sensitive deletes through an **RPC** with extra checks.

    **Inputs in prose:** table and filters; review available operators in the editor.

    <Warning>
      A broad filter can delete more rows than intended. Test first in development environments and verify RLS policies.
    </Warning>

    **Illustrative example:**

    ```json theme={null}
    {
      "table_name": "draft_sessions",
      "filters": {
        "session_id": "sess_tmp_001"
      }
    }
    ```
  </Accordion>

  <Accordion title="Call RPC function">
    Executes a PostgreSQL RPC function exposed in Supabase. Centralizes **business logic** (calculations, validations, transactions) in the database.

    **Inputs in prose:** function name and parameters according to PostgreSQL signature.

    **Illustrative example:**

    ```json theme={null}
    {
      "function_name": "get_customer_summary",
      "parameters": {
        "customer_id": "cst_123"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## How to use in Brain

With **Supabase**, the usual pattern is to use **AI Agent** when the flow must dynamically decide what to query/update, and **Canvas** when the process follows a fixed sequence, for example: query record -> validate state -> update row -> notify.

### In AI Agent

Use it when conversation is **open-ended**: the user may ask for data, create a record, or trigger a function without a fixed script. The agent chooses the tool within the subset you enable.

<Steps>
  <Step title="Open the AI Agent node">
    In Canvas, select or add the **AI Agent** node.
  </Step>

  <Step title="Open Tools">
    In the right panel, open the **Tools** tab.
  </Step>

  <Step title="Add Supabase">
    Use **Add tool**, search for **Supabase**, and enable it.
  </Step>

  <Step title="Configure tools">
    Restrict sensitive actions (for example, without **Delete row** in public-facing agents).

    <Check>
      **Supabase** appears in the agent tool list; adjust permissions from the integration settings icon.
    </Check>
  </Step>
</Steps>

### In Canvas

Use it when the process is **deterministic**: for example list tables -> describe -> query -> branch -> insert or update, with explicit validation between nodes.

<Steps>
  <Step title="Drag Supabase into Canvas">
    In the side panel, open **Marketplace** and drag **Supabase** into the flow.
  </Step>

  <Step title="Select the tool">
    With the node selected, in **Tools** choose the action (for example **Query table** or **Insert row**).
  </Step>

  <Step title="Configure body and memory">
    Fill in the JSON in the node editor and use **Save response** in memory when the next step depends on the output.
  </Step>

  <Step title="Connect the flow">
    Link **Task completed** and **There was an error** with your business logic or user-facing messages.

    <Check>
      Each node executes one tool; Canvas order defines your process.
    </Check>
  </Step>
</Steps>

Illustrative **Insert row** example (adjust column names and memory vars to your flow):

```json theme={null}
{
  "table_name": "leads",
  "data": {
    "name": "{{$memory.name}}",
    "email": "{{$memory.email}}",
    "source": "whatsapp"
  }
}
```

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead capture and record creation directly in your database">
    When a prospect, request, or relevant event happens in the conversation, the flow persists it in Supabase instantly. No middleware API and no extra integration: data goes straight to your tables.

    **Concrete example:** a SaaS captures leads through WhatsApp. The prospect identifies themselves and shows interest. The flow validates required fields and inserts a row in `leads` with name, email, and source channel. Sales sees it on their dashboard immediately.

    **Ideal for:** digital products, startups, and teams that use Supabase as their primary database and want to avoid data duplication in other systems.
  </Accordion>

  <Accordion title="Personalized conversations with user data">
    Instead of requesting information that already exists, the flow queries Supabase before answering. If the user already has orders, an active plan, or a process in progress, the agent knows before replying.

    **Concrete example:** an ecommerce support channel on WhatsApp. The customer asks, "where is my order?" The flow queries `orders` by email, finds the most recent order, and replies with status, ETA, and tracking number.

    **Ideal for:** SaaS, ecommerce, onboarding, and any flow where user context improves response quality.
  </Accordion>

  <Accordion title="Operational state changes from conversation">
    When the user confirms an action - accept a proposal, complete onboarding, approve a ticket - the flow updates the corresponding column in Supabase. System state reflects what actually happened.

    **Concrete example:** a logistics platform confirms delivery via WhatsApp. The courier confirms handoff. The flow updates order `status` to "delivered" in Supabase. Operator dashboard and automated notifications update immediately.

    **Ideal for:** operations, fulfillment, customer success, and processes with transactional state changes.
  </Accordion>

  <Accordion title="Centralized business logic with RPC functions">
    For calculations, complex validations, or multi-table transactions, logic should live in PostgreSQL, not in the flow. The flow calls the RPC function and uses the result to reply, decide, or continue.

    **Concrete example:** a fintech computes credit eligibility. The flow calls `get_credit_score` with user ID. PostgreSQL executes logic (history query, score calculation, constraints), then returns the result.

    **Ideal for:** fintech, scoring, pricing, complex validations, and products with core logic in PostgreSQL.
  </Accordion>
</AccordionGroup>

***

## Integrations that pair well with Supabase

<AccordionGroup>
  <Accordion title="Slack">
    Every time a critical record is created or changes state in Supabase, the flow can notify the right Slack channel.

    **Combined flow:** new lead inserted in Supabase -> alert to #sales in Slack with name and source channel.

    [Slack documentation](/en/guides/integraciones/productividad/slack)
  </Accordion>

  <Accordion title="Gmail">
    After inserting or updating a record in Supabase, the flow can send a transactional email to the user.

    **Combined flow:** order updated to "shipped" in Supabase -> email to customer with tracking number.

    [Gmail documentation](/en/guides/integraciones/productividad/gmail)
  </Accordion>

  <Accordion title="Google Sheets">
    For reporting, manual review, or sharing with stakeholders without Supabase access, the flow can export query results to a shared sheet.

    **Combined flow:** query weekly metrics in Supabase -> update KPI sheet in Sheets.

    [Google Sheets documentation](/en/guides/integraciones/productividad/google-sheets)
  </Accordion>

  <Accordion title="HubSpot">
    When Supabase stores product operations (activity, usage, onboarding) and HubSpot manages the commercial lifecycle, the flow can pass backend milestones to CRM.

    **Combined flow:** user completes onboarding in Supabase -> update HubSpot contact with activation date and plan.

    [HubSpot documentation](/en/guides/integraciones/crm/hubspot)
  </Accordion>
</AccordionGroup>

***

## Related articles

<CardGroup cols={2}>
  <Card title="Integrations" href="/en/guides/integraciones/integraciones" icon="grid">
    Catalog of integrations available in Marketplace.
  </Card>

  <Card title="How to use integrations in Brain" href="/en/guides/integraciones/como-usar-integraciones-en-brain" icon="book-open">
    General flow to install and use integrations in Brain Studio.
  </Card>
</CardGroup>