Skip to main content

Configuration Reference

Project Configuration (.dfmt.json)​

Create a .dfmt.json file in your project root to configure formatting. The CLI discovers it by walking parent directories.

{
  "dialect": "postgres",
  "keywordCase": "lower",
  "identifierCase": "lower",
  "functionCase": "lower",
  "dataTypeCase": "lower",
  "indentWidth": 4,
  "maxLineWidth": 120,
  "clauseLayout": "indented",
  "commaStyle": "trailing",
  "andOrPosition": "before",
  "linesBetweenStatements": 1,
  "shortStatementsOneLine": false,
  "alignTokens": "",
  "blankLineBetweenCtes": true,
  "siblingLayout": "stacked",
  "clarifyStructure": true,
  "clauseAlignment": "left",
  "cteNamesOnNewLine": true,
  "include": [
    "**.sql"
  ],
  "exclude": []
}

Precedence (lowest to highest): defaults → .dfmt.json → CLI flags.

CLI usage:

sqlfmt --init postgres   # Create .dfmt.json with defaults
sqlfmt .                 # Format current directory (dialect from config)
sqlfmt . --write         # Format and write back
sqlfmt . --check         # Check mode (exit 1 if changes needed)

Formatting Options​

keywordCase​

CLI flag: --keyword-case
Type: upper | lower | preserve
Default: lower
Description: Controls the casing of SQL keywords (SELECT, FROM, WHERE, JOIN, etc.).

identifierCase​

CLI flag: --identifier-case
Type: upper | lower | preserve
Default: lower
Description: Controls the casing of identifiers (column names, table names, aliases).

functionCase​

CLI flag: --function-case
Type: upper | lower | preserve
Default: lower
Description: Controls the casing of function names (count, sum, coalesce, etc.). When different from keyword case, function names are cased independently.

dataTypeCase​

CLI flag: --data-type-case
Type: upper | lower | preserve
Default: lower
Description: Controls the casing of data type keywords (INT, VARCHAR, BOOLEAN, NUMERIC, etc.). When different from keyword case, data types are cased independently.

indentWidth​

CLI flag: --indent-width
Type: integer (1-8)
Default: 4
Description: Number of spaces per indentation level (used for subqueries, CASE branches, continuation lines).

maxLineWidth​

CLI flag: --max-line-width
Type: integer (0-200)
Default: 120
Description: Target maximum line width. When set with WIDTH_AWARE newline modes, lines exceeding this width are broken. 0 disables width-based breaking.

clauseLayout​

CLI flag: --clause-layout
Type: indented | left_aligned | inline
Default: indented
Description: Controls how SQL clauses are laid out. INDENTED: each clause on its own line, body indented. LEFT_ALIGNED: each clause on its own line, body at same indent. INLINE: all clauses on one line.

commaStyle​

CLI flag: --comma-style
Type: trailing | leading
Default: trailing
Description: Controls whether commas appear at the end of the line (trailing) or the beginning of the next line (leading).

andOrPosition​

CLI flag: --and-or-position
Type: before | after
Default: before
Description: Controls where AND/OR operators are placed relative to line breaks. BEFORE: AND/OR starts a new line. AFTER: AND/OR ends the line, continuation on next line.

linesBetweenStatements​

CLI flag: --lines-between-statements
Type: integer (0-5)
Default: 1
Description: Number of blank lines between statements when formatting multiple statements. 0 means just a newline, 1 means one blank line, etc.

shortStatementsOneLine​

CLI flag: --collapse-short-statements
Type: true | false
Default: false
Description: When enabled with maxLineWidth, short queries that fit on one line are collapsed to a single line. Only applies to top-level statements.

alignTokens​

CLI flag: --align-tokens
Type: string
Default: ``
Description: Comma-separated list of tokens to vertically align across siblings. Common values: AS, THEN, =. Empty means no alignment.

blankLineBetweenCtes​

CLI flag: --blank-line-between-ctes
Type: true | false
Default: true
Description: When enabled, inserts a blank line between CTEs in a WITH clause for visual separation.

siblingLayout​

CLI flag: --sibling-layout
Type: stacked | consistent | pack
Default: stacked
Description: Controls how sibling items in a broken list relate to each other. STACKED: one item per line, each decides internal layout independently. CONSISTENT: one item per line, if any item breaks internally all break. PACK: items share lines by width.

clarifyStructure​

CLI flag: --clarify-structure
Type: true | false
Default: true
Description: Makes implicit SQL structure explicit with parentheses: AND/OR precedence (a OR b AND c → a OR (b AND c)) and set operation boundaries (SELECT A UNION ALL SELECT B → (SELECT A) UNION ALL (SELECT B)).

clauseAlignment​

CLI flag: --clause-alignment
Type: left | right
Default: left
Description: LEFT (default): keywords left-aligned. RIGHT: keywords right-aligned (river style).

cteNamesOnNewLine​

CLI flag: --cte-names-on-new-line
Type: true | false
Default: true
Description: When true (default), CTE names start on a new indented line after WITH.

File Selection​

include​

Type: array of glob patterns
Default: ["**.sql"]
Description: Glob patterns for files to format. Files must match at least one include pattern.

exclude​

Type: array of glob patterns
Default: []
Description: Glob patterns for files to skip. Exclude takes precedence over include.

Common patterns​

PatternMatches
**.sqlAll .sql files recursively
models/**.sqlSQL files under models/
target/**Files in any target directory
vendor/**Files in vendor/