{"id":9335,"library":"sqruff","title":"Sqruff SQL Linter","description":"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.","status":"active","version":"0.38.0","language":"en","source_language":"en","source_url":"https://github.com/quarylabs/sqruff","tags":["sql","linter","formatter","rust","cli"],"install":[{"cmd":"pip install sqruff","lang":"bash","label":"Install Sqruff"}],"dependencies":[{"reason":"Required for Python bindings and distribution via PyPI.","package":"python","optional":false},{"reason":"The core linter is written in Rust, used for compilation of the Python package.","package":"rust","optional":false}],"imports":[{"note":"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.","symbol":"sqruff (CLI tool)","correct":"Run 'sqruff <command>' from the terminal"}],"quickstart":{"code":"# Create a SQL file to lint\necho \"SELECT  col1, col2 FROM my_table;\" > bad_sql.sql\n\n# Create a configuration file (e.g., .sqruff)\necho \"[sqruff]\\ndialect = postgres\" > .sqruff\n\n# Run the linter\nsqruff lint bad_sql.sql\n\n# Or lint all SQL files in the current directory with the config\nsqruff lint .\n\n# Run the formatter\nsqruff format bad_sql.sql\n","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.38.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"Potentially any major/minor version updates (e.g., 0.x.x to 0.y.x where y > x)"},{"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 .`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `sqruff` executable is not in your system's PATH, or the pip installation failed/is not activated in your current environment.","error":"sqruff: command not found"},{"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.","cause":"Sqruff could not parse the provided SQL, likely due to syntax errors in the SQL file or an incorrect/unspecified SQL dialect.","error":"Error: Failed to parse SQL. This can occur if the SQL is invalid or the wrong dialect is selected."},{"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.","cause":"You are trying to enable or disable a linting rule that does not exist in the current version of Sqruff or is misspelled.","error":"error: no such rule: <RULE_CODE>"}]}