Skip to content

Commit 002e9f6

Browse files
EliSauderCopilot
andcommitted
docs: explain dialect typing gaps and MSSQL conversion boundaries
Compare all seven seeded engines' common-type semantics and explain why SQL Server settings must not be copied to them. Clarify converter dispatch and the metadata needed to replace its recognition maps. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 64e0b37 commit 002e9f6

3 files changed

Lines changed: 92 additions & 6 deletions

File tree

‎docs/guides/development.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,45 @@ Install `sqlc-gen-json` to avoid test failure.
1414
go build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json
1515
```
1616

17+
## Dialect type-combination policies
18+
19+
The analysis core owns traversal, column names, catalog resolution and
20+
nullability propagation. Database-specific common-type algorithms belong to
21+
the engine: SQL Server's precedence, length and decimal rules live in
22+
`internal/engine/mssql/typepolicy`, independent of its parser.
23+
24+
`set_operations.strategy` in a dialect's `dialect.json` explicitly selects an
25+
implemented policy (currently only `"mssql"`). The remaining fields configure
26+
that SQL Server policy; they are not a universal coercion language. Seeds
27+
reject missing or unsupported strategies rather than accidentally applying
28+
SQL Server's formula to another engine. The selector is serialized in the
29+
catalog, so cache restores use the same policy as freshly seeded catalogs.
30+
Omitting `set_operations` preserves the old inference fallback.
31+
32+
To support another dialect, add its engine-owned policy and explicit
33+
dispatch/seed validation, then opt in its dialect settings and add end-to-end
34+
cases. Do not copy SQL Server's settings into other seeds. Some engines need
35+
the entire candidate list, cast context, domain information or recursive
36+
structured types; extend the policy inputs/orchestration for those semantics
37+
rather than forcing them through pairwise precedence. Set operations and
38+
`CASE`-like expressions need not share one algorithm. The current cross-engine
39+
gaps and database references are in
40+
[`analyze`](../howto/analyze.md#common-type-inference).
41+
42+
SQL Server's converter also performs syntax/semantic lowering before seeded
43+
function lookup. `convertMethodCall` handles receivers, static `type::method`
44+
syntax and XML `value`'s type argument; `convertAlternatives` produces the
45+
shared AST nodes that combine candidates and propagate nullability. Ordinary
46+
function calls retain `OVER` rather than being rewritten as alternatives.
47+
JSONL signatures already describe the lowered calls' argument and return
48+
types, but cannot currently request these AST transformations. The method
49+
recognition map must stay synchronized with the leading-dot signatures.
50+
The datepart recognition map distinguishes bare keyword arguments from column
51+
references; `ident_args` in the dialect settings applies to *type* arguments,
52+
not function arguments. Moving these maps into seed metadata would require
53+
new converter metadata and a way to consume it before analysis, not merely
54+
additional function signatures.
55+
1756
## Running Tests
1857

1958
```

‎docs/howto/analyze.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,45 @@ engine's own analysis path, so the two can report a type differently — most
1919
visibly, `analyze` reports type names as the catalog stores them, in lower
2020
case.
2121

22+
## Common-type inference
23+
24+
The shared core does not give every database the same coercion rules. SQL
25+
Server explicitly enables its type-combination policy for set operations and
26+
alternative-valued expressions such as `CASE`, `COALESCE`, `GREATEST`, `LEAST`
27+
and `CHOOSE`. `ISNULL` instead keeps its first typed argument's type; both
28+
arguments must be nullable for its result to be nullable.
29+
30+
Other dialects currently keep the existing core fallback: a set-operation
31+
column takes its type from the left branch, and an alternative-valued
32+
expression takes the first typed candidate. **This is incomplete static
33+
inference, not those databases' common-type semantics.** It does not change
34+
their normal `generate` paths.
35+
36+
The database rules differ in ways that need separate policies:
37+
38+
| Dialect | Database behavior and current core gap |
39+
| --- | --- |
40+
| SQL Server | Uses type precedence and combines decimal scale/integer digits with a precision limit of 38. The enabled policy models these rules, but is not a general implicit-cast validator. |
41+
| PostgreSQL | Selects common types using categories, implicit casts, preferred types, unknown literals and domains. Modifiers survive only when the candidates have the same type and modifier: `numeric(5,2) UNION numeric(8,4)` has unconstrained `numeric`, not SQL Server-style decimal widening. |
42+
| SQLite | Values are dynamically typed; compound-view/subquery affinity can come from any constituent `SELECT`. Declared decimal precision and string length do not impose SQL Server-style limits. |
43+
| MySQL | Aggregates types and lengths across set-operation branches; alternative expressions also need signed/unsigned, numeric, binary/string, temporal and NULL-literal rules. |
44+
| DuckDB | Uses combination casting for set operations, including casts not allowed by ordinary implicit casting. Integer widths and nested types need more than a precedence list. |
45+
| ClickHouse | Computes compatible supertypes, including `Nullable`, signed/unsigned widths and nested types; decimal precision can reach 76. Some combinations have no compatible supertype. |
46+
| GoogleSQL (Spanner) | Intersects supertype sets, distinguishes exact from inexact numeric inputs, and has separate literal and structured-type rules. Its type inventory is not identical to BigQuery's. |
47+
48+
These are reviewed database semantics, not a claim that sqlc has implemented
49+
or live-tested the missing policies. See the upstream references:
50+
[SQL Server](https://learn.microsoft.com/en-us/sql/t-sql/data-types/precision-scale-and-length-transact-sql),
51+
[PostgreSQL common types](https://www.postgresql.org/docs/18/typeconv-union-case.html)
52+
and [modifiers](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/parser/parse_coerce.c),
53+
[SQLite](https://www.sqlite.org/datatype3.html#column_affinity_for_compound_views),
54+
[MySQL set operations](https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/set-operations.html)
55+
and [alternative expressions](https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/flow-control-functions.html),
56+
[DuckDB](https://duckdb.org/docs/2.0/sql/data_types/typecasting),
57+
[ClickHouse UNION](https://clickhouse.com/docs/reference/statements/select/union)
58+
and [decimals](https://clickhouse.com/docs/reference/data-types/decimal),
59+
and [Spanner](https://docs.cloud.google.com/spanner/docs/reference/standard-sql/conversion_rules).
60+
2261
## Usage
2362

2463
```sh

‎internal/engine/mssql/convert.go‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,10 @@ func (c *cc) convertScalarExpression(expr tsql.ScalarExpression) ast.Node {
547547
case *tsql.ParenthesisExpression:
548548
return c.convertScalarExpression(e.Expression)
549549
case *tsql.FunctionCall:
550+
// Methods need receiver/type syntax lowered before signature lookup;
551+
// alternatives need candidate-dependent typing and nullability.
552+
// Keep window calls on the ordinary path so an alternative rewrite
553+
// cannot discard their OVER clause.
550554
if out := c.convertMethodCall(e); out != nil {
551555
return out
552556
}
@@ -684,10 +688,10 @@ func (c *cc) convertScalarExpression(expr tsql.ScalarExpression) ast.Node {
684688
}
685689

686690
// convertAlternatives converts the functions that yield one of their
687-
// arguments, which SQL Server types as the type their candidates combine
688-
// to, as it does CASE: GREATEST and LEAST, and CHOOSE, which is the CASE
689-
// over its index it is defined as. ISNULL, NULL only when both arguments
690-
// are, as COALESCE is, keeps its first argument's type.
691+
// arguments: GREATEST/LEAST combine their candidate types, and CHOOSE becomes
692+
// the CASE over its index. ISNULL keeps its first typed argument's type and
693+
// is NULL only when both arguments are. Fixed JSONL function signatures do
694+
// not describe these AST rewrites or the candidates' combined nullability.
691695
func (c *cc) convertAlternatives(e *tsql.FunctionCall) ast.Node {
692696
args := &ast.List{}
693697
for _, p := range e.Parameters {
@@ -790,7 +794,9 @@ type namedParam struct {
790794
// typeMethods are the methods of xml, geography, geometry and hierarchyid
791795
// a query calls on a value, as doc.exist('/a') or node.GetLevel() do. A
792796
// call to one is seeded as ".name" taking the value first, which tells it
793-
// from a function in a schema, as dbo.f(), the parser sees alike.
797+
// from a function in a schema, as dbo.f(), the parser sees alike. This map
798+
// recognizes receiver syntax before catalog lookup and must stay in sync
799+
// with the leading-dot JSONL signatures.
794800
var typeMethods = map[string]bool{
795801
"exist": true,
796802
"getlevel": true, "tostring": true, "getancestor": true, "getdescendant": true,
@@ -894,7 +900,9 @@ func (c *cc) convertFunctionCall(n *tsql.FunctionCall) *ast.FuncCall {
894900
return fc
895901
}
896902

897-
// datepartFunctions are the functions whose first argument is a datepart.
903+
// datepartFunctions take a bare keyword which the parser sees as a column.
904+
// JSONL signatures describe its string type, not this syntax; dialect
905+
// ident_args describes type arguments, not function arguments.
898906
var datepartFunctions = map[string]bool{
899907
"dateadd": true,
900908
"datediff": true,

0 commit comments

Comments
 (0)