prefect-dbt

With prefect-dbt, you can execute dbt Core from a Prefect flow with per-node observability, trigger and observe dbt Cloud jobs, and incorporate other tools, such as Snowflake, into your dbt runs. Prefect provides a global view of the state of your workflows and allows you to take action based on state changes.

Getting started

Prerequisites

A dbt adapter for your target database if using dbt Core (for example, dbt-duckdb, dbt-snowflake, or dbt-bigquery).
A dbt Cloud account if using dbt Cloud.

Install `prefect-dbt`

bash

pip install "prefect[dbt]"

This installs prefect-dbt and dbt-core, but not a dbt database adapter. For adapter-specific extras ([snowflake], [bigquery], [postgres], [all_extras]) and notes on adapters without a bundled extra such as dbt-duckdb, see the installation guide.

Start here

If you already have a dbt Core project with a working profiles.yml, the shortest path is PrefectDbtRunner:

python

from prefect import flow
from prefect_dbt import PrefectDbtRunner


@flow
def run_dbt():
    PrefectDbtRunner().invoke(["build"])


if __name__ == "__main__":
    run_dbt()

For a complete end-to-end flow that downloads a dbt project, runs it, and tests it, see the Run dbt with Prefect example.

dbt Core

prefect-dbt ships two interfaces for running dbt Core from a Prefect flow. PrefectDbtRunner has been available since 0.7.0; PrefectDbtOrchestrator first appeared in 0.7.17 but has picked up significant surface area since — cross-run caching and plan() in 0.7.20, DbtCloudExecutor in 0.7.19, and the raise_on_failure toggle in 0.7.23. Pin prefect-dbt>=0.7.23 to match the full guide. Both interfaces coexist and can be mixed within the same project — choose based on how much control you want Prefect to have over dbt's execution.

Interface	Execution model	Use when
`PrefectDbtRunner`	Reactive — dbt drives execution	You want `dbt build` semantics with Prefect observing each node as a task, plus asset lineage and templated `profiles.yml`.
`PrefectDbtOrchestrator` <sup>Beta</sup>	Proactive — Prefect drives each node/wave	You need per-node retries, cross-run caching, Prefect-native concurrency, dry-run planning, or dbt Cloud-backed execution.

For projects still using the pre-0.7.0 API (DbtCoreOperation, DbtCliProfile, and the TargetConfigs block hierarchy), see the Legacy guide.

dbt Cloud

Use the pre-built run_dbt_cloud_job flow to trigger dbt Cloud jobs from Prefect, with automatic retries for failed nodes. See the dbt Cloud guide for end-to-end setup with DbtCloudCredentials and DbtCloudJob blocks.

Resources

PrefectDbtRunner — reactive dbt Core execution with asset lineage.
PrefectDbtOrchestrator — proactive per-node / per-wave orchestration with retries, caching, and dbt Cloud support.
dbt Cloud — run dbt Cloud jobs from Prefect.
Run dbt with Prefect example — complete working flow.
Installation — adapter extras and detailed install options.
Legacy — prefect-dbt 0.6.6 and earlier.
prefect-dbt release notes — version history.
SDK reference — full prefect-dbt API.
dbt documentation — upstream dbt docs.