Skip to main content

Configuration Reference

Project Configuration (dlab.json)​

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

{
  "dialect": "postgres",
  "include": [
    "**.sql"
  ],
  "exclude": [],
  "dfmt": {
    "keywordCase": "lower",
    "identifierCase": "lower",
    "functionCase": "lower",
    "dataTypeCase": "lower",
    "indentWidth": 4,
    "maxLineWidth": 80,
    "clauseLayout": "indented",
    "commaStyle": "trailing",
    "andOrPosition": "before",
    "linesBetweenStatements": 1,
    "preserveExtraBlankLinesBetweenStatements": false,
    "shortStatementsOneLine": true,
    "alignTokens": "",
    "blankLineBetweenCtes": true,
    "listLayout": "auto",
    "consistentSiblings": false,
    "clarifyStructure": true,
    "clauseAlignment": "left",
    "cteNamesOnNewLine": true,
    "preserveBreaks": "off"
  }
}

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

CLI usage:

sqlfmt --init postgres   # Create dlab.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: 80
Description: Target maximum line width. Constructs that do not fit are broken across lines; 0 turns width-based breaking off entirely, leaving layout to the line breaks already in the source.

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.

preserveExtraBlankLinesBetweenStatements​

CLI flag: --preserve-extra-blank-lines-between-statements
Type: true | false
Default: false
Description: When enabled, gaps between top-level statements that exceed linesBetweenStatements blank lines in the source are preserved (capped by the source count). When disabled, every gap collapses to exactly linesBetweenStatements blank lines.

shortStatementsOneLine​

CLI flag: --short-statements-one-line
Type: true | false
Default: true
Description: When enabled, short queries that fit within maxLineWidth stay on one 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.

listLayout​

CLI flag: --list-layout
Type: stacked | packed | auto
Default: auto
Description: Controls how items in a broken comma-separated list arrange on lines. STACKED: one item per line. PACKED: paragraph-wrap, pack items greedily onto lines. AUTO: all-or-nothing — a list fits on one line or breaks one item per line.

consistentSiblings​

CLI flag: --consistent-siblings
Type: true | false
Default: false
Description: When enabled, if any item in a list breaks internally, all siblings break too. Works with any listLayout value.

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.

preserveBreaks​

CLI flag: --preserve-breaks
Type: off | breaks_only | breaks_and_alignment
Default: off
Description: Controls how the formatter reads line breaks in the user's original SQL. off: pure width-only formatting. breaks_only: preserve newlines between list items. breaks_and_alignment: also honor manual column alignment.

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/