feat(#2348, #2997): add sqlc.nembed() for nullable embeds

Introduces `sqlc.nembed()` function that generates nullable (pointer)
embed structs in Go codegen. When a LEFT JOIN may produce NULL rows,
nembed scans into temporary pointer variables and conditionally
constructs the embedded struct only when at least one field is non-nil.

Closes #2348
Closes #2997

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: luismingati

internal/analysis/analysis.pb.go

@@ -213,6 +213,8 @@ func pluginQueryColumn(c *compiler.Column) *plugin.Column {
 		}
 	}
 
+	out.IsNullableEmbed = c.NullableEmbed
+
 	return out
 }
 

internal/cmd/shim.go

@@ -10,6 +10,16 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/plugin"
 )
 
+// NullableEmbedFieldInfo stores metadata for scanning nullable embed fields
+type NullableEmbedFieldInfo struct {
+	TempVarName  string // ex: "nembedPostID"
+	ScanType     string // ex: "sql.NullInt32" for stdlib, "*int32" for pgx
+	ValidExpr    string // ex: "nembedPostID.Valid" or "nembedPostID != nil"
+	AssignExpr   string // ex: "nembedPostID.Int32" or "*nembedPostID"
+	StructField  string // ex: "ID"
+	OriginalType string // original type in the model struct (ex: "int32")
+}
+
 type Field struct {
 	Name    string // CamelCased name for Go
 	DBName  string // Name as used in the DB
@@ -19,6 +29,10 @@ type Field struct {
 	Column  *plugin.Column
 	// EmbedFields contains the embedded fields that require scanning.
 	EmbedFields []Field
+	// IsNullableEmbed indicates this field is a nullable embed (*Struct)
+	IsNullableEmbed bool
+	// NullableEmbedInfo stores scan metadata for each embedded field
+	NullableEmbedInfo []NullableEmbedFieldInfo
 }
 
 func (gf Field) Tag() string {

internal/codegen/golang/field.go

@@ -383,7 +383,9 @@ func filterUnusedStructs(enums []Enum, structs []Struct, queries []Query) ([]Enu
 			keepTypes[query.Ret.Type()] = struct{}{}
 			if query.Ret.IsStruct() {
 				for _, field := range query.Ret.Struct.Fields {
-					keepTypes[strings.TrimPrefix(field.Type, "[]")] = struct{}{}
+					trimmedType := strings.TrimPrefix(field.Type, "[]")
+					trimmedType = strings.TrimPrefix(trimmedType, "*")
+					keepTypes[trimmedType] = struct{}{}
 					for _, embedField := range field.EmbedFields {
 						keepTypes[embedField.Type] = struct{}{}
 					}

internal/codegen/golang/gen.go

@@ -319,6 +319,12 @@ func (i *importer) queryImports(filename string) fileImports {
 						if hasPrefixIgnoringSliceAndPointerPrefix(f.Type, name) {
 							return true
 						}
+						// Check nullable embed scan types
+						for _, info := range f.NullableEmbedInfo {
+							if hasPrefixIgnoringSliceAndPointerPrefix(info.ScanType, name) {
+								return true
+							}
+						}
 					}
 				}
 				if hasPrefixIgnoringSliceAndPointerPrefix(q.Ret.Type(), name) {
@@ -459,6 +465,11 @@ func (i *importer) batchImports() fileImports {
 						if hasPrefixIgnoringSliceAndPointerPrefix(f.Type, name) {
 							return true
 						}
+						for _, info := range f.NullableEmbedInfo {
+							if hasPrefixIgnoringSliceAndPointerPrefix(info.ScanType, name) {
+								return true
+							}
+						}
 					}
 				}
 				if hasPrefixIgnoringSliceAndPointerPrefix(q.Ret.Type(), name) {

internal/codegen/golang/imports.go

@@ -201,6 +201,14 @@ func (v QueryValue) Scan() string {
 	} else {
 		for _, f := range v.Struct.Fields {
 
+			// nullable embed: scan into temporary variables
+			if f.IsNullableEmbed && len(f.NullableEmbedInfo) > 0 {
+				for _, info := range f.NullableEmbedInfo {
+					out = append(out, "&"+info.TempVarName)
+				}
+				continue
+			}
+
 			// append any embedded fields
 			if len(f.EmbedFields) > 0 {
 				for _, embed := range f.EmbedFields {
@@ -227,6 +235,77 @@ func (v QueryValue) Scan() string {
 	return "\n" + strings.Join(out, ",\n")
 }
 
+// HasNullableEmbeds returns true if the query value has nullable embed fields
+func (v QueryValue) HasNullableEmbeds() bool {
+	if v.Struct == nil {
+		return false
+	}
+	for _, f := range v.Struct.Fields {
+		if f.IsNullableEmbed {
+			return true
+		}
+	}
+	return false
+}
+
+// NullableEmbedDecls generates declarations for nullable embed temporary variables
+func (v QueryValue) NullableEmbedDecls() string {
+	if v.Struct == nil {
+		return ""
+	}
+	var lines []string
+	for _, f := range v.Struct.Fields {
+		if !f.IsNullableEmbed {
+			continue
+		}
+		for _, info := range f.NullableEmbedInfo {
+			lines = append(lines, fmt.Sprintf("var %s %s", info.TempVarName, info.ScanType))
+		}
+	}
+	if len(lines) == 0 {
+		return ""
+	}
+	return "\n" + strings.Join(lines, "\n")
+}
+
+// NullableEmbedAssigns generates post-scan code to construct nullable embed structs
+func (v QueryValue) NullableEmbedAssigns() string {
+	if v.Struct == nil {
+		return ""
+	}
+	var blocks []string
+	for _, f := range v.Struct.Fields {
+		if !f.IsNullableEmbed || len(f.NullableEmbedInfo) == 0 {
+			continue
+		}
+
+		// Build the validity check: any field non-nil means the row exists
+		var validChecks []string
+		for _, info := range f.NullableEmbedInfo {
+			validChecks = append(validChecks, info.ValidExpr)
+		}
+
+		// Build the struct assignment
+		modelType := strings.TrimPrefix(f.Type, "*")
+		var assignments []string
+		for _, info := range f.NullableEmbedInfo {
+			assignments = append(assignments, fmt.Sprintf("%s: %s,", info.StructField, info.AssignExpr))
+		}
+
+		block := fmt.Sprintf("if %s {\n%s.%s = &%s{\n%s\n}\n}",
+			strings.Join(validChecks, " || "),
+			v.Name, f.Name,
+			modelType,
+			strings.Join(assignments, "\n"),
+		)
+		blocks = append(blocks, block)
+	}
+	if len(blocks) == 0 {
+		return ""
+	}
+	return "\n" + strings.Join(blocks, "\n")
+}
+
 // Deprecated: This method does not respect the Emit field set on the
 // QueryValue. It's used by the go-sql-driver-mysql/copyfromCopy.tmpl and should
 // not be used other places.

internal/codegen/golang/query.go

@@ -120,11 +120,12 @@ type goEmbed struct {
 	modelType string
 	modelName string
 	fields    []Field
+	nullable  bool
 }
 
 // look through all the structs and attempt to find a matching one to embed
 // We need the name of the struct and its field names.
-func newGoEmbed(embed *plugin.Identifier, structs []Struct, defaultSchema string) *goEmbed {
+func newGoEmbed(embed *plugin.Identifier, structs []Struct, defaultSchema string, nullable bool) *goEmbed {
 	if embed == nil {
 		return nil
 	}
@@ -147,6 +148,7 @@ func newGoEmbed(embed *plugin.Identifier, structs []Struct, defaultSchema string
 			modelType: s.Name,
 			modelName: s.Name,
 			fields:    fields,
+			nullable:  nullable,
 		}
 	}
 
@@ -304,7 +306,7 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, structs []
 					columns = append(columns, goColumn{
 						id:     i,
 						Column: c,
-						embed:  newGoEmbed(c.EmbedTable, structs, req.Catalog.DefaultSchema),
+						embed:  newGoEmbed(c.EmbedTable, structs, req.Catalog.DefaultSchema, c.IsNullableEmbed),
 					})
 				}
 				var err error
@@ -396,6 +398,11 @@ func columnsToStruct(req *plugin.GenerateRequest, options *opts.Options, name st
 		}
 		if c.embed == nil {
 			f.Type = goType(req, options, c.Column)
+		} else if c.embed.nullable {
+			f.Type = "*" + c.embed.modelType
+			f.EmbedFields = c.embed.fields
+			f.IsNullableEmbed = true
+			f.NullableEmbedInfo = computeNullableEmbedInfo(c.embed)
 		} else {
 			f.Type = c.embed.modelType
 			f.EmbedFields = c.embed.fields
@@ -435,6 +442,40 @@ func columnsToStruct(req *plugin.GenerateRequest, options *opts.Options, name st
 	return &gs, nil
 }
 
+// computeNullableEmbedInfo computes scan metadata for nullable embed fields.
+// For each field in the embed, we scan into a pointer-typed temporary variable,
+// then check if any temp var is non-nil to construct the struct.
+func computeNullableEmbedInfo(embed *goEmbed) []NullableEmbedFieldInfo {
+	var infos []NullableEmbedFieldInfo
+	for _, f := range embed.fields {
+		varName := "nembed" + embed.modelName + f.Name
+		originalType := f.Type
+		var scanType, validExpr, assignExpr string
+
+		if strings.HasPrefix(originalType, "*") {
+			// Already a pointer type (e.g., pgx nullable), scan directly
+			scanType = originalType
+			validExpr = varName + " != nil"
+			assignExpr = varName
+		} else {
+			// Wrap in pointer for nullable scan
+			scanType = "*" + originalType
+			validExpr = varName + " != nil"
+			assignExpr = "*" + varName
+		}
+
+		infos = append(infos, NullableEmbedFieldInfo{
+			TempVarName:  varName,
+			ScanType:     scanType,
+			ValidExpr:    validExpr,
+			AssignExpr:   assignExpr,
+			StructField:  f.Name,
+			OriginalType: originalType,
+		})
+	}
+	return infos
+}
+
 func checkIncompatibleFieldTypes(fields []Field) error {
 	fieldTypes := map[string]string{}
 	for _, field := range fields {

internal/codegen/golang/result.go

@@ -91,9 +91,11 @@ func (b *{{.MethodName}}BatchResults) Query(f func(int, []{{.Ret.DefineType}}, e
        defer rows.Close()
        for rows.Next() {
            var {{.Ret.Name}} {{.Ret.Type}}
+           {{- .Ret.NullableEmbedDecls}}
            if err := rows.Scan({{.Ret.Scan}}); err != nil {
              return err
            }
+           {{- .Ret.NullableEmbedAssigns}}
            items = append(items, {{.Ret.ReturnName}})
         }
         return rows.Err()
@@ -110,6 +112,7 @@ func (b *{{.MethodName}}BatchResults) QueryRow(f func(int, {{.Ret.DefineType}},
 	defer b.br.Close()
    for t := 0; t < b.tot; t++ {
      var {{.Ret.Name}} {{.Ret.Type}}
+     {{- .Ret.NullableEmbedDecls}}
      if b.closed {
         if f != nil {
           f(t, {{if .Ret.IsPointer}}nil{{else}}{{.Ret.Name}}{{end}}, ErrBatchAlreadyClosed)
@@ -118,6 +121,7 @@ func (b *{{.MethodName}}BatchResults) QueryRow(f func(int, {{.Ret.DefineType}},
      }
      row := b.br.QueryRow()
 	  err := row.Scan({{.Ret.Scan}})
+     {{- .Ret.NullableEmbedAssigns}}
      if f != nil {
        f(t, {{.Ret.ReturnName}}, err)
      }

internal/codegen/golang/templates/pgx/batchCode.tmpl

@@ -36,7 +36,9 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.De
 	{{- if or (ne .Arg.Pair .Ret.Pair) (ne .Arg.DefineType .Ret.DefineType) }}
 	var {{.Ret.Name}} {{.Ret.Type}}
 	{{- end}}
+	{{- .Ret.NullableEmbedDecls}}
 	err := row.Scan({{.Ret.Scan}})
+	{{- .Ret.NullableEmbedAssigns}}
 	{{- if $.WrapErrors}}
 	if err != nil {
 		err = fmt.Errorf("query {{.MethodName}}: %w", err)
@@ -67,9 +69,11 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ([]{{.Ret.
 	{{end -}}
 	for rows.Next() {
 		var {{.Ret.Name}} {{.Ret.Type}}
+		{{- .Ret.NullableEmbedDecls}}
 		if err := rows.Scan({{.Ret.Scan}}); err != nil {
 			return nil, {{if $.WrapErrors}}fmt.Errorf("query {{.MethodName}}: %w", err){{else}}err{{end}}
 		}
+		{{- .Ret.NullableEmbedAssigns}}
 		items = append(items, {{.Ret.ReturnName}})
 	}
 	if err := rows.Err(); err != nil {

internal/codegen/golang/templates/pgx/queryCode.tmpl

@@ -27,7 +27,9 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{ dbarg }} {{.Arg.Pair}}
 	{{- if or (ne .Arg.Pair .Ret.Pair) (ne .Arg.DefineType .Ret.DefineType) }}
 	var {{.Ret.Name}} {{.Ret.Type}}
 	{{- end}}
+	{{- .Ret.NullableEmbedDecls}}
 	err := row.Scan({{.Ret.Scan}})
+	{{- .Ret.NullableEmbedAssigns}}
 	{{- if $.WrapErrors}}
 	if err != nil {
 		err = fmt.Errorf("query {{.MethodName}}: %w", err)
@@ -53,9 +55,11 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{ dbarg }} {{.Arg.Pair}}
     {{end -}}
     for rows.Next() {
         var {{.Ret.Name}} {{.Ret.Type}}
+        {{- .Ret.NullableEmbedDecls}}
         if err := rows.Scan({{.Ret.Scan}}); err != nil {
             return nil, {{if $.WrapErrors}}fmt.Errorf("query {{.MethodName}}: %w", err){{else}}err{{end}}
         }
+        {{- .Ret.NullableEmbedAssigns}}
         items = append(items, {{.Ret.ReturnName}})
     }
     if err := rows.Close(); err != nil {