Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt

Use this file to discover all available pages before exploring further.

SQLBuild can run alongside an existing dbt project. Your dbt models stay in dbt. New models, tests, audits, and scenarios are written in SQLBuild and can reference dbt model outputs directly. No migration required.

​
How it works

  1. SQLBuild runs dbt compile to produce a manifest.json with model metadata
  2. SQLBuild reads the manifest to understand dbt model names and their qualified warehouse tables
  3. SQLBuild models reference dbt models using __dbt_ref("package", "model")
  4. sqb dbt plan/run/build/test orchestrates both sides: dbt runs first, then SQLBuild runs against the dbt outputs
dbt is always invoked as a subprocess - SQLBuild does not reimplement Jinja, profiles, or any dbt internals. It calls the dbt CLI for compilation, selection, and execution.

​
Setup

​
Project layout

A typical layout has both projects side by side: 
my-workspace/
  dbt_project/
    dbt_project.yml
    models/
      staging/stg_orders.sql
      marts/fact_orders.sql
    target/
      manifest.json
  profiles/
    profiles.yml
  sqlbuild_project/
    sqlbuild_project.toml
    models/
      marts/downstream_orders.sql
    tests/
      unit/test_downstream_orders.sql

​
Configuration

Point SQLBuild at the dbt project in sqlbuild_project.toml: 
[dbt]
project_dir = "../dbt_project"
profiles_dir = "../profiles"
target_path = "../dbt_project/target"
FieldDescription
project_dirPath to the dbt project root (where dbt_project.yml lives)
profiles_dirPath to the directory containing profiles.yml
target_pathPath to dbt’s target/ directory (where manifest.json is written)
targetdbt target name override (optional)
Paths can be absolute or relative to the SQLBuild project root.

​
Referencing dbt models

SQLBuild models use __dbt_ref("package", "model") to reference dbt model outputs: 
MODEL (
  tags [finance],
  columns (order_id (audits [not_null])),
);

SELECT order_id FROM __dbt_ref("analytics", "fact_orders")
This resolves to the qualified warehouse table name from the dbt manifest (e.g. analytics.fact_orders). The dbt model becomes an upstream dependency in the combined graph. SQLBuild models can also reference other SQLBuild models with __ref() as usual: 
MODEL (tags [marts]);

SELECT order_id FROM __ref("downstream_orders")

​
Selection behavior

The sqb dbt commands use --select and --exclude to scope what runs. Selectors work across both dbt and SQLBuild, with the system determining which side owns each selector and how to route work.

​
SQLBuild-recognized selectors

These selectors match SQLBuild models directly:
SelectorExampleBehavior
Model namefact_ordersSelects that SQLBuild model. Auto-includes its immediate dbt upstream dependencies.
Leading ++fact_ordersSelects the model plus walks upstream through both SQLBuild and dbt models.
Trailing +fact_orders+Selects the model plus all downstream SQLBuild models.
Both ++fact_orders+Full upstream (including dbt) and downstream expansion.
Tagtag:nightlySelects all SQLBuild models with that tag. Auto-includes dbt dependencies.
Tag with ++tag:nightlyTag match plus upstream expansion through the combined graph.
Pathpath:martsSelects SQLBuild models under that directory. dbt-style path:models/marts is translated automatically.
Path with ++path:martsPath match plus upstream/downstream expansion.
When a SQLBuild model is selected, its immediate dbt upstream dependencies are always included so dbt can build the tables that SQLBuild models read from.

​
dbt-only selectors

Selectors that SQLBuild does not recognize (like state:modified, package:stripe, source:stripe.charges) are passed to dbt ls to resolve:
SelectorExampleBehavior
Without +state:modifieddbt-only work. No SQLBuild models selected.
With trailing +state:modified+SQLBuild runs dbt ls to find which dbt models match, then walks downstream into SQLBuild territory.
With both ++state:modified+Same downstream expansion, plus upstream dbt expansion.
This means you can use dbt-native selectors like state:modified+ to trigger rebuilds of SQLBuild models that depend on changed dbt models. If dbt ls returns no matching models, no SQLBuild work is triggered.

​
Exclude

--exclude removes matching SQLBuild models from the final selection: 
sqb dbt build --select fact_orders+ --exclude tag:nightly

​
Examples

# Build a specific SQLBuild model and its dbt dependencies
sqb dbt build --select downstream_orders

# Build everything downstream of a SQLBuild model
sqb dbt build --select downstream_orders+

# Build a SQLBuild model with full upstream dbt chain
sqb dbt build --select +downstream_orders

# Build SQLBuild models downstream of modified dbt models
sqb dbt build --select state:modified+

# Build all SQLBuild models tagged "nightly" with their dbt dependencies
sqb dbt build --select tag:nightly

# Build SQLBuild models under a path
sqb dbt build --select path:marts

​
Execution order

For sqb dbt run and sqb dbt build:
  1. dbt runs first - a single dbt run/build command executes with the user’s selectors merged with any additional dbt models required by selected SQLBuild models
  2. SQLBuild runs second - selected SQLBuild models execute against the now-built dbt tables
For sqb dbt test:
  1. dbt test runs first - with the user’s original selectors
  2. SQLBuild test runs - unit tests for selected SQLBuild models
  3. SQLBuild audit runs - audits for selected SQLBuild models
The test_type:data and test_type:unit selectors from dbt are mapped to SQLBuild equivalents: test_type:data runs SQLBuild audits, test_type:unit runs SQLBuild unit tests.

​
Unit tests with dbt refs

SQLBuild unit tests can mock dbt model dependencies using __dbt_ref__ fixture CTEs. When a model has a package, use __dbt_ref__package__model. When there is no package, use __dbt_ref__model: 
TEST();

WITH
__dbt_ref__analytics__fact_orders AS (
  SELECT 1 AS order_id, 100 AS customer_id, 2500 AS amount_cents
),
__expected__downstream_orders AS (
  SELECT 1 AS order_id
)
SELECT 1
This mocks the dbt model analytics.fact_orders with controlled data, allowing you to test your SQLBuild model without a warehouse connection or a compiled dbt manifest.

​
Debug

sqb dbt debug runs both dbt’s and SQLBuild’s diagnostics: 
sqb dbt debug
This runs dbt debug (verifying dbt project config and warehouse connection) followed by sqb debug (verifying SQLBuild project config and connection).

​
Prerequisites

  • dbt must be installed and available on PATH
  • Both projects must target the same warehouse and schema/database context
SQLBuild runs dbt compile automatically as part of sqb dbt plan/run/build/test to produce the manifest. You do not need to compile the dbt project manually.