Supabase integration

How to set up the Release Supabase integration for instant databases

Release integrates with Supabase 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)

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.

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.

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.

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

1. Click Generate new token.

Generate New Token dialog — enter a name and expiration

1. Enter a name for the token (e.g., release-integration).

2. Set the expiration to Never for production use.

3. Click Generate token.

Generate New Token dialog filled with name and Never expiration

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

The access token is only displayed once. Make sure to copy it before closing the dialog.

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

1. Find Supabase under the Available section and click on it.

2. Click Install Supabase.

3. Enter your Access Token from Step 2.

4. Click Install Integration.

5. 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

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

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