# sqruff: SQL Linting and Formatting Tool

> sqruff is a Rust-based SQL linter and formatter for teams that want configurable checks, automated formatting and editor support. Its documented CLI covers project-wide linting, configuration selects a SQL dialect, and the LSP supports compatible editors.

**quarylabs/sqruff** — Fast SQL formatter/linter

- Repository: https://github.com/quarylabs/sqruff
- Website: https://playground.quary.dev/docs
- Stars: 1,412 · Forks: 79
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/quarylabs-sqruff

## Why sqruff addresses SQL project quality

sqruff is intended for developers and teams that need to inspect SQL before it reaches production, review repositories containing many query files, or apply a consistent SQL style across an editor and a command-line workflow. The project description identifies two primary jobs: linting SQL for configurable problems and formatting SQL automatically. That combination is useful because a formatter can standardize layout while a linter can report rule violations that are not fixed merely by changing indentation or whitespace.

The project is written primarily in Rust and presents itself as a fast, portable tool. The README specifically points users toward BigQuery, ClickHouse and Snowflake topics, while its quickstart uses PostgreSQL as the dialect example. The repository workspace contains separate crates for the command-line library, core library, dialects, LSP and editor-related components. Based on that layout, sqruff is structured as a reusable library system with a CLI and editor-facing functionality rather than as a single-purpose script.

The intended audience is narrower than a general-purpose text formatter. Users need SQL files and a selected SQL dialect. Teams also need to decide which rules they want enforced and whether formatting changes should be accepted automatically. sqruff leaves those decisions visible through project configuration instead of requiring every check to be selected through a long command line for every run.

## The sqruff CLI and project configuration flow

The documented command path is straightforward. A user supplies a directory to the `lint` command and names a dialect with `--dialect`. The README gives `sqruff lint . --dialect postgres` as the first project-wide linting example. The trailing `.` represents the current project directory in that example, so the command is intended to cover files below the current working directory.

For persistent settings, sqruff reads a `.sqruff` file from the project root. The documented format uses the `[sqruff]` section and a `dialect` key:

```ini
[sqruff]
dialect = postgres
```

After that file exists, the dialect no longer needs to be repeated on the command line, as shown here:

```bash
sqruff lint .
```

This arrangement separates project-wide settings from the operation being performed. The command still decides whether to lint the project, while `.sqruff` records configuration shared by contributors working in the repository. The README does not document a rollback command, an auto-fix command or a complete list of configuration keys, so those behaviors should not be assumed from the quickstart. The linked configuration and rules documentation is the appropriate place to inspect the full surface before setting up a repository-wide policy.

The repository's `Cargo.toml` identifies version `0.41.0` for the workspace package and several internal libraries. It also lists dialects and LSP crates as workspace dependencies. Those names support the broad architecture description, but the README does not explain the parsing stages, rule execution order or file discovery rules in detail.

## Installing sqruff on macOS and running the first lint

The README provides a direct macOS installation path with Homebrew:

```bash
brew install sqruff
```

After installation, the documented first check targets the current directory and selects PostgreSQL:

```bash
sqruff lint . --dialect postgres
```

A reader should see the command available as `sqruff` before attempting this step. The README does not include expected output, exit codes or a sample violation, so the repository does not give enough information to promise a particular result for a user's SQL. The command's outcome will depend on the files present, the selected dialect and the applicable lint rules.

For projects that should not depend on a command-line flag every time, create `.sqruff` in the project root with the documented contents:

```ini
[sqruff]
dialect = postgres
```

Then run the shorter command from the project directory:

```bash
sqruff lint .
```

For platforms other than macOS, the README directs users to the installation guide for pip, Cargo and binary downloads. It does not provide those platform-specific commands in the quickstart, so this article does not reconstruct them. The package metadata also describes a Python distribution named `sqruff` requiring Python `>=3.10`, but the README's only directly documented installation command is the Homebrew command above.

A practical first pass is therefore to install the documented binary, run the explicit dialect command once, inspect the resulting diagnostics in the actual repository, and only then add `.sqruff` if the dialect should become the project default.

## Editor support through the sqruff LSP

sqruff also ships a language server through the `sqruff lsp` command. The README says this server is usable from any editor, although it also states that the repository maintains specific integrations for VS Code and Zed. Those integrations live under `editors/code` and `editors/zed`, making editor setup part of the repository rather than an undocumented external add-on.

The LSP route addresses a common workflow gap between terminal linting and interactive editing. A developer can invoke sqruff from a project command to check a directory, while an editor integration can use the language server to expose SQL language services during editing. The README does not state which diagnostics appear in an editor, how quickly they appear, or whether formatting can be triggered through the LSP. Those details require checking the linked editor and LSP documentation.

There is also a repository-level separation between the Rust workspace and the JavaScript workspace. `package.json` defines scripts for formatting, linting, building, testing and packaging the playground and editor-related packages. It requires Node.js `>=24.0.0` and pnpm `>=10.0.0` for that development workflow. Those requirements are relevant to contributors working in the repository, but they are not presented by the README as requirements for an end user who installs the prebuilt command through Homebrew.

This distinction matters when choosing sqruff. A team that only wants command-line checks can start with `sqruff lint .`, while a team that also wants editor feedback must configure the relevant integration and verify that its editor launches `sqruff lsp` correctly.

## Configuration boundaries for dialects and rules

sqruff presents itself as configurable, but the README exposes only one configuration key, `dialect`. The documentation links include separate pages for configuration and rules, which indicates that more settings exist, yet their names and defaults are not included in the README. That limits the level of adoption guidance that can be given from the documented commands alone.

Dialect selection is not cosmetic. SQL syntax varies between engines, and a rule or parser that behaves correctly for one dialect may need different handling for another. The quickstart chooses `postgres`, while repository topics name BigQuery, ClickHouse and Snowflake. Those topic labels do not, by themselves, establish which rules are supported for every dialect or whether formatting output is identical across all of them. A team should verify the dialect options and rule documentation for its warehouse or database before assuming coverage.

The repository also contains templating-related Python metadata, including Jinja2, dbt-related dependencies and a `jinja` optional dependency group. That confirms that the project has adjacent tooling and tests involving templated SQL or dbt-style contexts. The README does not state how a user enables those features, how templates are discovered, or whether every templater is available in every installation. Those are concrete questions to resolve in the linked usage documentation.

The absence of documented rollback and fix commands is another boundary. A linter can report findings without necessarily modifying files, but the quickstart does not specify the remediation workflow. Users should not plan a migration based on an imagined `sqruff fix` or rollback operation until they find those commands in the CLI reference.

## sqruff compared with formatter-only and lint-only workflows

The closest practical alternatives are a SQL formatter used alone, a SQL linter used without a formatter, or a separate editor SQL service. sqruff's difference is that it places both linting and formatting in one Rust-based command-line tool and also exposes an LSP entry point. A formatter-only workflow may standardize whitespace but will not provide the project's configurable lint findings. A linter-only workflow may report rule violations but will not necessarily apply a consistent layout.

The trade-off is that combining these functions makes dialect and rule configuration more important. A team that only needs indentation normalization may prefer a simpler formatter, while a team with semantic SQL rules may choose a linter that supports its database more comprehensively. sqruff is most useful when one project wants the same tool for command-line checks and editor integration, and when its documented dialect and rule behavior matches the SQL in that repository.

Compared with an editor-only solution, sqruff's CLI supports repository-oriented checks such as `sqruff lint .`, which is useful for local development or automation. Compared with a standalone formatter, its linting capability can address issues that formatting cannot express. Neither comparison establishes that sqruff covers every engine or every SQL feature. The repository supports a concrete distinction in scope, not a claim that sqruff is superior in every case.

## Maintenance, packaging and upgrade costs in sqruff

The repository is not archived, and its last push was on 2026-10-15. Recent releases include `v0.41.0` on 2026-10-06, `v0.40.0` on 2026-08-14 and `v0.39.0` on 2026-07-03. This indicates recent release activity in the repository, but it does not establish that every dialect or rule is equally mature.

The Rust workspace uses version `0.41.0`, edition `2024` and the `Apache-2.0` license. The repository also provides a Python package definition at version `0.41.0`, with optional dependency groups for development, tests, Cargo-related builds, documentation, Jinja and dbt. Contributors therefore face more than one packaging surface when working from source. The `Cargo.toml` release profile enables link-time optimization, one codegen unit, stripped binaries and no debug information, while the `Dockerfile` builds a release binary in a Rust builder stage and copies it into a Debian runtime image.

Those packaging choices can affect release and deployment work. A binary installation is simpler for end users, but source or container builds require the relevant Rust and repository build environment. The README does not provide a migration guide for upgrading from one sqruff version to another, so teams should inspect release notes and configuration documentation before changing versions. The Apache-2.0 license permits use under its terms, but organizations handling distribution or modification still need to review the actual `LICENSE` file and their own obligations.

## Conclusion

sqruff fits developers and teams that want one Rust-based command for configurable SQL linting and formatting, especially when a project uses the dialects and editor integrations covered by its documentation. It is a poorer choice for workflows that require undocumented database-specific behavior or cannot tolerate deciding how existing violations affect their repository. Evaluate it first by checking dialect support, the enabled rules in `.sqruff`, and the result of `sqruff lint .` against the project's existing SQL before changing formatting policy.

## FAQ

### How do I install sqruff?

The README documents `brew install sqruff` for macOS. For pip, Cargo and binary downloads, it directs users to the installation guide at `https://playground.quary.dev/docs/getting-started/installation/`.

### How do I lint a SQL project with sqruff?

The documented command is `sqruff lint . --dialect postgres`. You can put `dialect = postgres` under `[sqruff]` in a root `.sqruff` file and then run `sqruff lint .`.

### Does sqruff provide editor integrations?

Yes. The README says sqruff includes an LSP server started with `sqruff lsp` and that the repository maintains integrations for VS Code and Zed.

## Sources

- [License: Apache-2.0](https://github.com/quarylabs/sqruff/blob/main/LICENSE)
- [Project website](https://playground.quary.dev/docs)
- [quarylabs/sqruff on GitHub](https://github.com/quarylabs/sqruff)
- [README](https://github.com/quarylabs/sqruff/blob/main/README.md)
- [Releases](https://github.com/quarylabs/sqruff/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/quarylabs-sqruff