Skip to main content
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. sqb dbt runs in direct mode, so change-aware execution and virtual environments are 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.
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.
The generated sqlbuild_project.toml looks like this:
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.
Declared flags are routed to the right place automatically:

​
--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.

​
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:

​
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: 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).

​
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.