sqlanvil Engineering Fundamentals

Overview

sqlanvil is a fork of Dataform repositioned for PostgreSQL and Supabase. Your Dataform/BigQuery instincts are mostly right — .sqlx files, config {} blocks, ${ref()}, ${self()}, declarations, assertions, tags, incremental tables, pre_operations/post_operations all work the same. This skill is the delta: the specific places where assuming Dataform/BigQuery produces broken sqlanvil code.

Core principle: When the warehouse is Postgres/Supabase, reach for the postgres: {} config block and idiomatic Postgres — never BigQuery options or hand-rolled DDL workarounds.

REQUIRED FOUNDATION: TDD applies — see superpowers:test-driven-development. For warehouse-agnostic architecture, layering, ${ref()} discipline, and columns:{} documentation standards, the rules in dataform-engineering-fundamentals carry over unchanged (just swap BigQuery specifics for the deltas below).

Authoritative config reference: protos/configs.proto in the sqlanvil repo (PostgresOptions, PostgresConnection, ConnectionConfig, TableConfig, IncrementalTableConfig, ViewConfig, DeclarationConfig). When unsure of a field, read the proto — it is the source of truth.

When to Use

• Writing any .sqlx model, workflow_settings.yaml, or .df-credentials.json for a sqlanvil project on Postgres/Supabase
• Adding indexes, partitioning, storage options, materialized views, or stored procedures
• Reading a source table from another warehouse (BigQuery, or a second Postgres) — named connections + introspect
• Translating an existing Dataform/BigQuery project to sqlanvil/Postgres
• Any time you're about to write bigquery: {}, partitionBy, dataform.json, method: "btree", or ; between statements — STOP and check the deltas