DOCSEARCHbyAlgolia
Submit Docs

sqruff

repository·main·Indexed 23 days ago

https://github.com/quarylabs/sqruff

A fast, Rust-based SQL linter and formatter for advanced, configurable linting and automated formatting across different SQL dialects. It includes a CLI for linting and fixing files, an LSP server for IDE integration, and support for custom templaters to handle non-standard SQL syntax. Configuration can be managed via a .sqruff INI file, allowing for dialect-specific rules and options.

Tokens
31.4K
Snippets
61
Records
209
Agent score
78%

What's inside sqruff

  1. Overview of Sqruff

    main

    Sqruff is a high-performance SQL linter and formatter written in Rust. It is designed to provide fast linting and automated formatting for specific SQL dialects. Unlike some other tools, Sqruff focuses on targeting valid SQL for each dialect rather than attempting to fix partially incorrect SQL.

    Key Capabilities:

    • Linting: Advanced and customizable SQL linting.
    • Formatting: Automated, configurable SQL code formatting.
    • Lineage: Column-level data lineage analysis.
    • Performance: High speed and efficiency with minimal overhead.
    • Portability: Easy integration into CI/CD workflows.

  2. Configure and manage Sqruff rules

    main

    Sqruff rules can be enabled, disabled, or configured via the project's configuration file. The available rules are derived from the rules module in the source code. Each rule is identified by a unique Rule Code and a Rule Name.

    When configuring rules, you can determine if a rule is Fixable (can be automatically corrected by Sqruff) and which Groups the rule belongs to. Some rules may also be skipped depending on the SQL Dialect being used.

  3. Configure and manage Sqruff linting rules

    main

    Sqruff provides a comprehensive set of linting rules categorized by their purpose (e.g., aliasing, ambiguity, capitalisation, convention, layout, etc.). These rules can be enabled, disabled, or configured within your project's configuration file.

    Rules are identified by a unique Rule Code (e.g., AL01, CP01) and a Rule Name (e.g., aliasing.table, capitalisation.keywords).

  4. Install sqruff using a bash script

    main

    You can use a curl command to download and run the official installation script. You can choose to install to the default location (/usr/local/bin) or specify a custom directory.

    # Install to default location (/usr/local/bin)
curl -fsSL https://raw.githubusercontent.com/quarylabs/sqruff/main/install.sh | bash

# Install to custom directory
curl -fsSL https://raw.githubusercontent.com/quarylabs/sqruff/main/install.sh | bash -s ~/.local/bin

  7. Lint SQL files and directories with sqruff lint

    main

    Use the sqruff lint command to analyze SQL files or entire directories for linting issues. You can provide a single file, multiple specific files, or a directory path as arguments.

    sqruff lint <file>
sqruff lint <file1> <file2> <file3>
sqruff lint <directory>

  9. Ignore multiple line errors with -- noqa: disable

    main

    You can disable linting rules for a range of lines using a directive similar to pylint. Add -- noqa: disable=<rule_id>[,...] | all to a line to stop enforcing the specified rules (or all rules if all is used) from that point forward.

    Rules will remain disabled until a corresponding -- noqa: enable=<rule_id>[,...] | all directive is encountered.

    -- Ignore rule AL02 from this line forward
SELECT col_a a FROM foo -- noqa: disable=AL02

-- Ignore all rules from this line forward
SELECT col_a a FROM foo -- noqa: disable=all

-- Enforce all rules from this line forward
SELECT col_a a FROM foo -- noqa: enable=all

  10. Use recommended VS Code defaults for sqruff development

    main
    The repository provides a sample VS Code configuration located in .hacking/vscode. Developers can use these settings to ensure their environment matches the recommended defaults for contributing to the sqruff project.

  12. Configure and use the dbt templater

    main

    The dbt templater provides full dbt functionality by compiling models using dbt-core. This resolves ref(), source(), macros, and handles ephemeral models automatically.

    Requirements:

    1. A valid dbt project with dbt_project.yml.
    2. A profiles.yml file.
    3. A compiled dbt manifest (run dbt compile or dbt run first).
    4. Python packages: sqruff, dbt-core, and your database adapter (e.g., dbt-snowflake).

    Install via:

    pip install sqruff dbt-core

    Setup:

    1. Enable in .sqruff config:
    [sqruff]
templater = dbt
    1. Configure project details in [sqruff:templater:dbt].
    2. Pass dbt variables via [sqruff:templater:dbt:context] (equivalent to --vars).

    Configuration Options ([sqruff:templater:dbt]):

    • project_dir (string): Path to dbt project (default: current working directory).
    • profiles_dir (string): Path to dbt profiles (default: ~/.dbt).
    • profile (string): Profile name.
    • target (string): Target name.

    Note: dbt may connect to your database during compilation. Ensure profiles.yml is correct. If you see connection errors, run dbt debug to verify.

    [sqruff:templater:dbt]
project_dir = ./my_dbt_project
profiles_dir = ~/.dbt
profile = my_profile
target = dev

[sqruff:templater:dbt:context]
my_var = some_value