Skip to content

chore: document the config option #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tconbeer merged 1 commit into from
Jul 28, 2025
Merged

chore: document the config option #51

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 22 additions & 21 deletions docs/getting-started/configuring-sqlfmt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,28 +69,29 @@ If you have `NO_COLOR` set (for other programs) and want sqlfmt to colorize outp
use the force-color option, via `--force-color`, `SQLFMT_FORCE_COLOR`, or `force_color=true`
in your `pyproject.toml` file.

If the force-color option is set, sqlfmt will colorize output, no matter how no-color and
If the force-color option is set, sqlfmt will colorize output, no matter how no-color and
force-color are set. For example, if `force_color=true` is set in the config file, but
sqlfmt is run with the `--no-color` option, it **will** colorize output.
sqlfmt is run with the `--no-color` option, it **will** colorize output.

## Configuration Reference

| CLI Option | Environment Variable | Config File | Description |
|------------------------------------------|--------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--help` | ❌ | ❌ | Show the help message and exit. |
| `--version` | ❌ | ❌ | Show the version and exit. |
| `--check` | `SQLFMT_CHECK=1` | `check=true` | Fail with an exit code of 1 if source files are not formatted to spec. Do not write formatted queries to files. |
| `--diff` | `SQLFMT_DIFF=1` | `diff=true` | Print a diff of any formatting changes to stdout. Fails like `--check` on any changes. Do not write formatted queries to files. |
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
| `--exclude ./my_dir/**/*.sql` | `SQLFMT_EXCLUDE="./my_dir/**/*.sql"` | `exclude=["./my_dir/**/*.sql"]` | A string that is passed to glob.glob as a pathname; any matching files returned by glob will be excluded from FILES and not formatted. Note that glob is relative to the current working directory when sqlfmt is called. To exclude multiple globs, repeat the `--exclude` option. The TOML file takes a list of strings. |
| `--encoding inherit` | `SQLFMT_ENCODING=inherit` | `encoding="inherit"` | The encoding to use when reading and writing .sql files. Defaults to utf-8. Set to 'inherit' to read the system default encoding. utf encodings will detect and preserve the BOM if one is present. |
| `-d clickhouse`, `--dialect clickhouse` | `SQLFMT_DIALECT=clickhouse` | `dialect="clickhouse"` | The SQL dialect for the target files. Nearly all dialects are supported by the default polyglot dialect. Select the ClickHouse dialect to respect case sensitivity in function, field, and alias names. |
| `--no-jinjafmt` | `SQLFMT_NO_JINJAFMT=1` | `no_jinjafmt=true` | Do not format Jinja tags (the code between the curlies). Only necessary to specify this flag if sqlfmt was installed with the jinjafmt extra, or if *Black* was already available in this environment. |
| `--fast`, `--safe` | `SQLFMT_FAST=1` | `fast=true` | By default, sqlfmt re-processes the output it produces in order to run a safety check and ensure that all tokens from the input are present in the output. This can add 15-20% to the processing time for new files. To disable this safety check, use the `--fast` option. To force the safety check, use `--safe`." |
| `-k`, `--reset-cache` | `SQLFMT_RESET_CACHE=1` | `reset_cache=true` | Clear the sqlfmt cache before running, effectively forcing sqlfmt to operate on every file. Will slow down runs. |
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
| `--no-color` | `NO_COLOR=1`, `SQLFMT_NO_COLOR=1` | `no_color=true` | Removes color codes from all output, including diffs. See https://no-color.org/ for more details. |
| `--force-color` | `SQLFMT_FORCE_COLOR=1` | `force_color=true` | sqlfmt output is colorized by default. However, if you have the `NO_COLOR` env var set, and still want sqlfmt to colorize output, you can use `--force-color` to override the no-color option. |
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
| `--single-process` | `SQLFMT_SINGLE_PROCESS=1` | `single_process=true` | Run sqlfmt in a single process, even when formatting multiple files. If not set, defaults to multiprocessing using as many cores as possible. Also disables the progress bar. Will slow down runs. |
| CLI Option | Environment Variable | Config File | Description |
|------------------------------------------|-----------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--help` | ❌ | ❌ | Show the help message and exit. |
| `--version` | ❌ | ❌ | Show the version and exit. |
| `--check` | `SQLFMT_CHECK=1` | `check=true` | Fail with an exit code of 1 if source files are not formatted to spec. Do not write formatted queries to files. |
| `--diff` | `SQLFMT_DIFF=1` | `diff=true` | Print a diff of any formatting changes to stdout. Fails like `--check` on any changes. Do not write formatted queries to files. |
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
| `--exclude ./my_dir/**/*.sql` | `SQLFMT_EXCLUDE="./my_dir/**/*.sql"` | `exclude=["./my_dir/**/*.sql"]` | A string that is passed to glob.glob as a pathname; any matching files returned by glob will be excluded from FILES and not formatted. Note that glob is relative to the current working directory when sqlfmt is called. To exclude multiple globs, repeat the `--exclude` option. The TOML file takes a list of strings. |
| `--encoding inherit` | `SQLFMT_ENCODING=inherit` | `encoding="inherit"` | The encoding to use when reading and writing .sql files. Defaults to utf-8. Set to 'inherit' to read the system default encoding. utf encodings will detect and preserve the BOM if one is present. |
| `-d clickhouse`, `--dialect clickhouse` | `SQLFMT_DIALECT=clickhouse` | `dialect="clickhouse"` | The SQL dialect for the target files. Nearly all dialects are supported by the default polyglot dialect. Select the ClickHouse dialect to respect case sensitivity in function, field, and alias names. |
| `--no-jinjafmt` | `SQLFMT_NO_JINJAFMT=1` | `no_jinjafmt=true` | Do not format Jinja tags (the code between the curlies). Only necessary to specify this flag if sqlfmt was installed with the jinjafmt extra, or if *Black* was already available in this environment. |
| `--fast`, `--safe` | `SQLFMT_FAST=1` | `fast=true` | By default, sqlfmt re-processes the output it produces in order to run a safety check and ensure that all tokens from the input are present in the output. This can add 15-20% to the processing time for new files. To disable this safety check, use the `--fast` option. To force the safety check, use `--safe`." |
| `-k`, `--reset-cache` | `SQLFMT_RESET_CACHE=1` | `reset_cache=true` | Clear the sqlfmt cache before running, effectively forcing sqlfmt to operate on every file. Will slow down runs. |
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
| `--no-color` | `NO_COLOR=1`, `SQLFMT_NO_COLOR=1` | `no_color=true` | Removes color codes from all output, including diffs. See https://no-color.org/ for more details. |
| `--force-color` | `SQLFMT_FORCE_COLOR=1` | `force_color=true` | sqlfmt output is colorized by default. However, if you have the `NO_COLOR` env var set, and still want sqlfmt to colorize output, you can use `--force-color` to override the no-color option. |
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
| `--single-process` | `SQLFMT_SINGLE_PROCESS=1` | `single_process=true` | Run sqlfmt in a single process, even when formatting multiple files. If not set, defaults to multiprocessing using as many cores as possible. Also disables the progress bar. Will slow down runs. |
| `--config` | `SQLFMT_CONFIG=/path/to/pyproject.toml` | ❌ | Provide sqlfmt with a configuration file directly. If not set, sqlfmt will attempt to find a configuration file automatically. Other options passed at the command line will override settings in this file. Must exist or an exception will be thrown. |