Skip to main content

Preserve-Breaks Tiers

The formatter automatically chooses between three layout tiers based on how much fits within maxLineWidth. Each clause decides independently — simple clauses stay compact, complex ones expand.

Two settings control the behavior:

  • maxLineWidth — wider values keep more clause bodies inline (Tier 2), narrower values push them to indent (Tier 3)
  • shortStatementsOneLine — when true, enables Tier 1 (entire statement on one line when it fits)

When preserveBreaks is enabled, the user's original line breaks can override the tier decision — a clause body that would fit inline stays expanded if the user wrote items on separate lines.

Tier 1 — Short: everything on one line​

When the entire statement fits within maxLineWidth, it stays flat.

select id, name from users where active
select id, name from users where active

Tier 2 — Medium: clause-per-line, bodies inline​

When the statement doesn't fit on one line but each clause body fits on its keyword line, bodies stay inline with keywords.

select customer_id, name, email from customers where status = 'active'
select customer_id, name, email
from customers
where status = 'active'

Tier 2 with multiple clauses​

select customer_id, name, email from customers where status = 'active' order by name
select customer_id, name, email
from customers
where status = 'active'
order by name

Tier 3 — Long: clause bodies indented below​

When a clause body exceeds maxLineWidth from the keyword position, it breaks to a new indented line.

select customer_id, customer_name, customer_email, customer_phone, customer_address from customers where status = 'active' and region = 'US'
select
    customer_id, customer_name, customer_email,
    customer_phone, customer_address
from customers
where status = 'active' and region = 'US'

Mixed tiers in one statement​

Each clause decides independently. Simple clauses stay Tier 2, complex ones go Tier 3.

select customer_id, name from customers where status = 'active' and region = 'US' and created_at > '2024-01-01' order by name
select customer_id, name
from customers
where
    status = 'active'
    and region = 'US'
    and created_at > '2024-01-01'
order by name