SQLFluff hooks

Using pre-commit with SQLFluff is a good way to provide automated linting to SQL developers. With pre-commit, you also get the benefit of only linting/fixing the files that changed.

SQLFluff comes with two pre-commit hooks:

• sqlfluff-lint: returns linting errors.

• sqlfluff-fix: attempts to fix rule violations.

Using pre-commit — SQLFluff stable_version documentation

sqlfluff-lint

What it does Checks SQL files against SQLFluff rules to enforce consistent formatting and catch potential SQL anti-patterns.

When to use it Use this hook when you want to enforce consistent SQL style across your project. It's particularly useful for teams working on shared SQL codebases where maintaining consistent style is important.

Arguments

• --dialect: SQL dialect to use (e.g., postgres, mysql, snowflake)

• --exclude-rules: Comma-separated list of rule codes to exclude

• --rules: Comma-separated list of rule codes to check (defaults to all)

• --processes: Number of parallel processes to use

• --ignore: Comma-separated list of paths to ignore

Example

repos:
  - repo: https://github.com/sqlfluff/sqlfluff
    rev: 2.3.5
    hooks:
      - id: sqlfluff-lint
        args: [--dialect, snowflake, --exclude-rules, L014,L016]

Requirements

• SQLFluff installed (pip install sqlfluff)

• .sqlfluff config file (optional but recommended)

How it works

1. Hook identifies all changed SQL files in your commit

2. Each file is checked against enabled SQLFluff rules

3. Fails if any rule violations are found

4. Provides detailed output of rule violations and suggested fixes

sqlfluff-fix

What it does Automatically fixes SQL files to conform to SQLFluff rules and formatting standards.

When to use it Use this hook when you want to automatically format SQL files according to your team's standards. It saves time by fixing common formatting issues before they're committed.

Arguments

• --dialect: SQL dialect to use (e.g., postgres, mysql, snowflake)

• --exclude-rules: Comma-separated list of rule codes to exclude from fixing

• --rules: Comma-separated list of rule codes to fix (defaults to all fixable rules)

• --processes: Number of parallel processes to use

• --ignore: Comma-separated list of paths to ignore

Example

repos:
  - repo: https://github.com/sqlfluff/sqlfluff
    rev: 2.3.5
    hooks:
      - id: sqlfluff-fix
        args: [--dialect, snowflake, --exclude-rules, L014]

Using SQLFluff with dbt

What it does Enables SQLFluff to understand and lint dbt-specific SQL syntax, including dbt macros, ref/source functions, and Jinja templating.

When to use it Use this configuration when you're using SQLFluff in a dbt project. It allows SQLFluff to properly parse and lint SQL files that contain dbt-specific syntax and templating.

Configuration

Add the dbt templater as an additional dependency in your pre-commit config

Example

repos:
  - repo: https://github.com/sqlfluff/sqlfluff
    rev: 2.3.5
    hooks:
      - id: sqlfluff-fix
        args: [--dialect, snowflake, --exclude-rules, L014]
        additional_dependencies: ["sqlfluff-templater-dbt"]

Then, configure the dbt templater in your .sqlfluff

Using rules in your .sqlfluff file

To point pre-commit to use your custom .sqlfluff rules file, you need to either:

1. Put the .sqlfluff file in your repository root (default behavior), or

2. Specify a custom path in your pre-commit configuration

Example

repos:
  - repo: https://github.com/sqlfluff/sqlfluff
    rev: 2.3.5
    hooks:
      - id: sqlfluff-lint
        args: [
          --dialect, postgres,
          --config, path/to/your/.sqlfluff  # Point to your custom config
        ]

The --config argument tells SQLFluff where to find your rules configuration. The path should be relative to your repository root.

See also:

SQLFluff

Best Practices

1. Create a .sqlfluff config file for project-specific rules. See also SQLFluff configurations

2. Run fix before lint to automatically resolve simple issues

3. Use --exclude-rules for exceptions rather than disabling rules globally

4. Set appropriate line length limits for your team

5. Document any rule exclusions in your config file

6. Use consistent SQL dialects across your project