dbt pre-hook / post-hook Deep Dive: Practical Patterns and Exam Prep

pre-hooks and post-hooks let you inject SQL or macros immediately before or after each node (model, snapshot, seed, etc.) runs. They are useful for automating grants, audit logging, statistics refreshes, and similar tasks.

This article assumes the stable behavior described in the official docs and lays out the precautions you need to use hooks safely in production, plus the comparison points that come up on the Analytics Engineer exam.

Core Concepts and Scope

A pre-hook is evaluated and executed immediately before its node runs; a post-hook runs immediately after. Hook bodies can be templated with Jinja and have access to context such as this, target, var, and env_var.

These are node-level hooks, distinct from on-run-start / on-run-end, which fire only once at the start or end of the entire project run.

• Applies to: models, snapshots, and seeds (ephemeral models are excluded)
• Execution unit: evaluated and run per target node (skipped nodes do not trigger hooks)
• Defined in: a model file's config() block, or dbt_project.yml (+pre-hook/+post-hook)
• Contents: raw SQL strings, Jinja expressions, or macro calls
• Official: a stable feature documented in the dbt Docs Hooks page

Execution Order and Transaction Handling

Across a full dbt run, on-run-start fires once at the very beginning. Then, for each node, dbt runs pre-hook → main SQL → post-hook in order, and finally on-run-end fires once at the end.

On most adapters, the main SQL and the pre/post hooks share a single transaction. Setting transaction: false (on adapters that support it) runs the hook in its own transaction. Auto-commit behavior for DML/DDL is warehouse-specific, so it is safer to isolate things like grants and session settings when appropriate.

• On pre-hook failure: the node is marked failed and the main SQL and post-hook are skipped
• On post-hook failure: the node is marked failed, but the relation may already have been created or updated
• Hooks defined in multiple scopes are merged and run in declaration order from top to bottom. Consolidate definitions in one place when order matters
• Note that warehouses with auto-committed DDL (e.g. some Snowflake DDL) ignore transaction boundaries for those statements

Where hooks fit in the dbt run lifecycle

Representative Use Cases (Grants, Audit Logs, Session Settings)

Post-hooks are well suited for grants and statistics refreshes against a relation that was just created or replaced. Pre-hooks fit prep work such as cleaning staging areas or temporary tables before the main SQL runs.

For session- or query-level settings, combine hooks with sql_header and adapter-specific config (such as Snowflake's query_tag) for a more robust result.

• Grants (post-hook): grant select on {{ this }} to role ...
• Audit logging (pre/post): insert into an audit table to record model name, environment, and timestamp
• Optimization and statistics (post): analyze/vacuum on Redshift, optimize/analyze on Databricks, etc.
• Session settings (pre or sql_header): Snowflake query_tag, warehouse switching, etc.
• Housekeeping (pre): cleaning up staging areas and work tables

Configuration and Authoring Patterns (dbt_project.yml / config() / Macros)

You can apply hooks broadly through dbt_project.yml model hierarchies or individually via a model's config() block. Multiple entries can be declared as a list and run top-to-bottom, and macro calls are allowed.

Where the adapter supports it, transaction: false isolates the hook in its own transaction. This is helpful for grants, logging, and other operations you do not want rolled back together with the main SQL on failure.

• Bulk application: centralize grants and shared logging in dbt_project.yml
• Per-model application: keep model-specific pre/post logic in the model's config()
• Jinja: this, target, var, and env_var are available; use the log() macro for logging

Examples (dbt_project.yml, in-model config, and a macro)

# dbt_project.yml (excerpt)
models:
  my_project:
    +post-hook:
      - sql: grant select on {{ this }} to role ANALYST
        transaction: false
      - "{{ log('built ' ~ this, info=True) }}"

# models/fct_orders.sql (per-model hooks)
{{ config(
    materialized='table',
    pre_hook=[
      "delete from {{ ref('load_control') }} where model='{{ this.identifier }}'"
    ],
    post_hook=[
      "{{ insert_audit_record(this, 'fct_orders') }}"
    ]
) }}

select *
from {{ ref('stg_orders') }}

# macros/insert_audit_record.sql (audit-log macro)
{% macro insert_audit_record(relation, model_name) %}
  {% if execute %}
  insert into {{ ref('audit_log') }}(model, relation, executed_at, environment)
  values ('{{ model_name }}', '{{ relation }}', current_timestamp, '{{ target.name }}');
  {% endif %}
{% endmacro %}

Comparing pre / post / on-run and Exam Focus Points

On the Analytics Engineer exam, the typical talking points are hook granularity, execution timing, and transaction boundaries. Be ready to instantly pick the right hook for a given scenario.

In particular, memorize this split: on-run-start/end for once-per-run audit records, post-hook for grants applied to each model, and pre-hook for prep-time cleanup.

• Use pre/post for node-level work and on-run for run-level work
• Prefer the grants config when it is available; fall back to post-hook for more complex logic
• Choose the transaction setting based on how you want rollback to behave on failure

Pitfalls and Best Practices

Hooks are powerful, but mishandling transaction boundaries or ordering can lead to unintended side effects. The following guidelines keep things stable.

• For grants, prefer dbt's grants config where supported and fall back to post-hook for complex role logic or unsupported adapters
• Keep hook SQL idempotent (existence checks, create or replace, grants that tolerate re-execution)
• When order matters, consolidate definitions in one place and avoid duplicating them in both the project and the model
• For settings that should apply to the whole session, prefer sql_header or adapter-provided settings over pre-hook (which is per-node)
• When writing to a shared audit table, design for key collisions and locking
• Debug with dbt compile, --debug, log() output, and run-operation for isolated macro testing

Practice Question

Frequently Asked Questions