{"id":5883,"library":"collate-sqlfluff","title":"Collate SQLFluff","description":"collate-sqlfluff is a fork of SQLFluff (the SQL Linter for Humans), maintained by the OpenMetadata community. It provides a modular, dialect-flexible, and configurable SQL linter and auto-formatter, designed particularly for ELT applications. It supports multiple SQL dialects (e.g., BigQuery, Snowflake, PostgreSQL) and templating languages like Jinja and dbt. The library frequently syncs with upstream SQLFluff, incorporating its features and adhering to its semantic versioning, while adding specific enhancements relevant to OpenMetadata's ecosystem.","status":"active","version":"3.5.2","language":"python","source_language":"en","source_url":"https://github.com/open-metadata/collate-sqlfluff","tags":["SQL","linter","formatter","code quality","OpenMetadata","dbt","Jinja","ELT"],"install":[{"cmd":"pip install collate-sqlfluff","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"collate-sqlfluff is a fork of sqlfluff and builds upon its core functionality. Upstream changes, breaking or otherwise, generally apply to this package.","package":"sqlfluff","optional":false}],"imports":[{"note":"Despite the package name being `collate-sqlfluff`, the main import path for its functionality is `sqlfluff`.","wrong":"import collate_sqlfluff","symbol":"sqlfluff","correct":"import sqlfluff"},{"note":"For advanced programmatic usage, Linter and FluffConfig classes can be imported from sqlfluff.core.","symbol":"Linter","correct":"from sqlfluff.core import Linter, FluffConfig"}],"quickstart":{"code":"import sqlfluff\n\nmy_bad_query = \"SeLEct *, 1, blah as fOO from mySchema.myTable\"\n\n# Lint the given string and return violations\nlint_result = sqlfluff.lint(my_bad_query, dialect=\"bigquery\")\nprint(\"Linting Results:\", lint_result)\n\n# Fix the given string and get a fixed string back\nfix_result = sqlfluff.fix(my_bad_query, dialect=\"bigquery\")\nprint(\"Fixed Query:\\n\", fix_result)","lang":"python","description":"This example demonstrates how to use the programmatic API to lint and fix a SQL string using the `sqlfluff` module. The `dialect` parameter is often crucial for accurate linting and fixing."},"warnings":[{"fix":"Review the upstream `sqlfluff` release notes and migration guides (e.g., for 3.x and 4.x) to adapt code and configurations.","message":"collate-sqlfluff closely follows upstream sqlfluff releases. Major version updates in sqlfluff (e.g., 2.x to 3.x, 3.x to 4.x) introduce breaking changes to the Python API, rule coding, configuration, and CLI behavior. For instance, `sqlfluff fix` defaults behavior changed in 3.x, and 4.x introduced optional Rust routines. Users should consult the upstream sqlfluff release notes for migration guides.","severity":"breaking","affected_versions":">=3.0.0 (mirroring upstream sqlfluff changes)"},{"fix":"Always use `import sqlfluff` when importing the library in Python code.","message":"Although the package name is `collate-sqlfluff`, the primary Python import statement to access its functionality is `import sqlfluff`. Attempting to `import collate_sqlfluff` will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that `templater` configuration is defined in a higher-level configuration file (e.g., in the project root or user home directory) and not in subdirectories where it will be ignored.","message":"collate-sqlfluff uses a hierarchical configuration system where local configuration files override global ones. However, the `templater` configuration option *cannot* be set in config files located in subdirectories of the working directory; it must be set at a higher level.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Exercise caution when granting edit access to SQL or configuration files containing templated code. Review templated SQL for malicious constructs, especially when sourcing from untrusted users or environments.","message":"When using Jinja or dbt templating with `collate-sqlfluff`, macros within the SQL can potentially execute arbitrary code. While `sqlfluff` employs Jinja2's `SandboxedEnvironment` for some protection, users with edit access to SQL or configuration files should be aware of potential security implications, as some macros (e.g., dbt `run_query`) might execute arbitrary SQL.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'ad':74 'adher':68 'applic':40 'auto':34 'auto-formatt':33 'bigqueri':47 'code':85 'collat':1,4 'collate-sqlfluff':3 'communiti':20 'configur':29 'dbt':56,88 'design':36 'dialect':26,45 'dialect-flex':25 'e.g':46 'ecosystem':81 'elt':39,90 'enhanc':76 'featur':66 'flexibl':27 'fork':8 'formatt':35,84 'frequent':59 'human':15 'incorpor':64 'jinja':54,89 'languag':52 'librari':58 'like':53 'linter':13,31,83 'maintain':16 'modular':24 'multipl':43 'openmetadata':19,79,87 'particular':37 'postgresql':49 'provid':22 'qualiti':86 'relev':77 'semant':71 'snowflak':48 'specif':75 'sql':12,30,44,82 'sqlfluff':2,5,10,63 'support':42 'sync':60 'templat':51 'upstream':62 'version':72","created_at":"2026-04-14T18:32:35.389530+00:00","updated_at":"2026-04-16T03:05:17.227560+00:00","problems":[{"fix":"Always use `import sqlfluff` (or `from sqlfluff import ...`) in your Python code, even if the installed package is `collate-sqlfluff`.","cause":"Although the package is installed as `collate-sqlfluff`, its Python modules are exposed under the `sqlfluff` namespace, so direct import of `collate_sqlfluff` will fail.","error":"ModuleNotFoundError: No module named 'collate_sqlfluff'"},{"fix":"Specify the dialect using a `.sqlfluff` configuration file (e.g., `[sqlfluff] dialect = snowflake`) in your project root, or via the command line (e.g., `sqlfluff lint --dialect snowflake my_file.sql`).","cause":"collate-sqlfluff requires a SQL dialect to be specified for linting and parsing, either in a configuration file or directly via the command line, to correctly interpret SQL syntax.","error":"User Error: No dialect was specified. You must configure a dialect or specify one on the command line using --dialect after the command."},{"fix":"For dbt projects, configure SQLFluff to use the `dbt` templater (e.g., in `.sqlfluff` add `templater = dbt` under `[sqlfluff]`) and ensure your dbt project is compilable. For generic Jinja, provide dummy variables in the `[sqlfluff:templater:jinja:context]` section of your `.sqlfluff` file or specify `load_macros_from_path` if using external macro files. Alternatively, you can use `--ignore=templating` to skip templating errors, though this may lead to less accurate linting.","cause":"This error occurs when SQLFluff's Jinja templater cannot find the definition for a variable or macro used in your SQL, typically because the templater is not correctly configured to resolve dbt macros or other Jinja contexts.","error":"Undefined jinja template variable: '...' or Unrecoverable failure in Jinja templating: '...' is undefined."},{"fix":"Move the `templater` setting to a `.sqlfluff` file in a higher-level directory (e.g., the root of your project or your user's home directory) to ensure it is correctly picked up by SQLFluff.","cause":"The `templater` configuration option in SQLFluff has a hierarchical restriction; it cannot be defined in a `.sqlfluff` file located within a subdirectory of the working directory. It must be set at a higher level, such as the project root or user home directory.","error":"Templater cannot be set in a .sqlfluff file in a subdirectory of the current working directory."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.5.3","cli_name":"sqlfluff","cli_version":"sqlfluff, version 3.5.2","type":"library","homepage":"https://www.sqlfluff.com","github":"https://github.com/open-metadata/collate-sqlfluff","docs":"https://docs.sqlfluff.com","changelog":"https://github.com/open-metadata/collate-sqlfluff/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/collate-sqlfluff/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","testing","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}