Skip to content
SQLAnvil SQLAnvil SQLAnvil

Supabase connections

Supabase is a first-class SQLAnvil warehouse (see the OSS Supabase guide). Cloud connects to it through a revocable OAuth authorization — you never give it your database password or service-role key.

Connect your Supabase account

Section titled “Connect your Supabase account”

import { Steps } from ‘@astrojs/starlight/components’;

  1. On your project, go to Settings → Supabase warehouse and click Connect Supabase.

  2. Authorize on Supabase’s consent screen. You don’t register anything or paste a key — SQLAnvil runs the OAuth app; you’re just granting it access. Choose the organization/project to grant.

  3. Pick the warehouse project. If your account has more than one project, a dropdown appears — choose the one CI should branch off. (If you granted a single project, it’s selected automatically.) The project must be on the Pro plan — branch CI needs Supabase branching.

That’s it. From then on, every PR runs against a fresh branch of that project.

What we hold. Only a Supabase OAuth refresh token, encrypted at rest, from which each run mints a short-lived (1-hour) access token. Never your DB password or service-role key. You can revoke it any time in your Supabase account, or Reconnect to re-scope or re-authorize. See Data handling.

Use the session pooler, not the direct host

Section titled “Use the session pooler, not the direct host”

Supabase’s direct database host (db.<ref>.supabase.co) is IPv6-only and won’t resolve from many runtimes. Always connect via the session pooler:

  • Host: aws-<n>-<region>.pooler.supabase.com (the cluster number <n> is shown in your project’s Connect → Session pooler dialog — it varies per project)
  • Port: 5432 (session mode — not the 6543 transaction pooler)
  • User: postgres.<project-ref>
  • SSL: require

This is the connection shape Cloud builds automatically; it’s also what you’d put in a local .df-credentials.json.

Branch CI uses ephemeral branches

Section titled “Branch CI uses ephemeral branches”

For a pull request, SQLAnvil doesn’t touch your production database. It:

  1. Creates a disposable Supabase branch of your project (via the Management API),
  2. Runs the project against that fresh branch — models materialize and assertions execute,
  3. Reports the result, then destroys the branch so nothing is left billing.

Branching is available on Supabase Pro projects and works through the Management API directly — no GitHub-integration setup or supabase/ migrations directory required. SQLAnvil owns the full ephemeral-environment lifecycle.

Credentials

Section titled “Credentials”

Cloud brokers the branch credentials at run time and never stores your database password — see Warehouse connections.