{"id":4257,"library":"shandy-sqlfmt","title":"sqlfmt","description":"sqlfmt is an opinionated Python-based command-line tool that automatically formats your dbt SQL files and other SQL statements. Similar to `black` for Python, it enforces a consistent style with minimal configuration, primarily line length. It is currently at version 0.29.0 and maintains an active release cadence with frequent updates.","status":"active","version":"0.29.0","language":"python","source_language":"en","source_url":"https://github.com/tconbeer/sqlfmt","tags":["sql","formatter","dbt","cli","code-quality"],"install":[{"cmd":"pip install shandy-sqlfmt","lang":"bash","label":"With pip"},{"cmd":"pipx install shandy-sqlfmt","lang":"bash","label":"Recommended with pipx"},{"cmd":"pipx install shandy-sqlfmt[jinjafmt]","lang":"bash","label":"With jinjafmt extra (includes black)"}],"dependencies":[{"reason":"Required for running the tool.","package":"python","version_constraint":">=3.10"}],"imports":[],"quickstart":{"code":"# To format all .sql and .sql.jinja files in the current directory and subdirectories:\nsqlfmt .\n\n# To see a diff of changes sqlfmt would make (without modifying files):\nsqlfmt --diff .\n\n# To format SQL from stdin and print to stdout:\necho \"select 1,2,3 from my_table where a=1\" | sqlfmt -","lang":"bash","description":"sqlfmt is primarily a command-line tool. The most common usage is to format files in a directory. It will exit with a non-zero code if files are not formatted when using `--check` or `--diff`."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or higher. For example, using pyenv or updating your system Python.","message":"sqlfmt now requires Python 3.10 or newer. Users on older Python versions will need to upgrade their environment.","severity":"breaking","affected_versions":"0.29.0+"},{"fix":"Always use sqlfmt within a version-controlled project (e.g., Git) and commit your changes before running the formatter. Review the diffs carefully before accepting them.","message":"sqlfmt is an alpha product and might not always produce the desired formatted output, or could potentially break SQL syntax. It is strongly recommended to run it on files in a version control system and commit changes before running sqlfmt.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust any scripts or processes that consume `sqlfmt`'s stdout to account for the absence of the previously included extra trailing newline.","message":"When writing formatted code to stdout, sqlfmt no longer includes an extra trailing newline. This may affect scripts or tools that expect an additional newline when piping `sqlfmt` output.","severity":"breaking","affected_versions":"0.29.0+"},{"fix":"Understand that `sqlfmt` prioritizes consistency over customization. If its style does not align with your needs, consider alternatives or adapt your team to the `sqlfmt` style.","message":"sqlfmt is opinionated and not configurable beyond line length. It enforces a single style. If you require highly customizable formatting rules, sqlfmt may not be suitable.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.29.0':45 'activ':49 'automat':14 'base':8 'black':26 'cadenc':51 'cli':58 'code':60 'code-qu':59 'command':10 'command-lin':9 'configur':36 'consist':32 'current':42 'dbt':17,57 'enforc':30 'file':19 'format':15 'formatt':56 'frequent':53 'length':39 'line':11,38 'maintain':47 'minim':35 'opinion':5 'primarili':37 'python':7,28 'python-bas':6 'qualiti':61 'releas':50 'similar':24 'sql':18,22,55 'sqlfmt':1,2 'statement':23 'style':33 'tool':12 'updat':54 'version':44","created_at":"2026-04-12T03:47:39.020731+00:00","updated_at":"2026-04-16T21:40:26.438983+00:00","problems":[{"fix":"Activate your virtual environment if you used one for installation. Alternatively, ensure the directory containing the `sqlfmt` executable (e.g., `~/.local/bin` on Linux/macOS or `C:\\Users\\YourUser\\AppData\\Roaming\\Python\\Scripts` on Windows) is in your system's PATH, or run it using `python -m sqlfmt`.","cause":"The `sqlfmt` executable is not in the system's PATH, typically because pip installed it to a user-specific binary directory or it was installed in an inactive virtual environment.","error":"sqlfmt: command not found"},{"fix":"Simplify the SQL statement causing the error or adjust it to be more standard. If using dbt/Jinja, try to isolate the problematic part or use `{# sqlfmt: off #}` and `{# sqlfmt: on #}` comments to exclude specific blocks from formatting. Ensure your `shandy-sqlfmt` version is up-to-date, as parsing capabilities are frequently improved.","cause":"The SQL file contains syntax that `sqlfmt`'s parser does not understand or expects a different token at a specific position, often due to complex or non-standard SQL, or issues with Jinja templating.","error":"sqlfmt.parser.ParseError: Expected"},{"fix":"Run `sqlfmt .` (or `sqlfmt <target_files>`) without the `--check` flag to automatically format the files, then commit the changes.","cause":"`sqlfmt` was run with the `--check` flag (common in CI/CD pipelines), and one or more SQL files did not conform to the expected format.","error":"Exiting with code 1 due to unformatted files."},{"fix":"Consult the `sqlfmt --help` output or the official documentation (on GitHub) for the correct and current command-line options.","cause":"The user passed an argument or option to `sqlfmt` that is not recognized by the current version of the tool, possibly due to a typo, deprecation, or an option from a different tool.","error":"Error: No such option: --<some_option>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"sqlfmt","cli_version":"sqlfmt, version 0.30.0","type":"library","homepage":"https://sqlfmt.com","github":"https://github.com/tconbeer/sqlfmt","docs":"https://docs.sqlfmt.com","changelog":"https://github.com/tconbeer/sqlfmt/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/shandy-sqlfmt/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-11","next_check":"2026-07-10","install_tag":null}}