{"id":2783,"library":"sqlfluff-templater-dbt","title":"SQLFluff dbt Templater","description":"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]","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/sqlfluff/sqlfluff","tags":["dbt","sql","linting","templating","data-quality"],"install":[{"cmd":"pip install sqlfluff sqlfluff-templater-dbt dbt-core dbt-snowflake # Replace dbt-snowflake with your adapter","lang":"bash","label":"Install with dbt-core and an adapter"}],"dependencies":[{"reason":"Core SQL linter functionality, this package is a plugin for it.","package":"sqlfluff"},{"reason":"Required for dbt project templating and compilation.","package":"dbt-core"},{"reason":"A 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.","package":"dbt-adapters","optional":true}],"imports":[],"quickstart":{"code":"# 1. Create a dbt project, e.g., using `dbt init my_dbt_project`\n# 2. Navigate into your dbt project directory\n# 3. Create a .sqlfluff configuration file:\n# .sqlfluff\n# ---\n# [sqlfluff]\n# dialect = snowflake # Or your dbt adapter's dialect\n# templater = dbt\n#\n# [sqlfluff:templater:dbt]\n# project_dir = ./\n# profiles_dir = ~/.dbt/ # Or path to your dbt profiles.yml\n#\n# [sqlfluff:templater:jinja]\n# apply_dbt_builtins = True # Enable dbt macros like `ref`, `var`, `is_incremental()`\n# ---\n\n# 4. Create an optional .sqlfluffignore file to exclude dbt artifacts:\n# .sqlfluffignore\n# ---\n# target/\n# dbt_packages/\n# macros/\n# venv/\n# .venv/\n# node_modules/\n# logs/\n# ---\n\n# 5. Run SQLFluff to lint your dbt project\n# (Make sure your dbt profile is configured for compilation if models query database at compile time)\nimport subprocess\nimport os\n\n# Example dbt model file\nwith open('models/my_model.sql', 'w') as f:\n    f.write(\"-- my_model.sql\\n\\nSELECT {{ ref('another_model') }} FROM {{ source('my_schema', 'my_table') }}\\n\")\n\n# Lint all SQL files in the project\nprint(\"\\n--- Running sqlfluff lint ---\")\nresult_lint = subprocess.run(['sqlfluff', 'lint', '.'], capture_output=True, text=True)\nprint(result_lint.stdout)\nif result_lint.stderr: print(\"Error:\", result_lint.stderr)\n\n# Fix linting issues (if any are auto-fixable)\nprint(\"\\n--- Running sqlfluff fix ---\")\nresult_fix = subprocess.run(['sqlfluff', 'fix', '.'], capture_output=True, text=True)\nprint(result_fix.stdout)\nif result_fix.stderr: print(\"Error:\", result_fix.stderr)","lang":"python","description":"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."},"warnings":[{"fix":"Add `templater = dbt` under the `[sqlfluff]` section in your project's root `.sqlfluff` configuration file.","message":"The `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]","severity":"gotcha","affected_versions":"All versions"},{"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]","message":"Version 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]","severity":"breaking","affected_versions":"4.x and above"},{"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]","message":"Using 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]","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"SQLFluff 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]","severity":"gotcha","affected_versions":"4.1.0 and above"},{"fix":"Ensure your environment uses Python 3.9 or a later version. Upgrade your Python installation if necessary.","message":"SQLFluff 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]","severity":"breaking","affected_versions":"3.0.0 and above"},{"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.","message":"By 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]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}