{"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":"python","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,"search_vec":"'13':69 '2':67 '2026':66 '4.1.0':59 '5':68 'build':30 'capabl':36 'compil':24 'conjunct':51 'correct':21 'data':29,75 'data-qu':74 'dbt':2,7,28,39,43,70 'design':19 'engin':46 'extend':33 'human':17 'latest':62 'leverag':42 'librari':56 'lint':38,72 'linter':15 'main':54 'march':65 'model':40 'pars':22 'plugin':10 'project':26,48 'qualiti':76 'releas':49 'specif':18 'sql':14,25,71 'sqlfluff':1,5,12,34,55 'sqlfluff-templater-dbt':4 'templat':3,6,45,73 'tool':31 'use':27 'version':58","created_at":"2026-04-11T01:42:36.913392+00:00","updated_at":"2026-04-16T22:14:43.698491+00:00","problems":[{"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.","cause":"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.","error":"Configured templater 'dbt' was not found"},{"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>`.","cause":"The `sqlfluff-templater-dbt` plugin requires the path to your dbt project directory to be explicitly defined in the SQLFluff configuration.","error":"dbt_project_dir parameter is required for the dbt templater"},{"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.","cause":"The dbt templater could not locate the specified dbt profile, or the `profiles.yml` file itself, which is essential for dbt to compile SQL.","error":"Could not find profile 'your_profile_name' in profiles.yml"},{"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.","cause":"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.","error":"LINTING FAILED: A templating error occurred: Compilation Error in model"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://www.sqlfluff.com","github":"https://github.com/sqlfluff/sqlfluff","docs":"https://docs.sqlfluff.com","changelog":"https://github.com/sqlfluff/sqlfluff/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/sqlfluff-templater-dbt/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-10","next_check":"2026-07-09","install_tag":null}}