Getting Started
Introduction
The refactorable warehouse. Verify early, test properly, and refactor safely.
SQLBuild is a free, open-source framework for SQL and Python data pipelines. It brings compile-time checks, tests and diffs to your warehouse, so you can change it as often as you change your code.
Valid SQL isn’t the same as correct SQL. A query can compile, run and return rows, and still produce a wrong number that people already trust. SQLBuild is built to catch that before it reaches production.
Verify early
Section titled “Verify early”Before anything runs, sqb compile analyses the whole project offline, with no warehouse
connection. It checks SQL, model references and declared contracts,
and traces column lineage. Rules turn
decisions from code review into compile errors, and
declaration scopes keep enums, constants and macros visible only
where they are used.
Test properly
Section titled “Test properly”SQL unit tests mock your sources, resolve every model in between from its real SQL, and compare the output with what you expect. Scenarios build the real model graph against test data, then replay it locally on DuckDB in CI. Audits check each build before it replaces production.
Refactor safely
Section titled “Refactor safely”sqb plan shows why each model will run and how much it will rebuild.
sqb diff compares real data between targets before a change ships. When you
rename a model, a migration moves its table instead of rebuilding
its history, and the janitor archives tables the project no longer builds before
it deletes them.
How it fits together
Section titled “How it fits together”| Step | Command | What it does |
|---|---|---|
| Compile | sqb compile |
Checks the project offline |
| Test | sqb test |
Runs SQL unit tests |
| Plan | sqb plan |
Shows what will run, why, and how much it will rebuild |
| Build | sqb build |
Runs tests, builds models in dependency order, and blocks bad data with audits |
| Compare | sqb diff |
Compares schemas and rows between two targets |
SQLBuild works with DuckDB, MotherDuck, Snowflake, BigQuery, Databricks, PostgreSQL and SQL Server. DuckDB runs locally, so you can try everything without warehouse credentials. See Adapters for connection setup.