Using SQLBuild with dbt

Use the dbt compatibility bridge to coordinate dbt selections with SQLBuild-owned models downstream of their outputs.

SQLBuild reads the dbt manifest and drives the dbt CLI as a subprocess. dbt remains responsible for compiling and executing dbt-owned models; SQLBuild statically analyzes and executes only SQLBuild-owned models downstream. Change-aware execution is not supported by the bridge.

Start with your existing dbt project

From inside your dbt project, run a sqb dbt command. Scope dbt work with familiar --select values, or omit selection to plan the whole project.

sqb dbt plan --select path:models/marts

The first time you do this, SQLBuild bootstraps itself. If there is no sqlbuild_project.toml, it reads your dbt_project.yml and profile and creates a minimal twin project in a sqlbuild_project/ directory next to your dbt project. It reuses your dbt profile for the warehouse connection, so there are no separate credentials to configure.

my-workspace/
  analytics/                  # your existing dbt project, untouched
    dbt_project.yml
    models/
    target/
      manifest.json
  sqlbuild_project/           # created by SQLBuild
    sqlbuild_project.toml     # points at the dbt project, no models of its own

The generated sqlbuild_project.toml looks like this:

name = "analytics"
adapter = "snowflake"
default_target = "dev"

[dbt]
project_dir = "../analytics"
profiles_dir = "/Users/you/.dbt"
target_path = "../analytics/target"
target = "dev"

[connections.dbt_dev]
source = "dbt_profile"
profile = "analytics"
target = "dev"

[targets.dev]
connection = "dbt_dev"
database = "ANALYTICS"
schema = "analytics"

source = "dbt_profile" on the named connection tells SQLBuild to connect using your dbt profile, so it talks to the same warehouse dbt does. The target references that connection and remains authoritative for its database and schema.

sqb dbt build --select path:models/marts compiles the project, resolves the selection, runs the selected dbt models, then runs any SQLBuild models you have added against the dbt outputs.

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 resolves your --select/--exclude against dbt by running dbt ls, so dbt-native selectors like state:modified and package: are evaluated by dbt itself, not reimplemented
4. sqb dbt plan/run/build orchestrates the run: dbt executes the selected dbt work
5. (Optional) any SQLBuild models you have added run last, against the dbt outputs

Each step calls the dbt CLI directly: dbt compile for the manifest, dbt ls for selection, and dbt build/dbt run for execution.

Flags

sqb dbt plan/run/build declare the common flags directly. Anything declared goes before a -- separator; any other raw dbt flag goes after it and is forwarded verbatim. A flag placed on the wrong side errors rather than silently reaching dbt.

sqb dbt build --select path:models/marts --full-refresh

Declared flags are routed to the right place automatically:

Flag	Routed to	Notes
--select / --exclude	dbt	dbt resolves selection (see Selection).
--vars	dbt and SQLBuild	The same vars feed dbt’s compile and SQLBuild’s own variable resolution, so both sides see identical values.
--full-refresh	dbt and SQLBuild	Requests a full rebuild on both sides. dbt and native SQLBuild models independently apply their model-level full_refresh setting, including false opt-outs.
--threads	dbt (--threads) and SQLBuild (--concurrency)
--target / --project-dir / --profiles-dir / --profile / --target-path	dbt	Standard dbt locators.

--vars

--vars accepts the same JSON object dbt accepts, and SQLBuild passes it to both the underlying dbt invocation and its own variable resolution. That means a value referenced as @@my_var in SQLBuild model SQL (see Interpolation) and as {{ var('my_var') }} in a dbt model both resolve to the value you passed. CLI vars take precedence over project and local config vars. You do not need to declare vars twice.

sqb dbt build --select path:models/marts --vars '{"my_var": 1}'

Forwarding other dbt flags

For any native dbt flag SQLBuild does not declare, put it after -- and it is passed straight to the dbt invocation untouched:

sqb dbt build -- --log-level debug

Configuration

The auto-generated project above is editable, and you can write sqlbuild_project.toml by hand. The [dbt] block (shown in the generated project above) accepts:

Field	Description
project_dir	Path to the dbt project root (where dbt_project.yml lives)
profiles_dir	Path to the directory containing profiles.yml
target_path	Path to dbt’s target/ directory (where manifest.json is written)
target	dbt target name override (optional)

Paths can be absolute or relative to the SQLBuild project root.

Prerequisites

• dbt must be installed and available on PATH as dbt
• Both projects must target the same warehouse and schema/database context

SQLBuild uses your own dbt install; it does not bundle or install dbt. If your dbt is not reachable as a bare dbt on PATH (for example, you run it via uv, poetry, or a wrapper), set the DBT_EXECUTABLE environment variable to the executable SQLBuild should call.

SQLBuild runs dbt compile automatically as part of sqb dbt plan/run/build to produce the manifest. You do not need to compile the dbt project manually.

Debugging

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

sqb dbt debug

On this topic

• Selection - how --select and --exclude route work across both graphs.
• Adding SQLBuild models - optionally write SQLBuild models, tests, audits, and scenarios downstream of dbt.