Verify early. Test properly. Deploy reversibly. SQL pipelines with the rigor of real software.
Valid isn't the same as correct. Your SQL compiles, runs, and returns rows; none of that means the number is right, and a silently-wrong number a stakeholder already trusted is the bug that actually hurts.
SQLBuild brings software-engineering rigor to SQL pipelines: catch errors before the warehouse runs them, test your logic locally, and opt into change-aware execution when you need it. It works as a standalone framework or points at your existing dbt project with no migration and no edits to your dbt files.
All state is persisted as append-only tables in the warehouse alongside your data: no external state database, no manifest files, no paid add-on. It keeps a low, dbt-like floor for SQL models and adds ingestion, Python nodes, and opt-in virtual environments as your project grows.
Key features
- Test your logic, not just your columns. Chained SQL unit tests resolve every intermediate model from its real SQL, plus end-to-end scenarios with local DuckDB replay for fast CI with no warehouse. Catch wrong logic before it ships, not just nulls.
- Verify early. Define models as SQL files with
MODEL()headers. SQLBuild resolves references, validates SQL, infers columns, checks contracts, and computes column lineage before anything runs, all offline. It fails at compile, not halfway through a warehouse run. - Fast and open static analysis. SQL parsing, validation, column inference, lineage, and transpilation run on Polyglot, a Rust SQL engine (MIT, 32+ dialects), so compile stays fast on large projects. The analysis is part of the Apache-2.0 core: no proprietary engine, no login, no paid tier.
- Audits that block bad data. Audits run before data reaches the target table. Full table builds materialize into a staging table and only promote if audits pass; incremental models validate each batch before DML.
- Deploy reversibly (opt-in). Virtual environments add instant low-copy branching, partial promotion, rollback, checkpoints, and reconciliation. Opt-in, not a tax you pay upfront.
- Opt-in change-aware execution. Models, seeds, UDFs, and Python nodes are fingerprinted, and source freshness is tracked. Commands run the selected work by default; pass
--changes-onlyor setchanges_only = trueto skip work that is already current. - Works with your existing dbt project. Point SQLBuild at a dbt project and opt into change-aware builds with zero SQLBuild models. It reads the manifest and drives the
dbtCLI as a subprocess; it never edits your dbt files.sqb dbt cloneandsqb dbt diffwork against a production-shaped git ref. See dbt compatibility. - Warehouse-native state. All change-tracking state lives in append-only tables (
_sqlbuild_fingerprints,_sqlbuild_source_freshness,_sqlbuild_node_results) in your warehouse schemas. No external state machine, no corruption risk. - Cursor-based incremental processing. Automatic gap detection and resume, with microbatch mode for large ranges. No external checkpoint to maintain.
- Ingestion and Python nodes. Load external data with Python
@loaderfunctions, and run@task,@asset, and@checknodes as first-class members of the same DAG as your SQL models.
See the documentation for the full feature set, including providers, lifecycle hooks, Python macros, UDFs, custom materializations, data diffs, zero-copy cloning, and virtual environments.
Enable change-aware execution for individual commands with --changes-only, for a project with [settings], or for one target:
[settings]
changes_only = true
[targets.dev]
changes_only = true
The CLI flag takes precedence, followed by the selected target, explicit local settings, and project settings. For plan, build, and sqb dbt execution, the full selected scope runs when no configuration source enables changes-only mode; the former execution --force option is no longer used.
Works with your existing dbt project
Point SQLBuild at a dbt project and run a sqb dbt command. The first time, it bootstraps a minimal twin project from your dbt_project.yml and profile (reusing your dbt connection), then builds your selection with state recorded:
sqb dbt build --select path:models/marts
Run it again with --changes-only and models that have not changed are skipped:
sqb dbt build --changes-only --select path:models/marts
dbt (3 selected resources)
planned models: 0 run, 3 current, 0 blocked
skipped: all planned dbt models are current
Change one model and only that model, plus whatever depends on it, rebuilds when --changes-only is enabled. SQLBuild fingerprints your dbt models in the warehouse and prunes everything that is already current. Your --select scope is always respected, and where it matters SQLBuild warns you about stale upstreams or downstreams left outside the selection. See dbt compatibility.
Quick start
pip install sqlbuild
# or
uv pip install sqlbuild
Create and run the included playground project:
sqb playground waffle-shop
cd waffle-shop
sqb plan
sqb build
sqb test
Example
A model is a SQL file with a MODEL() header and a SELECT. References use __ref() and __source(), and configuration, schema, and audits are declared inline:
MODEL (
materialized table,
columns (
order_id (audits [not_null, unique]),
),
tags [marts],
);
SELECT
o.order_id,
o.customer_id,
p.amount_cents AS total_cents
FROM __ref("stg_orders") o
JOIN __ref("stg_payments") p USING (order_id)
A unit test mocks sources and asserts on the model, resolving every intermediate model automatically:
TEST();
WITH
__source__raw__orders AS (
@mock_orders()
),
__source__raw__payments AS (
SELECT
1 AS payment_id,
1 AS order_id,
1500 AS amount_cents,
'credit_card' AS method
),
__expected__fact_orders AS (
SELECT 1 AS order_id, 100 AS customer_id, 1500 AS total_cents
)
SELECT 1
See the documentation for incremental models, scenarios, loaders, and more.
Supported adapters
| Adapter | Status |
|---|---|
| DuckDB | Supported |
| MotherDuck | Supported |
| Snowflake | Supported |
| BigQuery | Supported |
| Databricks | Supported |
| PostgreSQL | Supported |
| SQL Server | Supported |
ClickHouse, Redshift, Trino, Spark, and Athena are on the way.
Documentation
Full documentation is available at docs.sqlbuild.com.
Contributing
We welcome contributions. Please see CONTRIBUTING.md for guidelines.
License
SQLBuild is licensed under the Apache License 2.0.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sqlbuild-0.48.0.tar.gz.
File metadata
- Download URL: sqlbuild-0.48.0.tar.gz
- Upload date:
- Size: 3.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
85c3be7bf07ad7b1747a9ad3f401ac99b1e118262d248d543cc8faa49e130612
|
|
| MD5 |
9120f1b5f137f76ba2afce58d7eba07f
|
|
| BLAKE2b-256 |
8a61e4838c6dc5707e791b9cd39f28afab176df1b975e41743f832a803a2013b
|
Provenance
The following attestation bundles were made for sqlbuild-0.48.0.tar.gz:
Publisher:
publish.yml on chio-labs/sqlbuild
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sqlbuild-0.48.0.tar.gz -
Subject digest:
85c3be7bf07ad7b1747a9ad3f401ac99b1e118262d248d543cc8faa49e130612 - Sigstore transparency entry: 2223349091
- Sigstore integration time:
-
Permalink:
chio-labs/sqlbuild@4f619dbcc1dc8fc7159acbf6ab6aa19dea055663 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/chio-labs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@4f619dbcc1dc8fc7159acbf6ab6aa19dea055663 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file sqlbuild-0.48.0-py3-none-any.whl.
File metadata
- Download URL: sqlbuild-0.48.0-py3-none-any.whl
- Upload date:
- Size: 1.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ecf09e6d922733ce74a5bbff75b0c5e045a9536495d40ce815f62a9a28f12c97
|
|
| MD5 |
61372538babe007601fcb539d51af68d
|
|
| BLAKE2b-256 |
25925f58c982e2c61cf07630719e090f1b878d5b0d99c04b3869e3fd5ee21b72
|
Provenance
The following attestation bundles were made for sqlbuild-0.48.0-py3-none-any.whl:
Publisher:
publish.yml on chio-labs/sqlbuild
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sqlbuild-0.48.0-py3-none-any.whl -
Subject digest:
ecf09e6d922733ce74a5bbff75b0c5e045a9536495d40ce815f62a9a28f12c97 - Sigstore transparency entry: 2223349784
- Sigstore integration time:
-
Permalink:
chio-labs/sqlbuild@4f619dbcc1dc8fc7159acbf6ab6aa19dea055663 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/chio-labs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@4f619dbcc1dc8fc7159acbf6ab6aa19dea055663 -
Trigger Event:
workflow_dispatch
-
Statement type:
