Templaters (Jinja, dbt, SQLMesh)

Relevant source files

The following files were used as context for generating this wiki page:

• docsv/configuration/templating/index.md
• docsv/configuration/templating/jinja.md
• docsv/development/architecture.md
• plugins/sqlfluff-templater-dbt/pyproject.toml
• plugins/sqlfluff-templater-sqlmesh/pyproject.toml
• test/core/templaters/jinja_test.py

Templaters constitute the first stage of the SQLFluff pipeline. They transform "raw" SQL files containing placeholders, macros, or Jinja control logic into valid SQL strings that the lexer and parser can process. The templating engine ensures that modular code is expanded into a flat SQL format before linting rules are applied.

The system supports native engines like Jinja and external integrations like dbt and SQLMesh through a plugin architecture. After rendering, SQLFluff maps rule violations discovered in the rendered output back to the original source locations in the raw file.

Sources: docsv/configuration/templating/index.md:7-14, docsv/development/architecture.md:7-16

Templating Architecture

The templating process follows a three-step cycle to ensure linting accuracy while maintaining a connection to the original source code.

1. Pre-rendering: The templater evaluates the raw SQL and substitutes placeholders or executes macros to produce a "post-templated" SQL string.
2. Lint/Fix Application: SQLFluff applies linting rules and auto-fixes to the rendered SQL.
3. Backporting: SQLFluff maps any identified violations or fixes from the rendered locations back to the original "raw" sections for user reporting.

Sources: docsv/configuration/templating/index.md:15-19, docsv/development/architecture.md:12-16

Templating Data Flow

The following diagram illustrates how raw SQL moves through the templater into the standard SQLFluff pipeline.

Jinja Templater

The Jinja templater uses the Jinja2 engine to render templates. It allows for complex logic, including loops, conditional branches, and macro definitions. Users provide "dummy" values in the SQLFluff configuration to simulate the production environment required for rendering.

Sources: docsv/configuration/templating/index.md:21-25, docsv/configuration/templating/jinja.md:3-5

Configuration Methods

The Jinja templater supports several methods for providing variables and macros:

Method	Variables	Macros	Filters	Description
Config File	✅	✅	❌	Defined in .sqlfluff under [sqlfluff:templater:jinja:context].
Macro Path	❌	✅	❌	Loads .sql files from folders specified in load_macros_from_path.
Library	✅	✅	✅	Imports Python modules via library_path to expose custom filters/functions.

Sources: docsv/configuration/templating/jinja.md:9-15, docsv/configuration/templating/jinja.md:127-140

Advanced Jinja Features

• Custom Delimiters: You can configure non-standard delimiters, such as <% ... %> for variables, to support tools like Snowflake CLI.
• Built-in dbt Mocks: When apply_dbt_builtins is set to True, the templater provides mock versions of dbt-specific macros like ref(), source(), and config().
• JSON/YAML Helpers: Supports fromjson, tojson, fromyaml, and toyaml to mirror dbt's data transformation capabilities.

Sources: docsv/configuration/templating/jinja.md:46-55, docsv/configuration/templating/jinja.md:195-215, docsv/configuration/templating/jinja.md:220-235

dbt Templater

The dbt templater is provided as a separate plugin (sqlfluff-templater-dbt). It interfaces directly with the dbt Python package to leverage the project's own compilation environment.

• Project Integration: It reads the dbt_project.yml and profiles to understand the macro context and dependencies.
• Configuration: Requires the project_dir to be specified in the .sqlfluff configuration.
• Dialect Support: Supports a wide range of dialects including BigQuery, Snowflake, and Redshift.

Sources: plugins/sqlfluff-templater-dbt/pyproject.toml:34-53, docsv/development/architecture.md:23-25

SQLMesh Templater

The SQLMesh templater (sqlfluff-templater-sqlmesh) allows users to lint SQL files within a SQLMesh project. Like the dbt templater, it is packaged as a plugin and requires the sqlmesh library as a dependency.

Sources: plugins/sqlfluff-templater-sqlmesh/pyproject.toml:44-48, docsv/configuration/templating/index.md:36-37

Variant Rendering

Templaters render specific branches of code (e.g., inside an {% if %} block). By default, code in unreached branches is not linted. SQLFluff supports "Template Variant Rendering" for the Jinja and dbt templaters, allowing the engine to render multiple versions of a file to cover different conditional paths.

Sources: docsv/configuration/templating/index.md:42-53, test/core/templaters/jinja_test.py:1085-1100

Variant Selection Sequence

Summary of Templater Dependencies

Templater	Source	Main Dependency	Plugin Entry Point
Jinja	Core	Jinja2	N/A (Native)
dbt	Plugin	dbt-core	sqlfluff_templater_dbt
SQLMesh	Plugin	sqlmesh	sqlfluff_templater_sqlmesh

Sources: plugins/sqlfluff-templater-dbt/pyproject.toml:57-59, plugins/sqlfluff-templater-sqlmesh/pyproject.toml:53-55, docsv/configuration/templating/index.md:30-37

The templating system is critical for modern data stacks where SQL is rarely static. By pre-rendering code and maintaining detailed source maps (slices), SQLFluff provides the modularity of templating engines with the rigorous quality assurance of a static linter.