feat: sqlc.switch — compile-time query branches for dynamic ORDER BY/WHERE (discussion #364)

[celso-alexandre]

Summary

Implements sqlc.switch — compile-time expansion of dynamic ORDER BY/WHERE branches into one static, fully-validated query per branch.

Follows up on the proposal posted in #364 (comment), opened after @StevenACoffman indicated a PR would be welcome at this point.

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY sqlc.switch(@sort,
    sqlc.when('name_asc', 'authors.name ASC'),
    sqlc.when('recent',   'authors.created_at DESC, authors.id DESC'),
    sqlc.else(            'authors.id ASC'));

expands at sqlc generate time into ListAuthorsNameAsc, ListAuthorsRecent, and ListAuthorsElse — each a plain static query. No runtime CASE (planner/index friendly), no string interpolation (no injection surface), and every branch is re-parsed and validated against the catalog like any ordinary query.

Design

• Branch keys and SQL fragments are string literals — compile-time constants, never runtime input.
• Allowed only in clauses that don't change the result shape (WHERE, ORDER BY); rejected in the SELECT list.
• Recognized via the AST exactly like sqlc.arg/sqlc.slice; macro logic lives in a dedicated compiler file, with a thin wrapper in parseQueries. The core expansion has zero codegen changes, so all language backends benefit.
• Multiple sqlc.switch per query are allowed when they declare the same key set (e.g. the same choice driving a CTE pre-sort and the final ORDER BY); expansion stays linear, one function per key, with shared Params/Row structs in the Go backend.

Full design note: docs/proposals/sqlc-switch.md.

Commits

• feat(compiler): sqlc.switch for compile-time query branches — core expansion + validation
• feat(golang): multiple sqlc.switch per query + shared Params/Row structs
• fix(golang): reference shared struct fields as arg.Field in query body
• fix(sqlite): populate SelectStmt.SortClause during AST conversion — contributed by @fahmifan; SQLite ORDER BY terms were parsed but never propagated, which also blocked sqlc.switch (and sqlc.arg) recognition there
• fix(compiler): allow sqlite implicit rowid columns in strict ORDER BY validation — populating SortClause made strict_order_by apply to SQLite for the first time; without this, existing queries using ORDER BY rowid would start failing

Testing

• Golden end-to-end testdata for PostgreSQL, MySQL, and SQLite (internal/endtoend/testdata/sqlc_switch/, order_by_rowid/)
• Full suite (go test --tags=examples -timeout 20m ./...) green against live PostgreSQL 16 and MySQL 9
• Dropped the fork into a large production codebase (hundreds of generated queries) via a replace directive and regenerated: the only diffs were in queries that actually use sqlc.switch — everything else came out byte-identical

Disclosure

The initial implementation was AI-generated as a proof of concept to explore the design space; it has since been manually reviewed and tested (unit tests, golden tests across all three engines, and real use in a production project). Details in the discussion post.

Open questions

Carrying over from the discussion, happy to adjust any of these:

1. Naming: sqlc.switch/when/else — or something else?
2. Should sqlc.else be mandatory, or is "no match falls through" acceptable?
3. Scope for a first cut — ORDER BY only, or WHERE too?

🤖 Generated with Claude Code