Is this still considered "alpha"?

[pgoslatara]

I've been using sqlfmt at several clients and really love it's simplicity and speed. One pushback I get when I propose sqlfmt is the following sentence in the README:

sqlfmt is an alpha product and will not always produce the formatted output you might want.

I totally agree with the warning about how sqlfmt works but is this tool still "alpha"? It's over 1.5 years since that line was added (PR) and based on my experience this is a fully-fledged ready-to-use formatter. Would love to see this word removed and make sqlfmt easier to onboard to new teams!

[tconbeer]

Thanks for the feedback, @pgoslatara . There are certain situations where I would consider the software to be in Beta, or even more mature than that. Those are:

1. Using sqlfmt to format select statements for one of the major dialects (pg, MySQL, Snowflake, BQ, Redshift)
2. 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 dialects.

However, there are other use cases where we are very much alpha:

1. Formatting some weirder dialects, like SQLServer
2. Formatting other DDL (create table, insert, etc.) (we try to no-op on these statements as much as possible)
   In these domains we are nowhere near "feature complete."

I personally use sqlfmt on all of my dbt projects and have never had a real issue. The project is also extensively tested against both our own repo of queries and very large public projects (gitlab, http archive, rittman analytics) to prevent regressions and unintended formatting.

If you use source control and have automated tests against your SQL, I think the risks are low that we introduce breaking changes into your code, and very low that those slip past code review and automated testing. I would, however, hesitate to run sqlfmt against a folder of DDL statements on an analyst's harddrive.

The final risk here is that I'm the only maintainer, and there have been limited community contributions (I've easily written 99.9% of the code in this project). And I have four other jobs.

If you'd like to propose different, less-scary language, I'm open to it! (This same disclaimer also appears in at least two places in the docs site).

[pgoslatara]

@tconbeer Thanks for the awesomely comprehensive reply! I'd love to update this note in the hope that it encourages more use of sqlfmt. What do you think of this (highly paraphrased, not too scary) replacement:

sqlfmt will not always produce the formatted output you might want. It might even break your SQL syntax. It is highly recommended to only run sqlfmt on files in a version control system (like git), so that it is easy for you to revert any changes made by sqlfmt. On your first run, be sure to make a commit before running sqlfmt.

There are certain situations where sqlfmt can be considered to be in Beta, or even more mature than that. Those are:

1. Using sqlfmt to format select statements for one of the major dialects (PostgresSQL, MySQL, Snowflake, BQ, Redshift).
2. 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 dialects.

However, there are other use cases where sqlfmt is very much alpha:

1. Formatting some less widely used dialects, like SQLServer.
2. Formatting other DDL (create table, insert, etc.) (sqlfmt attempts to be no-op on these statements as much as possible).

In these domains sqlfmt is nowhere near "feature complete" and caution is highly advised.