Registry / data / collate-sqlfluff

collate-sqlfluff

library3.5.3pypypi✓ verified 86d ago

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.

data testing devops

pip install collate-sqlfluff

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · COLLATE-SQLFLUFF

collate-sqlfluff

datapythonv3.5.3

Install

4.8s avg

Import

983ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.5.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.025s · 48.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.8s · import 0.941s · 51MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sqlfluff

✓ import sqlfluff

✗ import collate_sqlfluff

Despite the package name being `collate-sqlfluff`, the main import path for its functionality is `sqlfluff`.

Linter

✓ from sqlfluff.core import Linter, FluffConfig

For advanced programmatic usage, Linter and FluffConfig classes can be imported from sqlfluff.core.

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.

import sqlfluff my_bad_query = "SeLEct *, 1, blah as fOO from mySchema.myTable" # Lint the given string and return violations lint_result = sqlfluff.lint(my_bad_query, dialect="bigquery") print("Linting Results:", lint_result) # Fix the given string and get a fixed string back fix_result = sqlfluff.fix(my_bad_query, dialect="bigquery") print("Fixed Query:\n", fix_result)

sqlfluff --version

Debug

Known issues

breakingcollate-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.

fix

Review the upstream `sqlfluff` release notes and migration guides (e.g., for 3.x and 4.x) to adapt code and configurations.

affects: >=3.0.0 (mirroring upstream sqlfluff changes)

gotchaAlthough 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`.

fix

Always use `import sqlfluff` when importing the library in Python code.

affects: All versions

gotchacollate-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.

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.

affects: All versions

gotchaWhen 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.

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'collate_sqlfluff'

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.

fix

Always use `import sqlfluff` (or `from sqlfluff import ...`) in your Python code, even if the installed package is `collate-sqlfluff`.

User Error: No dialect was specified. You must configure a dialect or specify one on the command line using --dialect after the command.

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.

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`).

Undefined jinja template variable: '...' or Unrecoverable failure in Jinja templating: '...' is undefined.

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.

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.

Templater cannot be set in a .sqlfluff file in a subdirectory of the current working directory.

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.

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.

Upgrade

Version history

3.5.3latest on PyPI · released May 28, 2026

Audit

Dependencies

sqlfluffrequiredcollate-sqlfluff is a fork of sqlfluff and builds upon its core functionality. Upstream changes, breaking or otherwise, generally apply to this package.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/open-metadata/collate-sqlfluff ↗

packagehttps://pypi.org/project/collate-sqlfluff/ ↗

homepagehttps://www.sqlfluff.com ↗

docshttps://docs.sqlfluff.com ↗

changeloghttps://github.com/open-metadata/collate-sqlfluff/blob/main/CHANGELOG.md ↗