feat: add sqlc.embed.jsonb(table) for whole-row JSON results

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

Author: m-ali-akbay

docs/howto/embedding.md

@@ -150,4 +150,44 @@ The struct name and individual field names can be overridden via the
 
 `"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.
+key (`"id"`) instead to rename that field everywhere.
+
+##### Embedding a whole row as JSON
+
+Listing every column by hand is tedious when you just want the whole row.
+`sqlc.embed.jsonb(table)` builds a JSON object from all of a table's columns,
+the same way `sqlc.embed(table)` gives you the table's model — but as a
+single JSON value, so it can be nested inside `ARRAY(...)` to return a slice
+of rows from one query:
+
+```sql
+-- name: GetAuthorsWithBooks :many
+SELECT
+  authors.id,
+  ARRAY(SELECT sqlc.embed.jsonb(books) FROM books WHERE books.author_id = authors.id) AS books
+FROM authors;
+```
+
+```go
+type GetAuthorsWithBooksRow struct {
+	ID    int64  `json:"id"`
+	Books []Book `json:"books"`
+}
+
+type Book struct {
+	ID       int64  `json:"id"`
+	AuthorID int64  `json:"author_id"`
+	Title    string `json:"title"`
+}
+```
+
+The generated struct is named from the result alias — singularized for the
+`ARRAY(...)` case (`AS books` → `Book`), or used as-is for a scalar
+`sqlc.embed.jsonb(table) AS author` (→ `Author`). Fields, types and JSON keys
+come from the table's columns, so the object always decodes cleanly. Under
+the hood the call is rewritten to `to_jsonb(table)`, which you'll see in
+`EXPLAIN` output and logs.
+
+Like `sqlc.jsonb_build_object`, this is pgx/v5 only, and the generated name
+must not collide with a model or another JSON type; use the `rename` option
+if it does.

internal/codegen/golang/gen.go

@@ -213,7 +213,7 @@ func generate(req *plugin.GenerateRequest, options *opts.Options, enums []Enum,
 	}
 
 	if usesJSON(queries) && tctx.SQLDriver != opts.SQLDriverPGXV5 {
-		return nil, errors.New("sqlc.jsonb_build_object(...) is only supported by pgx/v5")
+		return nil, errors.New("sqlc.jsonb_build_object(...) and sqlc.embed.jsonb(...) are only supported by pgx/v5")
 	}
 
 	funcMap := template.FuncMap{

internal/compiler/json_columns.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
+	"github.com/sqlc-dev/sqlc/internal/sql/astutils"
 )
 
 // outputJSONColumn resolves the Column produced by an
@@ -59,6 +60,62 @@ func (c *Compiler) outputJSONColumn(qc *QueryCatalog, tables []*Table, res *ast.
 	}, nil
 }
 
+// outputEmbedJSONColumn resolves the Column produced by an
+// sqlc.embed.jsonb(table) call: a synthesized struct whose fields mirror the
+// referenced table's columns, decoded from a single to_jsonb(table) value
+// (see rewrite.IsEmbedJSONCall and expandJSON). The struct name is derived
+// from the result alias; for the array case it is left empty here and filled
+// in by the enclosing ARRAY_SUBLINK from its own alias.
+func (c *Compiler) outputEmbedJSONColumn(qc *QueryCatalog, tables []*Table, res *ast.ResTarget, call *ast.FuncCall) (*Column, error) {
+	if call.Args == nil || len(call.Args.Items) != 1 {
+		return nil, fmt.Errorf("sqlc.embed.jsonb(...) takes a single table argument")
+	}
+	ref, ok := call.Args.Items[0].(*ast.ColumnRef)
+	if !ok {
+		return nil, fmt.Errorf("sqlc.embed.jsonb(...) argument must be a table reference")
+	}
+	target := astutils.Join(ref.Fields, ".")
+
+	var table *Table
+	for _, t := range tables {
+		if t.Rel.Name == target {
+			table = t
+			break
+		}
+	}
+	if table == nil {
+		return nil, fmt.Errorf("sqlc.embed.jsonb(%s): table not found in the query's FROM clause", target)
+	}
+
+	var fields []*Column
+	for _, col := range table.Columns {
+		fields = append(fields, &Column{
+			Name:      col.Name,
+			DataType:  col.DataType,
+			NotNull:   col.NotNull,
+			Unsigned:  col.Unsigned,
+			IsArray:   col.IsArray,
+			ArrayDims: col.ArrayDims,
+			Length:    col.Length,
+			Type:      col.Type,
+		})
+	}
+
+	name := "json"
+	jsonName := ""
+	if res.Name != nil {
+		name = *res.Name
+		jsonName = *res.Name
+	}
+	return &Column{
+		Name:       name,
+		DataType:   "any",
+		NotNull:    true,
+		JSONFields: fields,
+		JSONName:   jsonName,
+	}, nil
+}
+
 func jsonStringLiteral(node ast.Node) (string, bool) {
 	aconst, ok := node.(*ast.A_Const)
 	if !ok {

internal/compiler/json_columns_test.go

@@ -153,3 +153,49 @@ func TestOutputColumnsJSON(t *testing.T) {
 		}
 	})
 }
+
+func TestOutputColumnsEmbedJSON(t *testing.T) {
+	c := newTestCompiler(t, testSchema)
+
+	t.Run("scalar mirrors the table's columns", func(t *testing.T) {
+		a := mustAnalyze(t, c, `SELECT sqlc.embed.jsonb(items) AS obj FROM items;`)
+		col := a.Columns[0]
+		if col.JSONName != "obj" {
+			t.Errorf("JSONName = %q, want %q", col.JSONName, "obj")
+		}
+		if col.IsArray {
+			t.Errorf("IsArray = true, want false")
+		}
+		if !col.NotNull {
+			t.Errorf("NotNull = false, want true")
+		}
+		if len(col.JSONFields) != 3 {
+			t.Fatalf("expected 3 JSONFields (id, x, y), got %d", len(col.JSONFields))
+		}
+		names := []string{col.JSONFields[0].Name, col.JSONFields[1].Name, col.JSONFields[2].Name}
+		if names[0] != "id" || names[1] != "x" || names[2] != "y" {
+			t.Errorf("field names = %v, want [id x y]", names)
+		}
+	})
+
+	t.Run("array singularizes the outer alias for the element name", func(t *testing.T) {
+		a := mustAnalyze(t, c, `SELECT ARRAY(SELECT sqlc.embed.jsonb(items) FROM items) AS objs;`)
+		col := a.Columns[0]
+		if !col.IsArray || col.ArrayDims != 1 {
+			t.Errorf("IsArray/ArrayDims = %v/%d, want true/1", col.IsArray, col.ArrayDims)
+		}
+		if col.JSONName != "obj" {
+			t.Errorf("JSONName = %q, want %q (singular of the alias)", col.JSONName, "obj")
+		}
+		if len(col.JSONFields) != 3 {
+			t.Fatalf("expected 3 JSONFields, got %d", len(col.JSONFields))
+		}
+	})
+
+	t.Run("unknown table", func(t *testing.T) {
+		err := analyzeErr(t, c, `SELECT sqlc.embed.jsonb(missing) AS obj FROM items;`)
+		if !strings.Contains(err.Error(), "table not found") {
+			t.Errorf("error = %v, want mention of table not found", err)
+		}
+	})
+}

internal/compiler/json_expand.go

@@ -20,14 +20,19 @@ func findOpenParen(s string, from int) (int, error) {
 	return from + idx, nil
 }
 
-// expandJSON rewrites sqlc.jsonb_build_object."Name"(k, v, ...) calls into
-// jsonb_build_object(k, v, ...): the qualified name is replaced (the struct
-// name has no equivalent in real SQL) but the argument list, already just
-// key/value pairs, is left untouched, including any enclosing ARRAY(...).
-// pgx v5 decodes a literal ARRAY(SELECT jsonb_build_object(...) FROM ...)
-// directly into a Go slice, so no further SQL restructuring is needed.
+// expandJSON rewrites sqlc's JSON directives into real Postgres functions,
+// replacing only the qualified name span (which has no equivalent in real
+// SQL) and leaving the argument list and any enclosing ARRAY(...) untouched:
+//
+//   - sqlc.jsonb_build_object."Name"(k, v, ...) -> jsonb_build_object(k, v, ...)
+//   - sqlc.embed.jsonb(table)                   -> to_jsonb(table)
+//
+// pgx v5 decodes a literal ARRAY(SELECT ... FROM ...) of jsonb directly into
+// a Go slice, so no further SQL restructuring is needed.
 func (c *Compiler) expandJSON(raw *ast.RawStmt, query string) ([]source.Edit, error) {
-	calls := astutils.Search(raw, rewrite.IsJSONCall)
+	calls := astutils.Search(raw, func(node ast.Node) bool {
+		return rewrite.IsJSONCall(node) || rewrite.IsEmbedJSONCall(node)
+	})
 	if len(calls.Items) == 0 {
 		return nil, nil
 	}
@@ -43,10 +48,15 @@ func (c *Compiler) expandJSON(raw *ast.RawStmt, query string) ([]source.Edit, er
 		}
 		length := openParen - loc
 
+		replacement := "jsonb_build_object"
+		if rewrite.IsEmbedJSONCall(call) {
+			replacement = "to_jsonb"
+		}
+
 		edits = append(edits, source.Edit{
 			Location: loc,
 			OldFunc:  func(string) int { return length },
-			New:      "jsonb_build_object",
+			New:      replacement,
 		})
 	}
 

internal/compiler/json_expand_test.go

@@ -46,6 +46,21 @@ func TestExpandJSON(t *testing.T) {
 			in:   `SELECT sqlc.jsonb_build_object.Obj('x', a, 'y', b) AS obj FROM t`,
 			want: `SELECT jsonb_build_object('x', a, 'y', b) AS obj FROM t`,
 		},
+		{
+			name: "embed.jsonb scalar rewrites to to_jsonb",
+			in:   `SELECT sqlc.embed.jsonb(t) AS obj FROM t`,
+			want: `SELECT to_jsonb(t) AS obj FROM t`,
+		},
+		{
+			name: "embed.jsonb inside ARRAY(...) leaves the wrapper untouched",
+			in:   `SELECT ARRAY(SELECT sqlc.embed.jsonb(c) FROM c WHERE c.parent_id = p.id) AS children FROM p`,
+			want: `SELECT ARRAY(SELECT to_jsonb(c) FROM c WHERE c.parent_id = p.id) AS children FROM p`,
+		},
+		{
+			name: "mix of jsonb_build_object and embed.jsonb in one query",
+			in:   `SELECT sqlc.jsonb_build_object."Obj"('x', a) AS obj, sqlc.embed.jsonb(t) AS row FROM t`,
+			want: `SELECT jsonb_build_object('x', a) AS obj, to_jsonb(t) AS row FROM t`,
+		},
 	}
 
 	for _, tt := range tests {

internal/compiler/output_columns.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 
+	"github.com/sqlc-dev/sqlc/internal/inflection"
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
 	"github.com/sqlc-dev/sqlc/internal/sql/astutils"
 	"github.com/sqlc-dev/sqlc/internal/sql/catalog"
@@ -345,6 +346,14 @@ func (c *Compiler) outputColumn(qc *QueryCatalog, tables []*Table, res *ast.ResT
 			cols = append(cols, col)
 			return cols, nil
 		}
+		if rewrite.IsEmbedJSONCall(n) {
+			col, err := c.outputEmbedJSONColumn(qc, tables, res, n)
+			if err != nil {
+				return nil, err
+			}
+			cols = append(cols, col)
+			return cols, nil
+		}
 
 		rel := n.Func
 		name := rel.Name
@@ -397,6 +406,11 @@ func (c *Compiler) outputColumn(qc *QueryCatalog, tables []*Table, res *ast.ResT
 			if res.Name != nil {
 				first.Name = *res.Name
 			}
+			// An sqlc.embed.jsonb(table) column has no name of its own; the
+			// array's alias, singularized, names the element struct.
+			if first.JSONFields != nil && first.JSONName == "" && res.Name != nil {
+				first.JSONName = inflection.Singular(inflection.SingularParams{Name: *res.Name})
+			}
 			if first.IsArray {
 				first.ArrayDims++
 			} else {