Introduction

SQLBuild is a free, open-source framework for SQL and Python data pipelines. It brings compile-time checks, end-to-end tests and safe renames to your warehouse, so you can change it as often as you change your code.

SQLBuild compiles, checks and plans your project in Rust. Warehouse execution stays in Python, as do your macros, Python hooks, loaders and custom rules.

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

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

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

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 or move a model with sqb rename and sqb mv, every reference is updated, a migration moves its table instead of rebuilding its history, and the old name keeps working as a view. Columns can be renamed the same way. The janitor archives tables the project no longer builds before it deletes them.

Investigate

Recall records every command: what ran, the SQL it executed, audit results and everything it printed. Agents and people query that history with SQL through sqb recall, then check live state in the warehouse with the same command.

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
Review	sqb review	Builds a branch’s changes in a temporary schema, tests them and compares them with a target
Investigate	sqb recall	Queries the history of past runs, then live warehouse state

SQLBuild works with DuckDB, MotherDuck, Snowflake, BigQuery, Databricks, PostgreSQL, SQL Server, ClickHouse and SQLite. DuckDB runs locally, so you can try everything without warehouse credentials. See Adapters for connection setup.

Where to start

Quickstart

Build a complete example project locally in a minute.

Coming from dbt

Run SQLBuild alongside an existing dbt project.

Concepts

Models, tests, audits, planning and the rest.

CLI reference

Every command and flag.