You probably don't need to configure sqlfmt at all! sqlfmt supports nearly all SQL dialects without configuration, and doesn't require a Jinja templater.
sqlfmt's style is not configurable, except for the line length (the default is 88). To set the line length, use the
--line-length option. For example, to run sqlfmt with a line length of 99:
sqlfmt -l 99 .
sqlfmt's operation, however, is highly configurable using options at the command line. For a full list of options, see below, or type:
Using Environment Variables
Any CLI option can be configured using environment variables. Variable names are prefixed by
SQLFMT and are the
SHOUTING_CASE spelling of the options. For example,
sqlfmt . --line-length 100 is equivalent to
SQLFMT_LINE_LENGTH=100 sqlfmt . Boolean flags can be set to any truthy value.
Any command-line option for sqlfmt can also be set in a
pyproject.toml file, under a
[tool.sqlfmt] section header. Options passed at the command line will override the settings in the config file.
sqlfmt will search for the
pyproject.toml file using the
files passed to it as arguments. It starts in the lowest (most specific) common parent directory to all the
files and recurses up to the root directory. It will load settings from the first
pyproject.toml file it finds in this search.
Example of a
pyproject.toml file to run sqlfmt in
check mode with a line length of 99:
line_length = 99
check = true
String literals in TOML files must be quoted!
If conflicting config is given to sqlfmt, config will be resolved in the following order:
- An explicit option passed at invocation (e.g.,
- A set environment variable (e.g.,
- A value from the
- The default behavior (e.g., 88 characters)
No-color and Force-color
sqlfmt output is colorized by default, by adding ANSI color codes to the terminal output.
sqlfmt supports the standard from no-color.org, and will not
colorize output if the
NO_COLOR environment variable is set. We achieve this by
implementing a "no-color" option, which can also be set via the sqlfmt-specific environment
SQLFMT_NO_COLOR, the CLI option
--no-color, or by setting
If you have
NO_COLOR set (for other programs) and want sqlfmt to colorize output, you can
use the force-color option, via
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.
|CLI Option||Environment Variable||Config File||Description|
|❌||❌||Show the help message and exit.|
|❌||❌||Show the version and exit.|
|Fail with an exit code of 1 if source files are not formatted to spec. Do not write formatted queries to files.|
|Print a diff of any formatting changes to stdout. Fails like |
|The maximum line length allowed in output files. Default is 88.|
|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 |
|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.|
|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.|
|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.|
|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 |
|Clear the sqlfmt cache before running, effectively forcing sqlfmt to operate on every file. Will slow down runs.|
|Prints more information to stderr.|
|Prints much less information to stderr.|
|Removes color codes from all output, including diffs. See https://no-color.org/ for more details.|
|sqlfmt output is colorized by default. However, if you have the |
|Never prints a progressbar to stderr.|
|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.|