{"id":4175,"library":"prefect-dbt","title":"Prefect dbt Integration","description":"Prefect-dbt is an official Prefect integration for orchestrating dbt (data build tool) projects within Prefect workflows. It provides tasks and blocks for interacting with the dbt CLI, allowing users to run dbt commands (like `dbt run`, `dbt test`, `dbt build`) as part of their data pipelines. The current version is 0.7.20, and it follows Prefect's release cadence for integrations, with updates typically coinciding with or following major Prefect releases.","status":"active","version":"0.7.20","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-dbt","tags":["prefect","dbt","data orchestration","etl","data transformation"],"install":[{"cmd":"pip install prefect-dbt","lang":"bash","label":"Install prefect-dbt"}],"dependencies":[{"reason":"Core dependency for Prefect flows and tasks.","package":"prefect","optional":false},{"reason":"Required in the execution environment to run dbt commands, but not a direct Python dependency of 'prefect-dbt' itself. Users must install dbt-core (or a specific adapter like dbt-postgres) separately.","package":"dbt-core","optional":true}],"imports":[{"symbol":"DbtCli","correct":"from prefect_dbt.cli import DbtCli"},{"symbol":"DbtCliProfile","correct":"from prefect_dbt.cli import DbtCliProfile"},{"note":"The `dbt_cli_task` function was a common direct import in older versions. It is now deprecated and the `DbtCli` class from `prefect_dbt.cli` is the recommended approach for improved functionality and block integration.","wrong":"from prefect_dbt import dbt_cli_task","symbol":"dbt_cli_task","correct":"from prefect_dbt.cli import dbt_cli_task"}],"quickstart":{"code":"import os\nfrom prefect import flow, get_run_logger\nfrom prefect_dbt.cli import DbtCli\n\n@flow(log_prints=True)\ndef dbt_cli_debug_flow():\n    \"\"\"\n    A simple Prefect flow that runs `dbt debug` using the prefect-dbt integration.\n    This demonstrates basic interaction with the dbt CLI via Prefect.\n    \"\"\"\n    logger = get_run_logger()\n    \n    # Initialize DbtCli. By default, it looks for dbt in the PATH\n    # and profiles.yml in the standard dbt locations or specified via env vars.\n    dbt_cli = DbtCli()\n    \n    logger.info(\"Attempting to run `dbt debug`...\")\n    \n    # Run the `debug` command. This checks dbt installation and profiles.\n    # It usually doesn't require a specific dbt project directory or database connection to run.\n    try:\n        debug_result = dbt_cli.debug()\n        \n        logger.info(f\"dbt debug completed with return code: {debug_result.return_code}\")\n        logger.info(f\"dbt debug stdout:\\n{debug_result.stdout}\")\n        \n        if debug_result.return_code != 0:\n            logger.error(f\"dbt debug stderr:\\n{debug_result.stderr}\")\n            raise RuntimeError(f\"`dbt debug` failed with return code {debug_result.return_code}\")\n            \n    except Exception as e:\n        logger.error(f\"Failed to execute dbt debug: {e}\")\n        logger.warning(\n            \"Ensure 'dbt-core' is installed in your execution environment \"\n            f\"(`pip install dbt-core` or specific adapter like `pip install dbt-postgres`).\"\n        )\n        raise\n\nif __name__ == \"__main__\":\n    dbt_cli_debug_flow() # For local execution\n    # To deploy: dbt_cli_debug_flow.to_deployment(name=\"dbt-debug-deployment\").apply()","lang":"python","description":"This quickstart demonstrates a simple Prefect flow that uses `prefect-dbt` to execute the `dbt debug` command. This is a good starting point as it verifies the dbt installation and profile configuration without requiring a full dbt project or database connection. For `dbt run`, `dbt test`, etc., you would typically set up a `DbtCliProfile` block in the Prefect UI and load it in your flow."},"warnings":[{"fix":"Migrate from `from prefect_dbt.cli import dbt_cli_task` to `from prefect_dbt.cli import DbtCli` and instantiate the class to call dbt commands (e.g., `DbtCli().run()`).","message":"The `dbt_cli_task` function has been deprecated in favor of the `DbtCli` class and its methods. The `DbtCli` class provides a more object-oriented interface and integrates better with Prefect Blocks for managing dbt profiles.","severity":"deprecated","affected_versions":"0.6.0 onwards"},{"fix":"Ensure `dbt-core` and your chosen dbt adapter are installed in your flow's execution environment using `pip install dbt-core [your-adapter]`.","message":"The `prefect-dbt` library acts as a wrapper for the dbt CLI. This means `dbt-core` (and any necessary dbt adapters like `dbt-postgres`, `dbt-bigquery`) must be installed separately in the environment where your Prefect flow runs. `prefect-dbt` does not automatically install `dbt-core`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Create a `DbtCliProfile` block in the Prefect UI with your dbt profile configuration. Then, load and pass this block to `DbtCli` (e.g., `DbtCli(dbt_profile=DbtCliProfile.load('my-profile'))`).","message":"Managing dbt profiles and credentials: While `prefect-dbt` can work with `profiles.yml` files in the execution environment, the recommended Prefect pattern for secure and centralized credential management is to use `DbtCliProfile` Blocks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the `prefect-dbt` documentation for supported `dbt-core` versions. Test your flows thoroughly after upgrading either `prefect-dbt` or `dbt-core`.","message":"Dbt CLI version compatibility: `prefect-dbt` is designed to work with various `dbt-core` versions, but significant changes in the dbt CLI's arguments or output can lead to unexpected behavior. Always verify compatibility with your specific `dbt-core` version.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}