Skip to main content

Introduction to sqlfmt

sqlfmt formats your dbt SQL files so you don't have to. It is similar in nature to Black, gofmt, and rustfmt (but for SQL).

  1. sqlfmt promotes collaboration. An auto-formatter makes it easier to collaborate with your team and solicit contributions from new people. You will never have to mention (or argue about) code style in code reviews again.
  2. sqlfmt is fast. Forget about formatting your code, and spend your time on business logic instead. sqlfmt processes hundreds of files per second and only operates on files that have changed since the last run.
  3. sqlfmt works with Jinja. It formats the code that users look at, and therefore doesn't need to know anything about what happens after the templates are rendered.
  4. sqlfmt integrates with your workflow. As a CLI written in Python, it's easy to install locally on any OS and run in CI. Plays well with dbt, pre-commit, SQLFluff, VSCode, and GitHub Actions. The sqlfmt API powers the dbt Cloud IDE's Format button.
  5. sqlfmt speaks any dialect. Most likely you don't even have to configure anything. (Sorry, ClickHouse)

sqlfmt is a command-line tool that is built in Python and runs on MacOS, Linux, and Windows, so you can run it locally and in CI.

sqlfmt is not configurable, except for line length: it enforces a single style. sqlfmt maintains comments and some extra newlines, but largely ignores all indentation and line breaks in the input file.

sqlfmt is not a linter. It does not parse your code into an AST; it just lexes it and tracks a small subset of tokens that impact formatting. This lets us "do one thing and do it well:" sqlfmt is very fast, easy to maintain, and easy to extend, compared to linters that need a full SQL grammar.

sqlfmt is designed to work with templated SQL files that contain Jinja tags and blocks. It formats the code that users look at, and therefore doesn't need to know anything about what happens after the templates are rendered.

Limited DDL and DML

For now, sqlfmt only works on select, delete, grant, revoke, and create function statements (which is all you need if you use sqlfmt with a dbt project). It is being extended to additional DDL and DML. See this tracking issue for more information.