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

# dbt

> Run SQLBuild alongside an existing dbt project.

# sqb dbt

Orchestrate dbt and SQLBuild together. Each subcommand runs dbt first, then SQLBuild, with selection logic that works across both project graphs. `sqb dbt build`, `sqb dbt run`, and `sqb dbt plan` are [change-aware](/concepts/dbt-compatibility/change-aware-builds): they prune dbt models that have not changed. See [Using SQLBuild with dbt](/concepts/dbt-compatibility/overview) for concepts and selection behavior.

## sqb dbt plan

Preview combined dbt and SQLBuild work without executing.

```bash theme={null}
sqb dbt plan [--select <selector>...] [--exclude <selector>...] [--json] [--verbose]
```

Shows which dbt models will run, which dbt models are current and pruned, which SQLBuild models will run, and the dbt/SQLBuild commands that would be executed.

## sqb dbt run

Run dbt models first, then SQLBuild models.

```bash theme={null}
sqb dbt run [--select <selector>...] [--exclude <selector>...]
```

## sqb dbt build

Build dbt models first (including dbt tests), then SQLBuild models with audits.

```bash theme={null}
sqb dbt build [--select <selector>...] [--exclude <selector>...]
```

## sqb dbt test

Run dbt tests first, then SQLBuild unit tests and audits for selected models.

```bash theme={null}
sqb dbt test [--select <selector>...] [--exclude <selector>...]
```

dbt's `test_type:data` and `test_type:unit` selectors are mapped: `test_type:data` runs SQLBuild audits, `test_type:unit` runs SQLBuild unit tests. Without a test type selector, both run.

## sqb dbt debug

Run dbt diagnostics followed by SQLBuild diagnostics.

```bash theme={null}
sqb dbt debug [--no-connection]
```

## Selectors

All `sqb dbt` commands accept `--select` and `--exclude`. Selectors work across both dbt and SQLBuild:

```bash theme={null}
# SQLBuild model with dbt dependencies
sqb dbt build --select downstream_orders

# Full upstream chain including dbt
sqb dbt build --select +downstream_orders

# Downstream of modified dbt models
sqb dbt build --select state:modified+

# SQLBuild models by tag
sqb dbt build --select tag:nightly

# SQLBuild models by path
sqb dbt build --select path:marts

# Exclude by tag
sqb dbt build --select fact_orders+ --exclude tag:nightly
```

See [Selection](/concepts/dbt-compatibility/selection) for full details on how selectors route work between dbt and SQLBuild.

## Configuration

Configure the dbt project location in `sqlbuild_project.toml`:

```toml theme={null}
[dbt]
project_dir = "../dbt_project"
profiles_dir = "../profiles"
target_path = "../dbt_project/target"
```

See [Project Configuration](/concepts/project-configuration#dbt) for all fields, including `replay_on_change` and `production_ref`.