sqlfluff-complexity 0.3.0

SQLFluff plugin for SQL and dbt model complexity rules

sqlfluff-complexity

SQLFluff rules and reports for finding SQL and dbt models that are too complex to review safely.

sqlfluff-complexity adds CPX rules to SQLFluff for CTE count, join count, nested subquery depth, CASE expressions, boolean predicates, window functions, CTE dependency depth, and an aggregate weighted complexity score. The same metric engine also powers a companion sqlfluff-complexity report command for non-blocking console, JSON, and SARIF reports.

Who It Is For

• Analytics engineers who want dbt models to stay small enough to review.
• Data platform teams that already run SQLFluff in local development or CI.
• Teams that want gradual complexity reporting before turning on strict lint failures.

Quick Start

Install the custom SQLFluff plugin in the same Python environment where you run SQLFluff:

pip install sqlfluff-complexity

If your project uses uv:

uv add --dev sqlfluff-complexity

Then enable CPX rules in .sqlfluff and run SQLFluff:

[sqlfluff]
dialect = postgres
rules = CPX_C101,CPX_C102,CPX_C103,CPX_C104,CPX_C105,CPX_C106,CPX_C107,CPX_C201

sqlfluff lint models/

For a complete walkthrough, see docs/quickstart.md.

Documentation

• Quick start: install, configure, and run the first lint.
• Configuration: thresholds, aggregate weights, and path overrides.
• Rules reference: CPX rule codes and what each metric counts.
• Reporting: console and SARIF report mode.
• dbt usage: SQLFluff dbt templater compatibility and v1 boundaries.
• Dialects: tested dialects and dbt adapter mapping caveats.
• Docs index: all user, contributor, and design documents.
• Internal import migration: if you import sqlfluff_complexity.core submodules directly, update paths after subpackage refactors.

Large dbt projects

This plugin does not read dbt artifacts (manifest.json, run_results.json, catalog.json) or graph metadata. Complexity is measured from the SQLFluff parse tree only—which aligns well with SQLFluff’s dbt templater so ref(), source(), and macros compile before linting.

Practical adoption patterns:

• Use the dbt templater when you need compiled SQL fidelity; keep sqlfluff-complexity focused on structural signals from parsed SQL.
• Tune thresholds per rule and use path_overrides on CPX_C201 where staging vs marts need different budgets.
• Prefer sqlfluff lint on changed models in CI and sqlfluff-complexity report for broader visibility without failing builds.
• For CTE dependency depth, see docs/rules.md (CPX_C107) and docs/reporting.md (report vs per-WITH lint).

See also dbt usage and configuration.

Project Status

• Native SQLFluff plugin rules and the companion report CLI are available in the package.
• v1 measures SQLFluff-parsed SQL; direct dbt manifest.json and DAG-level metrics are deferred.
• Architecture decisions are recorded in docs/adr/.

Development

Contributor setup, Nox sessions, fixture authoring, ADR workflow, and verifier guidance live in CONTRIBUTING.md. Agent-specific project instructions live in AGENTS.md.