Registry / testing / sqlfluff-templater-dbt

sqlfluff-templater-dbt

JSON →
library4.1.0pypypiunverified

SQLFluff-templater-dbt is a plugin for SQLFluff, the SQL linter for humans, specifically designed to correctly parse and compile SQL projects using dbt (data build tool). It extends SQLFluff's capabilities to lint dbt models by leveraging dbt's templating engine. The project releases in conjunction with the main SQLFluff library, with version 4.1.0 being the latest as of March 2026. [2, 5, 13]

pip install sqlfluff sqlfluff-templater-dbt dbt-core dbt-snowflake # Replace dbt-snowflake with your adapter
INSTALL
IMPORT
SIG · SQLFLUFF-TEMPLATER
S
sqlfluff-templater-dbt
testingpythonv4.1.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

To use sqlfluff-templater-dbt, you must first install the package along with `sqlfluff`, `dbt-core`, and your specific `dbt` adapter. You then configure SQLFluff in a `.sqlfluff` file at your dbt project root, explicitly setting `templater = dbt` and specifying your SQL `dialect`. [1, 4, 12] It's also recommended to configure `project_dir` and `profiles_dir` within the `[sqlfluff:templater:dbt]` section and enable dbt built-ins in the `[sqlfluff:templater:jinja]` section. [1, 4, 9] An `.sqlfluffignore` file is crucial to prevent linting dbt compilation artifacts. [1, 12] Once configured, you can run `sqlfluff lint` or `sqlfluff fix` from your project's root.

# 1. Create a dbt project, e.g., using `dbt init my_dbt_project` # 2. Navigate into your dbt project directory # 3. Create a .sqlfluff configuration file: # .sqlfluff # --- # [sqlfluff] # dialect = snowflake # Or your dbt adapter's dialect # templater = dbt # # [sqlfluff:templater:dbt] # project_dir = ./ # profiles_dir = ~/.dbt/ # Or path to your dbt profiles.yml # # [sqlfluff:templater:jinja] # apply_dbt_builtins = True # Enable dbt macros like `ref`, `var`, `is_incremental()` # --- # 4. Create an optional .sqlfluffignore file to exclude dbt artifacts: # .sqlfluffignore # --- # target/ # dbt_packages/ # macros/ # venv/ # .venv/ # node_modules/ # logs/ # --- # 5. Run SQLFluff to lint your dbt project # (Make sure your dbt profile is configured for compilation if models query database at compile time) import subprocess import os # Example dbt model file with open('models/my_model.sql', 'w') as f: f.write("-- my_model.sql\n\nSELECT {{ ref('another_model') }} FROM {{ source('my_schema', 'my_table') }}\n") # Lint all SQL files in the project print("\n--- Running sqlfluff lint ---") result_lint = subprocess.run(['sqlfluff', 'lint', '.'], capture_output=True, text=True) print(result_lint.stdout) if result_lint.stderr: print("Error:", result_lint.stderr) # Fix linting issues (if any are auto-fixable) print("\n--- Running sqlfluff fix ---") result_fix = subprocess.run(['sqlfluff', 'fix', '.'], capture_output=True, text=True) print(result_fix.stdout) if result_fix.stderr: print("Error:", result_fix.stderr)
Debug
Known issues
gotchaThe `dbt` templater is not the default for SQLFluff; the default is `jinja`. You must explicitly set `templater = dbt` in your `.sqlfluff` configuration file. This setting cannot be overridden in subdirectory configuration files. [1]
fix
Add `templater = dbt` under the `[sqlfluff]` section in your project's root `.sqlfluff` configuration file.
affects: All versions
breakingVersion compatibility with `dbt-core` can be a breaking change. SQLFluff 4.x explicitly drops support for `dbt` versions 1.4 and older, and supports up to `dbt` 1.10. Newer `dbt-core` releases (e.g., 1.8) have historically introduced incompatibilities that required `sqlfluff` updates. [8, 17, 19] Additionally, `dbt` Fusion engine is not natively compatible with the `sqlfluff-templater-dbt`, which relies on `dbt-core`'s templater. [14, 15]
fix
Always check the SQLFluff release notes and documentation for the supported `dbt-core` versions when upgrading either library. For `dbt` Fusion, using the standalone `dbt-core` engine templater locally is a current workaround. [14]
affects: 4.x and above
gotchaUsing the `dbt` templater is generally more complex and slower than the default `jinja` templater because it needs to compile the full dbt project. If your dbt models access a database at compile time, the templater will also require database access. [1, 21]
fix
Consider the trade-off between speed and accuracy. For CI/CD contexts where compilation accuracy is critical, the `dbt` templater is preferred. For local IDE or git hook usage where speed is paramount, the `jinja` templater might be more suitable, potentially with mock macros. [1]
affects: All versions
gotchaSQLFluff 4.1.0 introduced a `max_parse_depth` configuration setting (default 255) to protect against resource exhaustion from deeply nested SQL. Extremely complex or deeply nested dbt models might hit this limit, leading to parsing errors. [5, 11]
fix
If encountering parsing issues with deep queries, consider increasing `max_parse_depth` in your `.sqlfluff` configuration file under the `[sqlfluff]` section: `max_parse_depth = 500` (or a suitable higher value).
affects: 4.1.0 and above
breakingSQLFluff 3.x dropped support for Python 3.7. The latest versions of `sqlfluff` and `sqlfluff-templater-dbt` require Python 3.9 or newer. [8, 6]
fix
Ensure your environment uses Python 3.9 or a later version. Upgrade your Python installation if necessary.
affects: 3.0.0 and above
gotchaBy default, errors encountered during dbt compilation are ignored by the templater (`dbt_skip_compilation_error = True`). This can mask underlying issues in your dbt project that prevent full template rendering. [1]
fix
To surface these errors and ensure complete template rendering, set `dbt_skip_compilation_error = False` in the `[sqlfluff:templater:dbt]` section of your `.sqlfluff` configuration file.
affects: All versions
Errors
Common errors & fixes
Configured templater 'dbt' was not found
SQLFluff is configured to use the 'dbt' templater, but the `sqlfluff-templater-dbt` plugin is either not installed or not accessible in the Python environment where SQLFluff is run.
fix
Ensure the plugin is installed with `pip install sqlfluff-templater-dbt` and verify that `templater = dbt` is correctly set in your SQLFluff configuration file (e.g., `.sqlfluff` or `pyproject.toml`) under the `[sqlfluff]` section.
dbt_project_dir parameter is required for the dbt templater
The `sqlfluff-templater-dbt` plugin requires the path to your dbt project directory to be explicitly defined in the SQLFluff configuration.
fix
Add `dbt_project_dir = <your/dbt/project/path>` to the `[sqlfluff:templater:dbt]` section of your `.sqlfluff` configuration file, or specify it via the command line: `sqlfluff lint --templater dbt --dbt-project-dir <your/dbt/project/path>`.
Could not find profile 'your_profile_name' in profiles.yml
The dbt templater could not locate the specified dbt profile, or the `profiles.yml` file itself, which is essential for dbt to compile SQL.
fix
Ensure your `dbt_profiles_dir` is correctly set in your SQLFluff configuration (`[sqlfluff:templater:dbt]`) to point to the directory containing `profiles.yml`, and that the `profiles.yml` file contains the required profile for your dbt project.
LINTING FAILED: A templating error occurred: Compilation Error in model
The `sqlfluff-templater-dbt` plugin encountered an underlying dbt compilation error while trying to template your SQL model, which prevents SQLFluff from linting the fully compiled code.
fix
Debug the dbt compilation error directly by running `dbt compile <model_name>` on the affected model; ensure all macros are defined, variables are passed, and Jinja syntax is valid within your dbt project.
Upgrade
Version history
4.1.0latest on PyPI · released Mar 26, 2026
Audit
Dependencies
sqlfluffrequiredCore SQL linter functionality, this package is a plugin for it.
dbt-corerequiredRequired for dbt project templating and compilation.
dbt-adaptersoptionalA dbt adapter (e.g., dbt-postgres, dbt-snowflake) is implicitly required for dbt to function, and thus for the templater to work with a specific database.
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources
sqlfluff-templater-dbt — pip install sqlfluff-templater-dbt · libregistry