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

# Supabase integration

How to set up the Release Supabase integration for instant databases

Release integrates with [Supabase](https://supabase.com) to provision PostgreSQL databases for your ephemeral environments. Supabase's branching feature allows Release to automatically create isolated database branches, giving each environment its own database instance.

## Prerequisites

Before setting up the Supabase integration in Release, you'll need:

1. A Supabase account (sign up at [supabase.com](https://supabase.com))
2. A Supabase project on the **Pro plan** (branching requires Pro or above)
3. A Supabase access token

## Step 1: Create a Supabase Account and Project

1. Sign up or log in at [supabase.com/dashboard](https://supabase.com/dashboard).
2. Create a new project (or use an existing one). Note the **region** your project is in — you'll need this when creating a dataset.

{% hint style="info" %}
Supabase database branching requires a **Pro plan** or above. Free-tier projects cannot use branching. You can upgrade your project's plan in the Supabase dashboard under **Organization Settings** > **Billing**.
{% endhint %}

## Step 2: Create an Access Token in Supabase

Release connects to Supabase using an **access token**. You'll need to create one from your account settings.

1. In the Supabase Dashboard, click your avatar in the top-right corner and select **Account preferences**, or navigate directly to **Account** > **Access Tokens**.

![Supabase Access Tokens page in Account settings](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-597f4e0326627203ad3f326e00ddfba90c458e74%2Fsupabase-access-tokens.png?alt=media)

2. Click **Generate new token**.

![Generate New Token dialog — enter a name and expiration](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-8e6488edfe19ba42403377d3c92d5dd65febfc7d%2Fsupabase-generate-token-form.png?alt=media)

3. Enter a name for the token (e.g., `release-integration`).
4. Set the expiration to **Never** for production use.
5. Click **Generate token**.

![Generate New Token dialog filled with name and Never expiration](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-9933be16c340deaf9b7fb1521535863fbafa33cd%2Fsupabase-generate-token-filled.png?alt=media)

6. **Important:** Copy the access token value immediately. It will not be shown again.

{% hint style="warning" %}
The access token is only displayed once. Make sure to copy it before closing the dialog.
{% endhint %}

## Step 3: Install the Supabase Integration in Release

1. In the Release UI, navigate to **Configuration** > **Integrations** (accessible at `/workspaces/<workspace-id>/configuration/integrations`).

![Release Integrations page showing Supabase under Installed](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-5d274975c85bf5f2f5d7a8a63db014ca909dc5cd%2Frelease-integrations-list-supabase.png?alt=media)

2. Find **Supabase** under the **Available** section and click on it.
3. Click **Install Supabase**.
4. Enter your **Access Token** from Step 2.
5. Click **Install Integration**.
6. The integration is now installed and will appear under the **Installed** section on the Integrations page.

![Supabase integration page showing installed state with Actions dropdown](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-84d7ded46fc38b1d984a489dab780b9766aced07%2Frelease-supabase-installed.png?alt=media)

## Step 4: Create a Supabase Dataset

Once the integration is installed, you can create datasets that use Supabase as the database provider.

1. Navigate to **Configuration** > **Datasets**.
2. Click **Create Dataset**. If the Supabase integration is installed, you'll see a **Supabase** tab alongside the other provider tabs.
3. Select the **Supabase** tab.
4. Enter a **Dataset Name** (3-50 characters, lowercase letters, numbers, and hyphens).
5. Select a **Supabase Project** from the dropdown. This lists all projects accessible to your access token.
6. Optionally change the **Database Name** (defaults to `postgres`).
7. Configure the **Number of available databases** (how many branches to keep in the pool).
8. Click **Create Dataset**.

![Supabase dataset detail page showing pool items and environment variables](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-bbc09f6b1d07ac87967abcc5ea8e8eba3bd8c341%2Frelease-supabase-dataset.png?alt=media)

## How It Works

When Release creates an ephemeral environment that uses a Supabase dataset:

1. Release creates a **new branch** from the default branch of your Supabase project.
2. The branch is monitored until it reaches a **healthy** state.
3. Connection credentials are generated using the Supabase **session pooler** for IPv4 compatibility.
4. Credentials are automatically injected as **environment variables** into your services.
5. When the environment is torn down, the branch is deleted to clean up resources.

### Environment Variables

The following environment variables are automatically set for services using Supabase datasets. The prefix is derived from the dataset name (uppercased, with hyphens replaced by underscores).

For example, a dataset named `my-app` would produce:

| Variable                       | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `MY_APP_DB_POOL_HOST`          | Supabase session pooler hostname (IPv4 compatible)    |
| `MY_APP_DB_POOL_PASS`          | Database password                                     |
| `MY_APP_DB_POOL_USER`          | Database username (in `postgres.<branch-ref>` format) |
| `MY_APP_DB_POOL_DATABASE_NAME` | Database name (default: `postgres`)                   |
| `MY_APP_DB_POOL_NAME`          | Branch name created by Release                        |

### Important: Schema Only, No Data

Unlike some other database providers, Supabase branches **only include the schema** from your parent project — they do **not** copy data. This is a Supabase design decision to protect production data.

If your ephemeral environments need seed data, you have two options:

1. **Seed file**: Add a `supabase/seed.sql` file to your repository. Supabase runs this automatically when creating branches via the GitHub integration.
2. **Application-level seeding**: Run database seeds as part of your deployment process (e.g., `rails db:seed` or a migration step).

### Connection Details

Release uses the Supabase **session pooler** to connect to branch databases. This provides IPv4 connectivity, which is required for most Kubernetes environments. The connection details are:

* **Host**: The Supabase session pooler (e.g., `aws-1-us-west-2.pooler.supabase.com`)
* **Port**: `5432`
* **User**: `postgres.<branch-ref>` (the pooler requires this format)
* **SSL**: Required (`sslmode=require`)

Your application should use these environment variables to construct its database connection string:

```
postgresql://${MY_APP_DB_POOL_USER}:${MY_APP_DB_POOL_PASS}@${MY_APP_DB_POOL_HOST}:5432/${MY_APP_DB_POOL_DATABASE_NAME}
```

## Updating the Integration

To update your Supabase credentials:

1. Go to **Configuration** > **Integrations** > **Supabase**.
2. Click **Actions** > **Configure**.
3. Update the Access Token as needed.
4. Click **Save**.

## Troubleshooting

### Integration won't connect

* Verify your access token hasn't been revoked
* Ensure the access token has access to the projects you want to use
* You can test your token by running: `curl -H "Authorization: Bearer <your-token>" https://api.supabase.com/v1/projects`

### Branches not creating

* Verify your Supabase project is on the **Pro plan** or above — branching is not available on the Free tier
* If you see a "plan limitation" error, upgrade your Supabase project plan
* Check that your project is in a healthy state in the Supabase Dashboard

### Connection issues in environments

* Supabase requires SSL connections — ensure your application is configured to use `sslmode=require`
* Supabase is PostgreSQL-only — ensure your application's database driver is configured for PostgreSQL
* The connection uses the Supabase session pooler for IPv4 compatibility. If you see "tenant not found" errors, the branch may still be provisioning — wait a moment and retry
* Verify the environment variables are set correctly by running `env | grep DB_POOL` inside your container


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.release.com/integrations/integrations-overview/supabase-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.