Hooks

Pre-hooks and post-hooks run before and after materialization. Each entry is either sql("...") or python("hook_name").

SQL hooks

MODEL (
  materialized table,
  post_hooks [sql('GRANT SELECT ON @@CTX:destination.qualified TO analyst_role')],
);

SQL hooks support macros, project variables, environment variables, and context variables. Hook SQL is syntax-validated when the model’s effective SQL-validation gate is enabled: SQL analysis must be enabled, --no-sql-validation must be absent, and the effective project or model sql_validation value must be true.

Variable	Value
`@@CTX:destination.qualified`	Fully qualified destination relation
`@@CTX:destination.schema`	Destination schema
`@@CTX:destination.table`	Destination relation name
`@@CTX:model.name`	Model name
`@@CTX:run.target`	Active target name
`@@CTX:run.id`	Current run ID

Python hooks

SQLBuild discovers @hook functions recursively under hooks/:

from sqlbuild.hooks import hook

@hook
def grant_analyst(ctx, role="analyst_role"):
    ctx.execute_sql(f"GRANT SELECT ON {ctx.destination.qualified} TO {role}")

Reference the hook by name and optionally pass keyword arguments:

MODEL (
  materialized table,
  post_hooks [python("grant_analyst", role: "reader_role")],
);

SQL and Python hooks can appear in the same list.

Hook context

Python hooks declare a HookContext parameter named ctx, context, _ctx, or hook_context. It need not be the first parameter when providers or configured arguments are also present:

Field	Description
`ctx.model_name`	Model being built
`ctx.phase`	`pre_hooks` or `post_hooks`
`ctx.hook_name`	Invoked hook name
`ctx.run_id`	Current run ID
`ctx.target`	Active target
`ctx.vars`	Effective project variables
`ctx.destination`	Destination relation metadata
`ctx.adapter`	Adapter instance
`ctx.connection`	Live connection
`ctx.execute_sql(sql)`	Execute SQL
`ctx.query(sql)`	Execute SQL and return rows
`ctx.log(message)`	Write run output
`ctx.skip(reason="...", mode="soft")`	Return a soft or hard skip result; arguments are keyword-only
`ctx.providers`	Access discovered providers

Providers may also be injected into hook parameters by name.

Skip timing

Returning ctx.skip(...) from a pre-hook prevents materialization. Returning it from a post-hook changes the reported execution result, but the relation has already been created, promoted, or incrementally updated and audited. mode="hard" blocks downstream nodes. A soft skip does not automatically block every downstream node; scheduler propagation depends on the other upstream results.

Failure timing

Post-hooks are not promotion gates. A failed post-hook marks the model run as failed after warehouse mutation has already occurred. Put logic that must prevent materialization in a pre-hook, contract, pre-promotion audit, or the materialization itself.

Discovery and validation

Files beginning with _, including __init__.py, are skipped.
Hook names must be unique across the project.
The decorator accepts optional name and description arguments.
Unknown hooks, unknown keyword arguments, and missing required arguments fail compilation.
A function without **kwargs rejects undeclared hook arguments.

Getting Started

dbt Compatibility

Concepts

Python Nodes

Virtual Environments (Alpha)

Integrations

CLI Reference

SQL hooks

Python hooks

Hook context

Skip timing

Failure timing

Discovery and validation

​SQL hooks

​Python hooks

​Hook context

​Skip timing

​Failure timing

​Discovery and validation

SQL hooks

Python hooks

Hook context

Skip timing

Failure timing

Discovery and validation