Skip to content

feat: lay converted DuckDB SQL out one clause per line - #124

Merged
kvlonge merged 5 commits into
mainfrom
feat/sql-layout
Nov 6, 2026
Merged

kvlonge merged 5 commits into
mainfrom
feat/sql-layout

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Why

Converted DuckDB SQL printed as one long line, which reads badly in the playground and in convert output. This is a simple layout until a full formatter replaces it after launch.

Changes

  • layout_sql (sqlquack-duckdb) changes only the whitespace between tokens:
    • Each clause starts its own line: SELECT, FROM and JOINs, WHERE, GROUP BY, HAVING, QUALIFY, ORDER BY, LIMIT, and set operations.
    • Select items and common table expressions go one per line.
    • Nested queries are indented by depth.
    • A long CASE breaks at WHEN, ELSE and END, unless it sits inside a function call.
    • Statements and subqueries of up to 60 characters stay on one line.
  • On by default for convert's text output, the Python API (Conversion.sql) and the playground.
  • convert --compact, ConvertOptions(compact=True) and the playground's compact setting keep the single line.
  • --json's sql carries what the text output prints: laid out, or on one line with --compact.
  • The playground renders translated SQL in a <pre> that keeps its lines and scrolls sideways. That change is the website lane's 40efa91.
  • The convert, Python, docs index and quickstart pages show the laid-out output.

Verification

  • verify now checks every converted case:
    • The laid-out tokens equal the single-line tokens.
    • Laying out the result again changes nothing.
    • The laid-out SQL replays on DuckDB with the same column names, types and rows, or the same error. Clock-reading results compare names and types only.
  • Unit tests pin CTEs, joins, set operations, long and nested CASEs, and keywords inside strings.
  • A CLI test covers text, --json, --compact and --compact --json. A Python test covers compact=True against the command line.
  • Playground with the real engine at 1280 and 390 px: the statement keeps its lines, scrolls inside the panel, and the page keeps the viewport width.
  • make check-ci, make test-rust, make verify-recorded.

The Translate stage's SQL block uses white-space: pre with horizontal scroll,
so a clause-per-line layout shows as laid out. Diagnostics keep wrapping. A
stage is a grid item, so it takes min-width: 0; without it, a long line
widened the whole page.
Converted statements print each clause on its own line, select items and
common table expressions one per line, queries indented by depth and long
CASE expressions broken at WHEN, ELSE and END. Short ones stay on one line.
Only whitespace between tokens changes. convert --compact keeps the single
line, in --json too. Verify replays the laid-out SQL beside the single line
and fails a case whose results differ, whose tokens differ, or whose layout
is not idempotent.
The playground engine takes a compact setting like convert --compact, and
the docs pages that print convert output show the laid-out form.
# Conflicts:
#	tests/unit/python/src/sqlquack/api/main/test_convert.py

kvlonge commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Gate at ff9ff20 (main cce77ac merged in):

  • make check-ci: exit 0
  • make test-rust: every suite passed (exit 0)
  • make verify-recorded: 11800 cases, 7780 passed, 1031 diverged as expected, 2952 refused, 37 typed, 0 pending, 0 unproven, 0 failed; 220 of 220 equivalences and rules verified. Every converted case also replayed laid out (same tokens, idempotent, same names, types and rows). Translation baseline holds, 0 changes.
  • Website: engine rebuilt on this head, npm run test:engine 7/7, site build 0.
  • Playground with the real engine at 1280 and 390 px: the translated statement keeps its lines in a <pre> (white-space: pre, overflow-x: auto); at 390 the block scrolls (774 px content in a 340 px box) and the page stays 390 px wide.

kvlonge added a commit that referenced this pull request Nov 6, 2026
@kvlonge
kvlonge merged commit ff9ff20 into main Nov 6, 2026
1 of 2 checks passed
@kvlonge
kvlonge deleted the feat/sql-layout branch November 9, 2026 21:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant