feat: add sqlc.jsonb_build_object(...) for inline JSON-shaped results

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: m-ali-akbay

docs/howto/embedding.md

@@ -58,4 +58,96 @@ type ScoreAndTestsRow struct {
 	Student   Student
 	TestScore TestScore
 }
-```
+```
+
+#### Nested JSON objects and arrays
+
+`sqlc.jsonb_build_object."Name"(key, value, key, value, ...)` builds a named
+Go struct from an inline JSON shape — a typed wrapper around Postgres's
+`jsonb_build_object`, so keys must be string literals. This is most useful
+for pulling a one-to-many relationship into a single query as a slice
+field, instead of running a separate query per parent row. It's **pgx/v5
+only**: `sqlc generate` fails with a clear error for any other
+`sql_package`.
+
+`"Name"` is required and must be a double-quoted identifier in that
+position, not an argument — Postgres parses this as a 3-part qualified
+function name (`catalog.schema.name`), and sqlc reads the struct name
+directly off of it.
+
+```sql
+CREATE TABLE authors (
+  id   bigserial PRIMARY KEY,
+  name text NOT NULL
+);
+
+CREATE TABLE books (
+  id        bigserial PRIMARY KEY,
+  author_id bigint NOT NULL REFERENCES authors (id),
+  title     text NOT NULL
+);
+```
+
+```sql
+-- name: GetAuthors :many
+SELECT
+  sqlc.embed(authors),
+  ARRAY(
+    SELECT sqlc.jsonb_build_object."Book"('id', books.id, 'title', books.title)
+    FROM books
+    WHERE books.author_id = authors.id
+  ) AS books
+FROM authors;
+```
+
+```go
+type GetAuthorsRow struct {
+	Author Author
+	Books  []Book
+}
+
+type Book struct {
+	ID    int64  `json:"id"`
+	Title string `json:"title"`
+}
+```
+
+No custom `Scan`/`Value` methods, no wrapper type — `Books` is a plain
+`[]Book`; pgx v5 decodes the `jsonb[]` column into it directly. A lone
+`sqlc.jsonb_build_object."Name"(...)` (not wrapped in `ARRAY(...)`) works
+the same way and produces a plain struct field instead of a slice:
+
+```sql
+-- name: GetAuthorSummary :one
+SELECT sqlc.jsonb_build_object."AuthorSummary"('name', name) AS summary FROM authors LIMIT 1;
+```
+
+```go
+type GetAuthorSummaryRow struct {
+	Summary AuthorSummary
+}
+```
+
+Two queries that use the same explicit name reuse the same Go type, as long
+as their shapes match (this works even mixing scalar and `ARRAY(...)` uses
+of the same name). A shape mismatch, or a name that collides with an
+existing model/enum type, fails generation with an error instead of
+emitting Go code that won't compile.
+
+##### Overriding generated names
+
+The struct name and individual field names can be overridden via the
+`rename` option:
+
+```json
+{
+  "rename": {
+    "Book": "BookSummary",
+    "Book.id": "BookID"
+  }
+}
+```
+
+`"Book"` renames the type; `"Book.id"` renames just the `id` field within
+it, without affecting other types that also have an `id` key. Use the plain
+key (`"id"`) instead to rename that field everywhere.

internal/cmd/shim.go

@@ -183,6 +183,7 @@ func pluginQueryColumn(c *compiler.Column) *plugin.Column {
 		IsNamedParam: c.IsNamedParam,
 		IsFuncCall:   c.IsFuncCall,
 		IsSqlcSlice:  c.IsSqlcSlice,
+		JsonName:     c.JSONName,
 	}
 
 	if c.Type != nil {
@@ -213,6 +214,10 @@ func pluginQueryColumn(c *compiler.Column) *plugin.Column {
 		}
 	}
 
+	for _, field := range c.JSONFields {
+		out.JsonFields = append(out.JsonFields, pluginQueryColumn(field))
+	}
+
 	return out
 }
 

internal/codegen/golang/gen.go

@@ -212,6 +212,10 @@ func generate(req *plugin.GenerateRequest, options *opts.Options, enums []Enum,
 		return nil, errors.New(":batch* commands are only supported by pgx")
 	}
 
+	if usesJSON(queries) && tctx.SQLDriver != opts.SQLDriverPGXV5 {
+		return nil, errors.New("sqlc.jsonb_build_object(...) is only supported by pgx/v5")
+	}
+
 	funcMap := template.FuncMap{
 		"lowerTitle": sdk.LowerTitle,
 		"comment":    sdk.DoubleSlashComment,
@@ -356,6 +360,15 @@ func usesBatch(queries []Query) bool {
 	return false
 }
 
+func usesJSON(queries []Query) bool {
+	for _, q := range queries {
+		if len(q.JSONTypes) > 0 {
+			return true
+		}
+	}
+	return false
+}
+
 func checkNoTimesForMySQLCopyFrom(queries []Query) error {
 	for _, q := range queries {
 		if q.Cmd != metadata.CmdCopyFrom {

internal/codegen/golang/imports.go

@@ -350,6 +350,14 @@ func (i *importer) queryImports(filename string) fileImports {
 					return true
 				}
 			}
+			// JSONTypes live outside Ret/Arg, so check them separately.
+			for _, t := range q.JSONTypes {
+				for _, f := range t.Fields {
+					if hasPrefixIgnoringSliceAndPointerPrefix(f.Type, name) {
+						return true
+					}
+				}
+			}
 		}
 		return false
 	})

internal/codegen/golang/json_type.go

@@ -0,0 +1,105 @@
+package golang
+
+import (
+	"fmt"
+
+	"github.com/sqlc-dev/sqlc/internal/codegen/golang/opts"
+	"github.com/sqlc-dev/sqlc/internal/plugin"
+)
+
+// JSONType is a plain Go struct synthesized from an
+// sqlc.jsonb_build_object."Name"(...) call. No Scan/Value methods are
+// generated: pgx v5 decodes a literal ARRAY(SELECT jsonb_build_object(...)
+// FROM ...) directly into a bare []JSONType, and a scalar
+// jsonb_build_object(...) directly into a bare JSONType, via reflection.
+type JSONType struct {
+	Name   string
+	Fields []Field
+}
+
+// newGoJSONColumn resolves the Go type for an sqlc.jsonb_build_object."Name"(...)
+// column ([]Name for array results, Name otherwise) and collects the
+// JSONType struct declaration(s) it needs, including any nested calls.
+// col.JsonName is used as-is, letting two queries share one Go type by
+// using the same name (see internJSONTypes).
+func newGoJSONColumn(req *plugin.GenerateRequest, options *opts.Options, col *plugin.Column, models modelTypeSet, qualifier string) (string, []JSONType) {
+	structName := StructName(col.JsonName, options)
+
+	var fields []Field
+	var types []JSONType
+	for _, f := range col.JsonFields {
+		tags := map[string]string{"json": f.Name}
+		addExtraGoStructTags(tags, req, options, f)
+
+		var fieldType string
+		if len(f.JsonFields) > 0 {
+			var nested []JSONType
+			fieldType, nested = newGoJSONColumn(req, options, f, models, qualifier)
+			types = append(types, nested...)
+		} else {
+			fieldType = qualifyType(goType(req, options, f), models, qualifier)
+		}
+
+		// A namespaced rename ("Name.fieldKey") takes precedence over
+		// StructName's own global rename lookup, so the same JSON key can
+		// be renamed differently in different synthesized structs.
+		fieldName, ok := options.Rename[col.JsonName+"."+f.Name]
+		if !ok {
+			fieldName = StructName(f.Name, options)
+		}
+
+		fields = append(fields, Field{
+			Name:   fieldName,
+			DBName: f.Name,
+			Type:   fieldType,
+			Tags:   tags,
+			Column: f,
+		})
+	}
+
+	types = append(types, JSONType{Name: structName, Fields: fields})
+
+	if col.IsArray {
+		return "[]" + structName, types
+	}
+	return structName, types
+}
+
+// internJSONTypes deduplicates types against seen (a package-wide map keyed
+// by name, mutated in place), returning only the ones that still need to be
+// emitted. A name already used by a model/enum, or by an earlier JSONType
+// with different fields, is an error rather than a silent duplicate
+// declaration or a wrong-shape struct. Scalar and array uses of the same
+// name are compatible (the struct itself doesn't change; only the
+// referencing field gains a [] prefix), so they intern together.
+func internJSONTypes(seen map[string]JSONType, models modelTypeSet, types []JSONType) ([]JSONType, error) {
+	var toEmit []JSONType
+	for _, t := range types {
+		if _, ok := models[t.Name]; ok {
+			return nil, fmt.Errorf("sqlc.jsonb_build_object.%q(...) collides with an existing model or enum type; give it a different name", t.Name)
+		}
+		prev, ok := seen[t.Name]
+		if !ok {
+			seen[t.Name] = t
+			toEmit = append(toEmit, t)
+			continue
+		}
+		if !sameJSONShape(prev, t) {
+			return nil, fmt.Errorf("sqlc.jsonb_build_object.%q(...) is used with conflicting shapes across queries; give one of them a different name", t.Name)
+		}
+	}
+	return toEmit, nil
+}
+
+func sameJSONShape(a, b JSONType) bool {
+	if len(a.Fields) != len(b.Fields) {
+		return false
+	}
+	for i, f := range a.Fields {
+		g := b.Fields[i]
+		if f.Name != g.Name || f.Type != g.Type || f.Tag() != g.Tag() {
+			return false
+		}
+	}
+	return true
+}

internal/codegen/golang/json_type_test.go

@@ -0,0 +1,119 @@
+package golang
+
+import (
+	"strings"
+	"testing"
+)
+
+func field(name, typ string) Field {
+	return Field{Name: name, Type: typ, Tags: map[string]string{"json": name}}
+}
+
+func TestInternJSONTypes(t *testing.T) {
+	t.Run("first occurrence is emitted", func(t *testing.T) {
+		seen := map[string]JSONType{}
+		toEmit, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{
+			{Name: "Book", Fields: []Field{field("id", "int64")}},
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(toEmit) != 1 {
+			t.Fatalf("expected 1 type to emit, got %d", len(toEmit))
+		}
+	})
+
+	t.Run("same name and shape is interned, not re-emitted", func(t *testing.T) {
+		seen := map[string]JSONType{}
+		book := JSONType{Name: "Book", Fields: []Field{field("id", "int64")}}
+		if _, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{book}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		toEmit, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{book})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(toEmit) != 0 {
+			t.Errorf("expected 0 types to emit on reuse, got %d", len(toEmit))
+		}
+	})
+
+	t.Run("same name, different fields is a conflict", func(t *testing.T) {
+		seen := map[string]JSONType{}
+		if _, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{
+			{Name: "Book", Fields: []Field{field("id", "int64")}},
+		}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		_, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{
+			{Name: "Book", Fields: []Field{field("id", "int64"), field("title", "string")}},
+		})
+		if err == nil || !strings.Contains(err.Error(), "conflicting shapes") {
+			t.Errorf("error = %v, want mention of conflicting shapes", err)
+		}
+	})
+
+	t.Run("scalar and array uses of the same name intern together", func(t *testing.T) {
+		// The struct declaration is identical either way; only the
+		// referencing field gains a [] prefix, so these aren't a conflict.
+		seen := map[string]JSONType{}
+		book := JSONType{Name: "Book", Fields: []Field{field("id", "int64")}}
+		if _, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{book}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if _, err := internJSONTypes(seen, modelTypeSet{}, []JSONType{book}); err != nil {
+			t.Errorf("unexpected error reusing the same shape: %v", err)
+		}
+	})
+
+	t.Run("name collides with an existing model", func(t *testing.T) {
+		seen := map[string]JSONType{}
+		models := modelTypeSet{"Book": struct{}{}}
+		_, err := internJSONTypes(seen, models, []JSONType{
+			{Name: "Book", Fields: []Field{field("id", "int64")}},
+		})
+		if err == nil || !strings.Contains(err.Error(), "collides with an existing model") {
+			t.Errorf("error = %v, want mention of model collision", err)
+		}
+	})
+}
+
+func TestSameJSONShape(t *testing.T) {
+	tests := []struct {
+		name string
+		a, b JSONType
+		want bool
+	}{
+		{
+			name: "identical",
+			a:    JSONType{Fields: []Field{field("x", "int32")}},
+			b:    JSONType{Fields: []Field{field("x", "int32")}},
+			want: true,
+		},
+		{
+			name: "different field count",
+			a:    JSONType{Fields: []Field{field("x", "int32")}},
+			b:    JSONType{Fields: []Field{field("x", "int32"), field("y", "string")}},
+			want: false,
+		},
+		{
+			name: "different field type",
+			a:    JSONType{Fields: []Field{field("x", "int32")}},
+			b:    JSONType{Fields: []Field{field("x", "string")}},
+			want: false,
+		},
+		{
+			name: "different field name",
+			a:    JSONType{Fields: []Field{field("x", "int32")}},
+			b:    JSONType{Fields: []Field{field("y", "int32")}},
+			want: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := sameJSONShape(tt.a, tt.b); got != tt.want {
+				t.Errorf("sameJSONShape() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

internal/codegen/golang/query.go

@@ -279,6 +279,9 @@ type Query struct {
 	Arg          QueryValue
 	// Used for :copyfrom
 	Table *plugin.Identifier
+	// Go types synthesized from sqlc.jsonb_build_object(...) calls used by this query,
+	// emitted alongside the query's Arg/Ret structs.
+	JSONTypes []JSONType
 }
 
 func (q Query) hasRetType() bool {