Sqruff SQL Linter

0.38.0 · active · verified Thu Apr 16

Sqruff is a high-performance SQL linter and formatter written in Rust, designed for speed and portability. It supports various SQL dialects, including ANSI, BigQuery, and Postgres, with ongoing development for others like Snowflake and Clickhouse. Currently at version 0.38.0, it maintains an active release cadence with frequent updates and is often noted for its significant speed improvement over similar tools.

Common errors

```
sqruff: command not found
```
cause The `sqruff` executable is not in your system's PATH, or the pip installation failed/is not activated in your current environment.

fix Ensure `pip install sqruff` completed successfully. If using a virtual environment, activate it. Check your PATH environment variable. On some systems, pip installs executables into `~/.local/bin/` which might not be in PATH by default.
```
Error: Failed to parse SQL. This can occur if the SQL is invalid or the wrong dialect is selected.
```
cause Sqruff could not parse the provided SQL, likely due to syntax errors in the SQL file or an incorrect/unspecified SQL dialect.

fix First, verify your SQL syntax. If the SQL is valid, ensure you have correctly specified the SQL dialect in your `.sqruff` configuration file (e.g., `dialect = bigquery`) or using the `--dialect` CLI flag. Sqruff supports dialects like `ansi`, `bigquery`, `postgres` among others.
```
error: no such rule: <RULE_CODE>
```
cause You are trying to enable or disable a linting rule that does not exist in the current version of Sqruff or is misspelled.

fix Consult the official Sqruff documentation or run `sqruff rules` (if available in a future version) to get a list of supported rules. Correct the rule code in your `.sqruff` configuration or CLI arguments.

Warnings

gotcha Sqruff is primarily a CLI tool; there is no exposed Python API for direct programmatic linting/formatting (e.g., `sqruff.lint('SELECT 1')`) as of version 0.38.0. Users expecting a Python library for in-application use should reconsider or plan to wrap CLI calls.
Fix: Interact with Sqruff via its command-line interface (e.g., `subprocess.run(['sqruff', 'lint', 'file.sql'])`) or by invoking it as a separate process.
breaking The underlying Rust library, which Sqruff builds upon, has experienced frequent breaking changes across its development cycle (e.g., 28 breaking releases out of 99). While the Python packaging attempts to stabilize the interface, users should review release notes for significant updates that might affect behavior or require configuration adjustments.
Fix: Always check the official GitHub releases and documentation for breaking changes before upgrading, especially for significant version bumps. Test new versions in a controlled environment.
gotcha Incorrect or missing dialect configuration can lead to unexpected linting/formatting results or errors. Sqruff needs to know the SQL dialect (e.g., PostgreSQL, BigQuery, ANSI) to correctly parse and apply rules.
Fix: Always define the `dialect` in a `.sqruff` configuration file in your project root or pass it via the `--dialect` flag (e.g., `sqruff lint --dialect postgres .`).

Install

pip install sqruff Install Sqruff

Imports

sqruff (CLI tool)
```
Run 'sqruff <command>' from the terminal
```
Sqruff is primarily designed and documented as a command-line interface (CLI) tool. While it uses Python bindings (via PyO3) for its PyPI distribution, there is no commonly documented direct Python API for programmatic linting or formatting similar to 'import sqruff' functions found in other Python SQL linters. Users are expected to interact with it via its 'sqruff' executable.

Quickstart

This quickstart demonstrates how to install Sqruff and use its primary command-line interface to lint and format a SQL file. It involves creating a sample SQL file and a `.sqruff` configuration file to specify the SQL dialect.

# Create a SQL file to lint
echo "SELECT  col1, col2 FROM my_table;" > bad_sql.sql

# Create a configuration file (e.g., .sqruff)
echo "[sqruff]\ndialect = postgres" > .sqruff

# Run the linter
sqruff lint bad_sql.sql

# Or lint all SQL files in the current directory with the config
sqruff lint .

# Run the formatter
sqruff format bad_sql.sql

view raw JSON →