Option Parenthèses sur une nouvelle ligne

Parentheses on new line controls where an opening parenthesis goes when it starts an indented block: at the end of the line that introduces it (the default) or on a line of its own. This page shows exactly which parentheses move, with real output for both settings.

What the option does

When the formatter opens a block in parentheses, such as a subquery after IN, it indents the contents one level and puts the closing parenthesis on its own line. The only question left is where the opening parenthesis goes:

• Off (default): it stays at the end of the introducing line, as in WHERE id IN (.
• On: the introducing line ends with the keyword (WHERE id IN), and the parenthesis gets its own line, at the same indentation as the line it belongs to.

The contents and the closing parenthesis are laid out the same way in both modes. Only one character moves.

Possible values and default

Subquery after IN

The most common case. Compare the line after WHERE id IN in the two outputs:

select name, email from customers where id in (select customer_id from orders where total > 500 and status = 'PAID')

SELECT name,
    email
FROM customers
WHERE id IN (
    SELECT customer_id
    FROM orders
    WHERE total > 500
    AND status = 'PAID'
)

SELECT name,
    email
FROM customers
WHERE id IN
(
    SELECT customer_id
    FROM orders
    WHERE total > 500
    AND status = 'PAID'
)

With the option on, the opening and closing parentheses sit in the same column, one above the other, with the subquery between them.

CTEs and derived tables

The body of a common table expression and a derived table in FROM behave the same way. The WITH recent AS line and the FROM line lose their parenthesis, which moves to the next line:

with recent as (select customer_id, sum(total) as total from orders where created_at >= current_date - 90 group by customer_id) select x.region, sum(x.total) as region_total from (select t.region, r.total from recent r join territories t on t.customer_id = r.customer_id) x group by x.region

WITH recent AS (
    SELECT customer_id,
        SUM(total) AS total
    FROM orders
    WHERE created_at >= CURRENT_DATE - 90
    GROUP BY customer_id
)
SELECT x.region,
    SUM(x.total) AS region_total
FROM (
    SELECT t.region,
        r.total
    FROM recent r
        JOIN territories t
            ON  t.customer_id = r.customer_id
) x
GROUP BY x.region

WITH recent AS
(
    SELECT customer_id,
        SUM(total) AS total
    FROM orders
    WHERE created_at >= CURRENT_DATE - 90
    GROUP BY customer_id
)
SELECT x.region,
    SUM(x.total) AS region_total
FROM
(
    SELECT t.region,
        r.total
    FROM recent r
        JOIN territories t
            ON  t.customer_id = r.customer_id
) x
GROUP BY x.region

The same happens to the column list and the VALUES list of an INSERT and to the column definitions of a CREATE TABLE, which the formatter also lays out as indented blocks. A single-column list such as INSERT INTO t (id) stays inline and does not move.

Function calls and value lists

The option looks at the layout, not at the kind of parenthesis. Any parenthesis that opens an indented block moves, and any parenthesis that stays inline does not. The one exception is a window specification: OVER ( always stays on the line of its function, in both modes.

select id, count(*) as items, coalesce(discount_code, 'NONE') as discount, (select max(shipped_at) from shipments s where s.order_id = o.id) as last_shipment from orders o where status in ('PAID', 'SHIPPED') group by id, discount_code

SELECT id,
    COUNT(*) AS items,
    COALESCE(
        discount_code,
        'NONE'
    ) AS discount,
    (
        SELECT
            MAX(shipped_at)
        FROM shipments s
        WHERE s.order_id = o.id
    ) AS last_shipment
FROM orders o
WHERE status IN (
    'PAID',
    'SHIPPED'
)
GROUP BY id,
    discount_code

SELECT id,
    COUNT(*) AS items,
    COALESCE
    (
        discount_code,
        'NONE'
    ) AS discount,
    (
        SELECT
            MAX(shipped_at)
        FROM shipments s
        WHERE s.order_id = o.id
    ) AS last_shipment
FROM orders o
WHERE status IN
(
    'PAID',
    'SHIPPED'
)
GROUP BY id,
    discount_code

In this example:

• COUNT(*) and MAX(shipped_at) stay on one line, so their parentheses are not touched.
• COALESCE is split one argument per line, so with the option on its parenthesis moves to the next line, indented like the function name.
• The value list IN ('PAID', 'SHIPPED') is also split one value per line, and its parenthesis moves exactly like a subquery's.
• The scalar subquery in the select list already starts with its parenthesis on a line of its own, so both outputs are identical there.

When to turn it on

The two settings are the SQL equivalent of the brace-placement debate in C-like languages.

Keep it off for compact output that looks like most SQL in documentation and in published style guides, where WITH name AS ( and IN ( are the usual way to write it. Each block costs one line less, and the keyword that opens the block stays visually attached to it. The closing parenthesis lines up with the start of the line that opened the block, which is enough to find the pair in most queries.

Turn it on when you work with long, deeply nested queries and want to match parentheses by eye. Because the opening and closing parentheses share a column, an editor's indent guides or a quick vertical scan show where each block starts and ends. Some teams also find that a keyword alone at the end of a line (IN, AS, FROM) signals clearly that a block follows.

The costs are an extra line per block, which adds up in queries with many CTEs, and function calls that read a little unusually, with COALESCE on one line and its parenthesis on the next. If most of your long blocks are CTEs and subqueries, that trade can be worth it; if most of them are split function calls, the default usually reads better.

Related options

The indentation inside each block comes from indent spaces, and does not change with this option. Moving the parenthesis makes no line longer, so it never adds wrapping under maximum columns. Comma placement and keyword case apply to the contents of the block as usual. For broader advice on structuring nested queries, CTEs and subqueries before you format them, see formatting complex queries, and try both settings on your own SQL in the formatter: it is a one-click change.