Add testcheck to verify analyze cases against a real database, starting with ClickHouse

[kyleconroy]

Summary

Adds internal/testcheck, a nested, dependency-free Go module that verifies the analyze cases under internal/endtoend/testdata against a real database, and then fixes everything it found wrong in sqlc's ClickHouse analysis. All six ClickHouse analyze cases now match what ClickHouse itself reports, byte for byte.

testcheck generates nothing: each engine package finds every analyze_*/<engine> case, loads its schema.sql and optional fixture.sql into the database, runs query.sql there, prints what the database reports in the JSON shape sqlc analyze prints, and compares it with the case's committed output.json.

cd internal/testcheck
go run ./cmd/testcheck install clickhouse   # download the pinned clickhouse binary once
go run ./cmd/testcheck check                # or: go test ./...

ClickHouse package

• Needs no server. Each case runs in an ephemeral clickhouse local process. The pinned release (25.8.2.29) is downloaded per platform into the user cache directory and verified against a SHA-512 table; CLICKHOUSE overrides the lookup.
• Column types come from the executed query's result header. Provenance comes from EXPLAIN QUERY TREE, followed through subqueries, CTEs and unions. Parameters, which ClickHouse never sees, are substituted with ordinal-carrying sentinel constants that the query tree describes by the operand they are compared with; INSERT ... VALUES parameters map onto DESCRIBE TABLE.

sqlc analyze output

sqlc analyze prints each column's type as a call expression instead of data_type, not_null and is_array: a name applied to args, each carrying an optional label and exactly one of type, int, bool or string, with nullable set at whatever depth it applies. docs/howto/analyze.md is updated.

{"name": "map", "args": [
  {"type": {"name": "string"}},
  {"type": {"name": "uint8", "nullable": true}}]}

Every analyze case's expected output is renamed from stdout.txt to output.json, which the harness now reads first, and regenerated. New ClickHouse cases analyze_types, analyze_expressions, analyze_subqueries and analyze_exec come with a fixture.sql next to the schema, and analyze_basic and analyze_params gain fixtures.

What testcheck found, and the fixes

• Types lost their arguments and nesting. The ClickHouse converter now keeps a column's full spelling in the type name's Spelling, the schema stores it as the attribute's declared type, and the analysis core writes a TypeExpr for every column and parameter from it. Array(Nullable(String)), Array(Array(UInt8)), LowCardinality(Nullable(String)), Map(String, Nullable(UInt8)), Tuple(lat Float64, lon Float64), Enum8('active' = 1, ...), Decimal(10, 2), DateTime64(3, 'UTC') and FixedString(4) all survive.
• Expression columns had no type. A ClickHouse function seed of 581 signatures replaces the single count() entry, with "$n" naming the type of the nth argument and never_null for results that stay non-null. The dialect declares that functions propagate nullability, that comparisons yield UInt8 while true is Bool, that LIMIT counts are UInt64, and that an unconstrained placeholder is Nothing. The analyzer scores overloads instead of taking the first of the right arity, and COALESCE is now null only when every argument is.
• Parameters went missing. ClickHouse joins the preprocessed engines, so sqlc.arg() and sqlc.narg() work with ? binding; the analyzer types ORDER BY, LIMIT and OFFSET, follows IN (SELECT ...) into the subquery, and names a placeholder compared with a function call after the function. The converter's positions are now zero-based, which is also what made star expansion work.
• Scalar subqueries were ?column? typed bool. The converter treats a subquery in value position as a value rather than EXISTS, and captures aliases on every expression node kind.

Beyond the four: unaliased expression columns get ClickHouse's own names (sum(amount), plus(id, 1)), WITH elements are converted as the parser produces them so CTEs resolve, coalesce/ifNull convert to COALESCE, and a dialect that names the second id of a join e.id says so in its seed. The CTE and SELECT * join queries that had to be left out earlier are back in the subqueries case.

Tests

go test ./... at the root passes apart from the database-backed schema tests that need MySQL. The ClickHouse parse golden changed by one position and one column name, both correct. The testcheck module is not wired into CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y6XkyWnx7iJFEb8q3AnYps