English | 日本語

sql-dialect-fmt

English | 日本語

sql-dialect-fmt is an opinionated Rust formatter and editor toolchain for Snowflake SQL and Databricks SQL. It follows the gofmt / Prettier / Biome style: few options, stable output, and formatting that is safe to run in CI.

Formatting is mechanically lossless and idempotent. Inputs that cannot be parsed pass through unchanged, significant tokens and comments are preserved, and format(format(x)) == format(x).

Install

# From crates.io
cargo install sql-dialect-fmt --version 1.17.2 --locked

# Directly from this repository
cargo install --git https://github.com/hjosugi/sql-dialect-fmt sql-dialect-fmt

# From a local checkout
cargo install --path crates/sql-dialect-fmt-cli

# Binary install, when using release assets with cargo-binstall
cargo binstall sql-dialect-fmt

# Homebrew, using this repository as a tap
brew tap hjosugi/sql-dialect-fmt https://github.com/hjosugi/sql-dialect-fmt
brew install sql-dialect-fmt

CI can use the bundled composite action or the GHCR image.

- uses: hjosugi/sql-dialect-fmt@v1
  with:
    args: "sql/**/*.sql"

docker run --rm -v "$PWD:/work" -w /work ghcr.io/hjosugi/sql-dialect-fmt:1.17.2 --check .

Try the browser playground from the docs site: https://hjosugi.github.io/sql-dialect-fmt/playground.html

Usage

sql-dialect-fmt query.sql                 # format to stdout
sql-dialect-fmt --write *.sql             # rewrite files in place
sql-dialect-fmt --check src/**/*.sql      # non-zero when files are not formatted
sql-dialect-fmt --check --diff query.sql  # show a unified diff for unformatted input
sql-dialect-fmt --lint src/               # lint (SDF001-SDF007): path:line:col findings, exit 1 when any
cat query.sql | sql-dialect-fmt           # stdin to stdout
cat query.sql | sql-dialect-fmt -         # explicitly read stdin with `-`
sql-dialect-fmt --stdin-filepath src/query.sql < query.sql  # use a path for config discovery
cat query.sql | sql-dialect-fmt --range 40:120  # reformat only statements in a byte range (stdin)

# Options: --dialect snowflake|databricks / --line-width N / --indent-width N / --no-uppercase

pre-commit users can enable the official hooks:

repos:
  - repo: https://github.com/hjosugi/sql-dialect-fmt
    rev: v1.17.2
    hooks:
      - id: sql-dialect-fmt

Use sql-dialect-fmt-check instead when a hook should only verify formatting.

Browser Extension

The Chrome extension in extensions/chrome formats SQL in Snowsight and Databricks browser editors. It bundles the Rust formatter as WebAssembly, so no local server is needed.

./scripts/build-chrome-extension.sh

Then open chrome://extensions, enable Developer mode, and load extensions/chrome unpacked. Focus a SQL editor and run the formatter from the floating button, the extension action, or Alt+Shift+F. The options page controls dialect, line width, indent width, and keyword casing.

Release packages for the Chrome extension and VS Code extension are built together:

./scripts/package-extensions.sh

VS Code Extension

The VS Code extension in editors adds Snowflake SQL syntax highlighting and formatting. It registers a formatter for snowflake-sql files, so Format Document, Format Selection, and editor.formatOnSave all work with no external binary. Like the Chrome extension, it bundles the Rust formatter as WebAssembly and formats entirely on your machine.

./scripts/build-vscode-extension.sh

Then press F5 in editors/ (or install the packaged VSIX) and run Format Document on a .sql file. Formatting honors the sqlDialectFmt.* settings (dialect, line width, indent width, keyword casing).

Development

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
cargo fmt --all --check

Formatter feature flags

sql-dialect-fmt-formatter enables embedded JavaScript and Python formatting by default through the external-formatters feature. Minimal builds can drop the Biome/Ruff formatter graph:

cargo test -p sql-dialect-fmt-formatter --no-default-features

Fine-grained features are available for embedders:

Status

Snowflake support covers SELECT, DML (INSERT/UPDATE/DELETE/MERGE), COPY, major DDL and object DDL, Semantic View, and CREATE PROCEDURE/CREATE FUNCTION bodies in SQL, JavaScript, Python, Java, and Scala. JavaScript/Python embedded body formatting is enabled by default; Java and Scala body formatting is opt-in through embedded-brace-formatters and otherwise stays verbatim. Databricks mode covers LATERAL VIEW, Delta DDL options, VERSION/TIMESTAMP AS OF, higher-order-function lambdas, SQL scripting blocks, and backtick identifiers.

SQL lifted out of a host language keeps formatting and highlighting: a ${ ... } template placeholder — a JavaScript template literal (`SELECT ${cfg.col} FROM ${cfg.t}`) or a Databricks/Spark/dbt ${var} substitution — is treated as one atomic token, with nested braces, quoted }, and nested template literals balanced so the statement still parses and the placeholder round-trips verbatim.

The workspace also includes an LSP server, semantic tokens, hover text, a Tree-sitter grammar, a CLI, VS Code packaging, and the Chrome/WASM extension. The LSP server discovers and applies the same sql-dialect-fmt.toml as the CLI (with editor settings layered on top), so an editor formats consistently with CI. The headline formatter feature is magic trailing comma. See ROADMAP.md for the detailed coverage map.

Crates

License

0BSD. You can use, copy, modify, and distribute this project for almost any purpose.