All flags#

Generated from the parser, so it cannot fall behind it. The sections below explain the ones that need more than a line.

sqlalign [OPTIONS] FILE_OR_DIRECTORY...

Every flag below is the complete set — this page is written against sqlalign --help and nothing is omitted. New to the tool? Start with Getting started; this page is for looking things up. For committing these settings to a config file rather than typing them, see Configuration.

Defaults marked (house) are what you get with no config file and no flags.

Positional arguments#

A single - reads stdin and writes the result to stdout, which is what an editor's format-on-save runs through a generic external-formatter setting:

cat query.sql | sqlalign -
sqlalign - --dialect tsql < query.sql

--check and --diff still report rather than write when the input is -, so sqlalign --check - is a gate on piped SQL. - cannot be combined with file arguments: stdin is read once, so that has no sensible reading.

Output mode#

By default sqlalign rewrites each file in place and prints nothing. These flags change that.

--check, --stdout and --diff are mutually exclusive. Passing two is an argument error, not a silent precedence rule:

sqlalign: error: argument --stdout: not allowed with argument --check

A file with lone \r (classic-Mac) line endings is not a shape sqlalign models; it is passed through untouched with a warning.

File selection#

A file you name explicitly on the command line is never excluded — naming it is a clearer signal of intent than a pattern in a config file.

Exclusions are resolved per directory argument, before per-file style resolution, from --exclude plus the exclude key of the config discovered at that directory.

Configuration#

sqlalign reads a .sqlalign.toml, or a [tool.sqlalign] table in a pyproject.toml, discovered by walking up from each file being formatted. Precedence is built-in defaults → preset → config file → command-line flags.

--show-config resolves the config against the first path you give it, so in a repo with per-directory configs, ask about the directory you care about. Its output is valid TOML you can paste straight into a config file:

sqlalign --show-config .

# built-in defaults (no config file found)
width = 100
align = true
align_targets = ["aliases", "case_results", "column_aliases", "column_constraints", "column_types", "join_conditions", "operators", "table_aliases"]
comma_position = "leading"
boolean_operator_position = "leading"
on_placement = "inline"
select_placement = "inline"
select_indent = 2
clause_keyword_align = "left"
river_gutter = 6
format_dollar_bodies = true
neq_style = "!="
decimal_style = "NUMERIC"
table_alias_style = "bare"
keyword_case = "upper"
protect_templating = true
# blank_lines_between_statements is unset: one blank line between two
# multi-line statements, none otherwise. Set an integer to force a count.

Valid config keys#

Every key below is accepted in .sqlalign.toml or [tool.sqlalign]. Anything else is an error unless you pass --no-strict-config.

align · align_targets · blank_lines_between_statements · boolean_operator_position · clause_keyword_align · comma_position · decimal_style · dialect · exclude · format_dollar_bodies · keyword_case · neq_style · on_placement · preset · protect_templating · river_gutter · select_indent · select_placement · table_alias_style · width

Formatting a selection#

$ sqlalign --lines 40:58 models/orders.sql        # just those lines
$ sqlalign --lines 12 --lines 40:58 orders.sql    # two selections
$ sqlalign --diff --lines 40:58 orders.sql        # review before writing

The unit is the statement, not the line. Half a statement does not parse, so a range starting or ending inside one formats that statement entire — which is also what a dragged editor selection means. A range that covers only blank lines selects nothing and the file is left alone.

Everything outside the range is byte-identical, including the blank lines around it. Asking for line 12 is not asking for the spacing at line 40 to be normalised.

The use this exists for is adopting sqlalign on a repository nobody wants to reformat in one commit: format the lines your change touches, leave the rest, and the review stays about your change. For an editor filter that hands over just the selected text — a visual selection piped through :! in vim — use stdin instead: sqlalign - formats what it is given and needs no line numbers.

--line-ending is the only setting with no config key. Three of the four --no-* flags map onto the positive keys: --no-align is align = false, --no-protect-templating is protect_templating = false, and --no-format-bodies is format_dollar_bodies = false. The fourth, --no-strict-config, is not a style setting at all — it changes how the config file itself is read.

Style#

--neq-style and --decimal-style exist because sqlglot's parser collapses each of those pairs into a single AST node, so a spelling has to be chosen when printing. They are the only two places sqlalign picks for you.

Presets#

dbt ships with its one remaining deviation stated: dbt indents nested blocks 4, sqlalign indents a CTE body 2.

Alignment targets#

An unknown name is an error, not a silent no-op:

sqlalign: unknown align_targets ['alias']; valid: ['aliases', 'case_results', 'column_aliases', 'column_constraints', 'column_types', 'join_conditions', 'operators', 'table_aliases', 'table_names']

--no-align is the shorthand for switching every target off.

Exit codes#

Per-file failures do not abort the run: the file is reported on stderr and skipped, the rest still process, and the worst code seen is returned.

sqlalign --check nope.sql still.sql
# sqlalign: [Errno 2] No such file or directory: 'nope.sql'
# would reformat still.sql
# exit 2

Worked invocations#

Each block below is real output. The input for the style examples is tests/fixtures/input/13.sql; the default rendering of it is in the README.

Adopt the line structure without the padding#

sqlalign --stdout --no-align 13.sql

-- #13: multi-character aliases (mixed lengths)
SELECT cust.customer_id
     , cust.email
     , ord.order_id
     , ord.total
     , line_items.product_id
     , line_items.quantity
     , addr.city
FROM customers cust
INNER JOIN orders ord ON ord.customer_id = cust.customer_id
LEFT JOIN order_line_items line_items ON line_items.order_id = ord.order_id
LEFT JOIN shipping_addresses addr ON addr.order_id = ord.order_id
  AND addr.address_type = 'shipping'
WHERE ord.order_date >= '2026-07-01'
  AND cust.segment = 'enterprise';

Keep the alignment, move the separators to end of line#

sqlalign --stdout --preset trailing 13.sql

-- #13: multi-character aliases (mixed lengths)
SELECT cust.customer_id,
       cust.email,
       ord.order_id,
       ord.total,
       line_items.product_id,
       line_items.quantity,
       addr.city
FROM customers               cust
INNER JOIN orders            ord        ON ord.customer_id     = cust.customer_id
LEFT JOIN order_line_items   line_items ON line_items.order_id = ord.order_id
LEFT JOIN shipping_addresses addr       ON addr.order_id       = ord.order_id AND
                                           addr.address_type   = 'shipping'
WHERE ord.order_date >= '2026-07-01' AND
      cust.segment    = 'enterprise';

Drop ON to its own line#

Note what this costs: the ON conditions are now justified within each join instead of into one column spanning the whole FROM block.

sqlalign --stdout --on-placement own_line 13.sql

-- #13: multi-character aliases (mixed lengths)
SELECT cust.customer_id
     , cust.email
     , ord.order_id
     , ord.total
     , line_items.product_id
     , line_items.quantity
     , addr.city
FROM customers               cust
INNER JOIN orders            ord
   ON ord.customer_id     = cust.customer_id
LEFT JOIN order_line_items   line_items
   ON line_items.order_id = ord.order_id
LEFT JOIN shipping_addresses addr
   ON addr.order_id       = ord.order_id
  AND addr.address_type   = 'shipping'
WHERE ord.order_date >= '2026-07-01'
  AND cust.segment    = 'enterprise';

Lowercase everything#

sqlalign --stdout --keyword-case lower 13.sql

-- #13: multi-character aliases (mixed lengths)
select cust.customer_id
     , cust.email
     , ord.order_id
     , ord.total
     , line_items.product_id
     , line_items.quantity
     , addr.city
from customers               cust
inner join orders            ord        on ord.customer_id     = cust.customer_id
left join order_line_items   line_items on line_items.order_id = ord.order_id
left join shipping_addresses addr       on addr.order_id       = ord.order_id
                                       and addr.address_type   = 'shipping'
where ord.order_date >= '2026-07-01'
  and cust.segment    = 'enterprise';

Identifiers and string literals are untouched — the pass is AST-driven.

Format a dbt model#

--preset dbt is keyword_case = "lower" + trailing commas + no padding. Jinja survives because it is masked with same-width placeholders before parsing.

sqlalign --stdout --preset dbt orders.sql

select o.id,
       o.total,
       c.email
from {{ ref('orders') }} o
join {{ ref('customers') }} c on c.id = o.customer_id
where o.status = 'complete';

Give a long window function room#

--width moves the wrapping threshold. Same query, two widths:

sqlalign --stdout wide.sql            # default width 100

SELECT customer_id
     , SUM(total) OVER (PARTITION BY customer_id ORDER BY order_date
                        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS running_total
FROM orders;

sqlalign --stdout --width 200 wide.sql

SELECT customer_id
     , SUM(total) OVER (PARTITION BY customer_id ORDER BY order_date ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS running_total
FROM orders;

Lowering --width below the default often changes nothing, because the anchor + 60 floor keeps a deeply-indented construct readable regardless.

Space out a migration script#

sqlalign --stdout --blank-lines-between-statements 1 multi.sql

TRUNCATE TABLE staging_orders;

TRUNCATE TABLE staging_customers;

SELECT a
     , b
FROM t
WHERE a = 1
  AND b = 2;

SELECT c
FROM u;

With the flag unset, the two TRUNCATEs stay packed together and only the multi-line statements get air:

TRUNCATE TABLE staging_orders;
TRUNCATE TABLE staging_customers;
SELECT a
     , b
FROM t
WHERE a = 1
  AND b = 2;

SELECT c
FROM u;

Gate a repository in CI#

sqlalign --check --exclude 'vendor/*' --exclude '*.gen.sql' .

would reformat models/marts/rollup.sql
would reformat models/users.sql

Exit 1. Swap --check for --diff when you want the log to show the change rather than only the filename.