Feat: Add lifecycle hooks to PrefectDbtRunner and PrefectDbtOrchestrator

[harsh21234i]

Fixes #21493 I’ve implemented this on a local branch and verified the focused prefect-dbt test suite.

Completed in this pass:

• Added failure-safe Python lifecycle hooks to PrefectDbtRunner
• Added failure-safe Python lifecycle hooks to PrefectDbtOrchestrator
• Added invocation, selector, node, orchestration, and wave-level hook support
• Added docs and release note coverage
• Added focused tests for the new hook behavior

Verification:

• uv run pytest tests/core/test_runner.py tests/core/test_orchestrator_per_wave.py tests/core/test_orchestrator_per_node.py -q
• 229 passed

[desertaxle]

Thanks for submitting a PR @harsh21234i!

I would take a slightly different approach to the interface. I think a decorator-based API would be better for readability and type checking.

Here's the shape I think this should take:

from prefect_dbt import PrefectDbtRunner, DbtHookContext

runner = PrefectDbtRunner()

@runner.on_run_start                        
def before_build(ctx: DbtHookContext): ...

@runner.post_model(select="tag:critical")
def on_critical_done(ctx: DbtHookContext):
    if ctx.status == "error":
        publish_metric(...)

@runner.on_run_end(select="tag:marts")
def after_marts(ctx: DbtHookContext): ...

runner.invoke(["build"])

[harsh21234i]

Thanks, that makes sense. I’ll follow the decorator-based API shape and keep the implementation aligned between PrefectDbtRunner and PrefectDbtOrchestrator. I’ll start by defining a typed DbtHookContext and wiring the run/model hook registration and execution path.

[harsh21234i]

Hello @desertaxle I updated the implementation to the decorator-based API you suggested. PrefectDbtRunner and PrefectDbtOrchestrator now expose decorator hooks with a typed DbtHookContext, including select=... filtering, and I added focused tests for registration, execution, filtering, and hook-failure isolation.

[harsh21234i]

I updated the implementation to the decorator-based API you suggested. PrefectDbtRunner now supports on_run_start, post_model(select=...), and on_run_end(select=...) with a typed DbtHookContext, and I applied the same hook shape to PrefectDbtOrchestrator as well. I also added focused tests for registration, execution, filtering, and hook-failure isolation.