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#

There is no stdin mode and - is not special, but /dev/stdin works as a path — with the caveat that config discovery then walks up from /dev, not your repo, so pair it with --config.

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 · exclude · format_dollar_bodies · keyword_case · neq_style · on_placement · preset · protect_templating · river_gutter · select_indent · select_placement · table_alias_style · width

--dialect and --line-ending are the only settings 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_constraints', 'column_types', 'join_conditions', 'operators']

--no-align is the shorthand for switching all six 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.