Comma style

commaStyle says where the comma sits once a list has broken across lines: trailing, at the end of each item's line, or leading, at the head of the next one. A list that fits on one line is a, b, c under either.

Default: trailing. It is how SQL is written in vendor documentation and in most of the SQL already written, so it is the value that changes nothing a reader expects.

leading is the style many dbt projects use. The comma is the first thing on the line, so adding or removing the last column touches one line instead of two, and a missing comma shows up as a hole in the column rather than hiding at the end of the line above.

A select list, both styles

select customer_id, order_total, created_at, updated_at, status_code from orders

select
    customer_id,
    order_total,
    created_at,
    updated_at,
    status_code
from orders

select customer_id, order_total, created_at, updated_at, status_code from orders

select
      customer_id
    , order_total
    , created_at
    , updated_at
    , status_code
from orders

The first item is indented by the comma's width. Under leading every item's text begins in the same column and the commas stand in the margin to its left. Without that pad the first item, the one line a reader scans for, would sit two columns left of its siblings. The pad is withheld where there is no column to join: a packed list, or a first item that rides its keyword's line.

The style applies to every comma-separated list the grammar declares, rather than to a list of places it was taught: select items, group by and order by, values rows, column definitions, function arguments, and the CTEs of a with, which is where dbt projects meet it. A comment stays on the line the author wrote it on under either style.

A CTE list

with alpha as (select customer_id, order_total from orders), beta as (select customer_id, sum(order_total) as t from orders group by customer_id) select * from alpha join beta using (customer_id)

with
      alpha as (
          select customer_id, order_total
          from orders
      )

    , beta as (
        select customer_id, sum(order_total) as t
        from orders
        group by customer_id
    )
select *
from alpha
join beta using (customer_id)

The comma before beta is what the style is for: a CTE can be added, removed or reordered by touching one line, and blankLineBetweenCtes puts the blank line between the closing paren and that comma. The first CTE carries the pad into its whole block, body and closing paren included, because the pad moves the piece rather than its first word. The two CTE names sit in one column, which is the point; the two bodies sit two columns apart, which is the price.