Diff Quality Plugin

Relevant source files

The following files were used as context for generating this wiki page:

• src/sqlfluff/diff_quality_plugin.py
• docsv/usage/diff-quality.md
• pyproject.toml
• docsv/usage/team-rollout.md
• docsv/development/plugins.md
• CONTRIBUTING.md

The Diff Quality Plugin integrates SQLFluff with the diff-quality tool, which is part of the diff_cover package. This plugin limits SQLFluff linting output to only new or modified lines of SQL within a Git branch or pull request. It prevents large legacy codebases from overwhelming developers with unrelated quality issues during minor changes.

Installing SQLFluff automatically installs the diff_cover package required for this plugin. The plugin operates by identifying violations in changed files and reporting them back to the diff-quality reporting engine.

Sources: docsv/usage/diff-quality.md:1-12, pyproject.toml:73

Architecture and Tool Integration

The plugin serves as a bridge between the diff-quality command-line tool and the SQLFluff linter. It implements the interface required by diff-cover to collect and format linting violations.

Operational Flow

The following diagram illustrates how diff-quality interacts with SQLFluff through the plugin:

diff-quality identifies changed lines via Git metadata and requests violation data from the plugin. Sources: docsv/usage/diff-quality.md:14-25

Plugin Registration

SQLFluff registers the plugin using the diff_cover entry point in the project configuration. This allows the diff-quality tool to discover SQLFluff as a valid quality checker.

[project.entry-points.diff_cover]
sqlfluff = "sqlfluff.diff_quality_plugin"

Sources: pyproject.toml:109-110

Implementation Details

The plugin implementation resides in src/sqlfluff/diff_quality_plugin.py. It defines how SQLFluff output is mapped to the format expected by the diff-quality report.

Key Components

Component	Description
diff_cover Entry Point	The hook that allows diff-quality --violations sqlfluff to execute.
Violation Mapping	The process of converting SQLFluff LintResult objects into line-based violation reports.
Git Root Requirement	diff-quality must run from the root of a Git repository to access metadata.

Sources: src/sqlfluff/diff_quality_plugin.py, docsv/usage/diff-quality.md:38-40

Configuration Alignment

For the plugin to function correctly with complex setups (like dbt), three paths must align at the Git root:

1. The execution path of diff-quality.
2. The location of the .sqlfluff configuration file.
3. The root of the project (or the dbt_project.yml file).

Sources: docsv/usage/diff-quality.md:46-56

Integration with CI/CD

The plugin is primarily used in "Soft CI/CD" or "Hard CI/CD" phases to enforce quality on pull requests. By only linting changes, teams can prevent the introduction of new technical debt without needing to fix the entire legacy codebase at once.

Usage in CI Scripts

To run the plugin in a CI environment, you execute the following command after navigating to the Git repository root:

$ diff-quality --violations sqlfluff

Sources: docsv/usage/diff-quality.md:21-23, docsv/usage/team-rollout.md:52-58

Reporting Constraints

While SQLFluff provides exact character positions for violations, the diff-quality report format only supports line numbers. If precise character positions are required, you must run the SQLFluff CLI directly.

Sources: docsv/usage/diff-quality.md:34-36

Development and Testing

The plugin is part of the core SQLFluff repository and follows the standard contribution and testing guidelines.

Plugin Discovery

SQLFluff uses the pluggy library for discovery. For the diff-quality plugin to be recognized, the package must be installed in the environment (e.g., via pip install -e . during development).

Sources: docsv/development/plugins.md:1-5, CONTRIBUTING.md:218-220

Requirements for Contributors

• Python 3.10 minimum is required for development and execution.
• Any architectural changes to the linter that affect the plugin must pass the full test suite, including tox environments.

Sources: CONTRIBUTING.md:164-165, CONTRIBUTING.md:131-135

Summary

The Diff Quality Plugin enables targeted SQL linting by focusing solely on modified code within Git-versioned projects. It integrates SQLFluff into the diff_cover ecosystem, providing a practical pathway for teams to improve code quality incrementally during the pull request process.