> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/soda-documentation/developer-tools/data-source-reference-for-soda-core/supabase.md).

# Supabase

Access configuration details to connect Soda to a Supabase data source.

Soda Cloud connects to the Postgres database of a Supabase project. The connection runs on Soda's PostgreSQL adapter, so every Soda Runner version supports it and no runner upgrade is needed.

Data contracts, Metric Monitoring, Diagnostics Warehouse and lineage work on a Supabase data source as they do on a [PostgreSQL](https://docs.soda.io/soda-documentation/developer-tools/data-source-reference-for-soda-core/postgresql.md) data source.

## Connection modes

Supabase offers more than one way to reach a project's database. Connect Soda through the **session pooler**, which works over IPv4.

| Mode                         | Host                                   | Port   | User                     |
| ---------------------------- | -------------------------------------- | ------ | ------------------------ |
| Session pooler (recommended) | `aws-<n>-<region>.pooler.supabase.com` | `5432` | `postgres.<project-ref>` |
| Direct connection            | `db.<project-ref>.supabase.co`         | `5432` | `postgres`               |

To find the exact values for your project, open the project in the Supabase dashboard and click **Connect** at the top of the page.

The direct connection resolves to an IPv6 address unless your Supabase project has the IPv4 add-on. Use it only if the runner that connects to Supabase has IPv6 connectivity, or if your project has the add-on.

> For details on each connection mode, refer to the Supabase documentation on [connecting to Postgres](https://supabase.com/docs/guides/database/connecting-to-postgres).

## Onboard Supabase in Soda Cloud

{% stepper %}
{% step %}

### Select Supabase

On the **Data Sources** page, click **New Data Source**, then select **Supabase**.
{% endstep %}

{% step %}

### Name the data source and select a runner

Fill in the data source identifier and the runner as for any other data source.

> To learn how, refer to [Via Soda Cloud](https://docs.soda.io/soda-documentation/connect/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud.md).
> {% endstep %}

{% step %}

### Enter the connection details

Copy the session pooler details from **Connect** in your Supabase project dashboard, then click **Paste from Supabase** to fill in the form. Pasting the same text into any field of the form works too.

**Paste from Supabase** reads a `postgresql://` connection string or `key=value` pairs, such as `host=... port=... user=...`, and fills in the fields it finds. It skips the `[YOUR-PASSWORD]` placeholder in Supabase's connection strings, so enter the password yourself. Store it as a [secret](https://docs.soda.io/soda-documentation/connect/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud.md#using-secrets-for-sensitive-credentials) rather than in plain text.

| Field         | Required | Default    | Description                                                                                                                                        |
| ------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host`        | Yes      |            | The session pooler host, `aws-<n>-<region>.pooler.supabase.com`.                                                                                   |
| `port`        | No       | `5432`     | The session pooler port.                                                                                                                           |
| `user`        | Yes      |            | `postgres.<project-ref>` for the session pooler.                                                                                                   |
| `password`    | Yes      |            | The database password of your Supabase project.                                                                                                    |
| `database`    | Yes      | `postgres` | The database name.                                                                                                                                 |
| `sslmode`     | No       | `require`  | The TLS mode: `disable`, `allow`, `prefer`, `require`, `verify-ca` or `verify-full`. Clear the field to use the driver default, which is `prefer`. |
| {% endstep %} |          |            |                                                                                                                                                    |

{% step %}

### Test and connect

Test the connection, then connect the data source.
{% endstep %}
{% endstepper %}

## Data source YAML

Soda Cloud stores a Supabase connection as a PostgreSQL configuration, and the runner receives it with `type: postgres`:

{% code title="ds\_config.yml" %}

```yaml
type: postgres
name: my_supabase
connection:
  host: aws-<n>-<region>.pooler.supabase.com
  port: 5432
  user: postgres.<project-ref>
  password: ${env.SUPABASE_PASSWORD}
  database: postgres
  sslmode: require
  prepare_threshold: 2147483647
```

{% endcode %}

Soda Cloud adds `prepare_threshold: 2147483647` to every Supabase connection. It stops psycopg, the PostgreSQL driver, from preparing statements on the server.

To connect Soda Core to Supabase, install the `soda-postgres` package and use this configuration. There is no separate Supabase package or `type: supabase`. To verify contracts against a Supabase data source onboarded in Soda Cloud, use the same data source name.

```bash
pip install soda-postgres
```

## Required permissions

Create a dedicated read-only role for Soda with the statements listed under [PostgreSQL required permissions](https://docs.soda.io/soda-documentation/developer-tools/data-source-reference-for-soda-core/postgresql.md#required-permissions). Through the session pooler, a custom role connects with the user name `<role>.<project-ref>`, for example `soda_user.<project-ref>`.

<br>

***

{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation.

Learn more about [Licensing & documentation access](https://docs.soda.io/soda-documentation/govern/security-licensing-and-compliance/documentation-access-and-licensing.md) or <a href="https://docs.soda.io/~gitbook/auth/login" class="button primary small">Log in to Soda Cloud</a>.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/soda-documentation/developer-tools/data-source-reference-for-soda-core/supabase.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
