Skip to content
SQLAnvil SQLAnvil SQLAnvil

Supabase Integration

SQLAnvil is an open-source SQL workflow engine (a Dataform fork) with first-class Supabase support, plus a hosted control plane — SQLAnvil Cloud — that runs your project’s CI on ephemeral Supabase branches. This page is the end-to-end integration guide: what the integration does, how it connects to Supabase, and how to set it up.

What the integration provides

Section titled “What the integration provides”
  • SQL workflow modeling on Supabase. Tables, views, materialized views, incremental rollups, and data-quality assertions defined as .sqlx files, compiled to idiomatic Postgres DDL and executed in dependency order — no data warehouse required.
  • Supabase-native model types. RLS policies, Realtime publications, and pgvector indexes are first-class declarative actions that rebuild with the rest of the graph.
  • Branch-aware CI. Open a pull request and Cloud runs the full model graph against a disposable branch of your Supabase project, posts the check to the PR, and destroys the branch. Production is never touched.
  • Zero credential custody. You connect via Supabase OAuth; SQLAnvil never sees or stores your database password or service-role key.

How it connects to Supabase

Section titled “How it connects to Supabase”
Supabase surfaceWhat SQLAnvil uses it for
OAuthThe only authorization Cloud holds — an encrypted, revocable refresh token.
Management APICreating/destroying CI branches, minting short-lived per-run database roles, resolving connection details.
BranchingThe ephemeral environments PR CI runs against (requires a project on the Pro plan).
Session poolerAll database connections (IPv4, port 5432, user postgres.<ref>) — never the IPv6-only direct host.
PostgresModels compile to plain Postgres DDL/DML — COMMENT ON metadata, native indexes and partitioning included.

SQLAnvil Cloud’s own control plane also runs on Supabase (Postgres, Auth, RLS) — Supabase is both the integration target and the product’s system of record.

Set up: SQLAnvil Cloud (hosted CI)

Section titled “Set up: SQLAnvil Cloud (hosted CI)”

  1. Sign in at app.sqlanvil.com with GitHub and create a project.

  2. Connect your repo — install the SQLAnvil GitHub App and pick the repository holding your SQLAnvil project (the new-project wizard can scaffold one, or convert an existing Dataform project).

  3. Connect Supabase — in Settings → Supabase warehouse, click Connect Supabase and authorize on Supabase’s consent screen. Pick the warehouse project CI should branch off; it must be on the Pro plan (branch CI needs Supabase branching). See Supabase connections for details.

  4. Open a pull request. SQLAnvil creates an ephemeral Supabase branch via the Management API, runs the graph against it (models materialize, assertions execute), posts a SQLAnvil CI check on the PR, and destroys the branch.

Set up: OSS CLI (local / your own CI)

Section titled “Set up: OSS CLI (local / your own CI)”
Terminal window
npm i -g @sqlanvil/cli
sqlanvil init my_project --warehouse supabase

Add a gitignored .df-credentials.json with your Session pooler connection (host aws-<n>-<region>.pooler.supabase.com, port 5432, user postgres.<project-ref>, sslMode: "require" — the direct db.<ref>.supabase.co host is IPv6-only and fails on most networks), then:

Terminal window
sqlanvil compile my_project
sqlanvil validate my_project --credentials my_project/.df-credentials.json
sqlanvil run my_project --credentials my_project/.df-credentials.json

The Supabase guide covers the full modeling surface — connection shapes, the supabase: {} config block, RLS policies, Realtime publications, pgvector indexes, and incremental tables. Prefer a working example? Start from the supabase-sqlanvil-starter template.

Security & data handling

Section titled “Security & data handling”

Cloud stores an encrypted OAuth refresh token — never your database password or service-role key. Each run mints a short-lived Management-API access token and a per-run Postgres role that is dropped when the run finishes; you can revoke the authorization from your Supabase account at any time. Full details: Data handling.

Learn more

Section titled “Learn more”