Add sqlc fmt: a comment-preserving SQL formatter, SQLite first

[kyleconroy]

sqlc fmt formats the query files referenced by the configuration: each statement is parsed with the engine's parser and printed back from the AST in a canonical form, with its comments kept where they were written. Files are rewritten in place; --diff prints the changes to stdout instead.

-- name: PickyQuery :many          -- name: PickyQuery :many
SELECT id, -- the primary key      SELECT
       name,                    →    id, -- the primary key
       -- computed downstream        name,
       bio                           -- computed downstream
FROM authors                         bio
-- soft-deleted rows filtered      FROM authors
WHERE bio IS NOT NULL              -- soft-deleted rows filtered
  AND id > ?;                      WHERE bio IS NOT NULL AND id > ?;

Engine support

SQLite only for now. Comments cannot be reprinted without parser support, so an engine joins fmt when its parser surfaces the comments its lexer already scans. meyer does this as of v0.1.2 (sqlc-dev/meyer#6): ParseFile returns statements plus the lexer's trivia from a single pass. Other engines' query files are left unchanged, with a one-line stderr notice per engine; each joins by implementing ParseFile (meyer is the template — oliphant's Scan already emits comment tokens, marino needs a small scanner change) and adding a case to newQueryFormatter.

Architecture

Two layers, borrowed from the formatters that got this right:

• Layout is a Wadler-style document renderer (the model behind Prettier and ruff) in internal/sql/ast/print.go: Format methods emit text plus layout tokens (line, softline, group, indent), and the renderer lays each group out flat when it fits within 80 columns, breaking at clause boundaries — then lists, AND/OR chains, and parenthesized regions one level deeper — when it doesn't. ast.Format still renders on a single line for existing callers (expander, tests).
• Comments follow the gofmt/dave-dst model: the parser carries them beside the tree, ast.AttachComments classifies each one once (trailing vs leading, by source position and line) against a dry run of the printer itself, and from then on positions are never consulted — the printer emits by node identity, which also means a future AST-rewriting tool prints comments correctly on edited or synthetic trees. A line comment measures as infinitely wide in the doc IR, so it forces its enclosing groups to break: commented statements format instead of collapsing.

Safety

Comments are never deleted and SQL is never changed, enforced rather than assumed:

• Per statement: the output must reparse as a single statement whose comments equal the input's (multiset) and whose reprint reproduces the output byte-for-byte (fixed point); otherwise the statement is left exactly as written.
• Per file: any result that would alter the file's comments is refused and reported as a formatter bug.
• Statements using syntax the formatter can't prove it preserves fall back verbatim.

Along the way this surfaced and fixed two real MySQL converter bugs (dolphin mapped LIKE to the ILIKE kind and dropped NOT from NOT LIKE), added SortBy nodes for MySQL ORDER BY (previously invisible to formatting), and taught A_Expr to recognize pre-rewrite @name parameters so they print as @name, not @ name.

Testing

• Endtoend fmt cases (testdata/fmt/{sqlite,postgresql,mysql}) pin the formatted output, the comment placements, and the unsupported-engine skip behavior, run through the real CLI via exec.json.
• The full --tags=examples suite passes with live PostgreSQL and MySQL.
• Formatting is idempotent (fmt after fmt produces no diff) and formatted files still compile.

Docs: docs/howto/fmt.md (example verified against real output), CLI reference entry, and internal/sql/ast/CLAUDE.md notes on the doc IR and comment machinery.

🤖 Generated with Claude Code

https://claude.ai/code/session_018MTvpHqNMadH12pTtsgUq2

---

Generated by Claude Code

[kyleconroy]

The ast/print.go needs to be moved to a separate ast/printer package. Can we easily move tracked buffer to that package?

[kyleconroy]

On the review-body question — moving ast/print.go into a separate ast/printer package:

Done in half: the document renderer (the Wadler engine — tokens, groups, indentation, width fitting) now lives in internal/sql/ast/printer as printer.Buffer, with no knowledge of SQL or the AST.

TrackedBuffer itself can't easily move. Every node's Format method is typed Format(buf *ast.TrackedBuffer, d format.Dialect), so a printer.TrackedBuffer that dispatches to nodes would need printer → ast while ast → printer for the node signatures — an import cycle. Breaking it would mean either an interface with the union of everything Format methods call (join/joinComma/condition/boundary plus all the writer methods) or touching the signature of every node file for no behavioral gain.

So the split is by knowledge instead: printer.Buffer is the pure renderer, and TrackedBuffer (still in ast, now just embedding a *printer.Buffer) keeps only the AST-facing layer — node dispatch, list joins, and comment emission. print.go went from ~570 lines to ~270, all of them about the AST.

Also in the latest push: the line width is gone entirely. fmt prints at effectively unlimited width and instead keeps the line breaks the author wrote — AttachComments records which clause/list boundaries had a break in the source, and the printer re-emits them — so one-line statements stay on one line and multi-line ones keep their shape, gofmt-style. Docs, help text, and the endtoend golden are updated, and the full --tags=examples suite is green.

---

Generated by Claude Code