Skip to main content

Maturity and Stability

sqlfmt was first released in 2021; since then, it has been downloaded millions of times, integrated into dbt Cloud, and trusted by thousands of teams.

But it's also maintained by a single person and is version-zero software.

So... can you use it? That may depend on your use-case.

Project Maturity for Different Use Cases​

There are certain situations where sqlfmt can be considered feature-complete and stable. Those are:

  1. Using sqlfmt to format a dbt project (which may also include jinja and some minimal DDL/DML, like grants, create function, etc.) for one of the major, standards-conforming, OLAP dialects (Snowflake, BigQuery, Redshift, DuckDB, Postgres, MySQL).

  2. Using sqlfmt to format only select statements for one of those same dialects.

However, there are other use cases where sqlfmt is incomplete or less well-supported, and where you should use more caution:

  1. Formatting some dialects that deviate from ANSI or Postgres, like T-SQL (SQLServer).

  2. Formatting other DDL (create table, insert, etc.). For these statements, sqlfmt attempts to no-op on anything it cannot parse, but this doesn't always work. For more details on supported DDL, see this tracking issue.

Stability​

sqlfmt is being actively developed, and as version 0 software, anything about the sqlfmt style, operations, or interface may change in the future.

That said, this project conforms to semantic versioning. Patch releases will only fix bugs or add backwards-compatible features, and will not change the Python API or the formatting of files, except under two scenarios:

  1. The previous release introduced a major regression and the patch returns the behavior to the previous and intended behavior, before the regression.
  2. The patch introduces formatting changes in a very small number of scenarios, where the previous formatting was obviously deficient or undesirable.

Accordingly, at least until version 1.0, minor releases may include changes that:

  1. Change the public API
  2. Change the sqlfmt style

All such changes will be communicated via the CHANGELOG, under sections title "Breaking API Changes" and "Formatting Changes", respectively.

At this time, we will not be back-porting any commits in patch releases to older minor releases (PRs welcome).

Evolving the sqlfmt Style​

If you would like to make suggestions or otherwise be involved in the future of the sqlfmt style, please start or join a discussion in the project repo.