Add a :type annotation to share a row type between queries

A query that returns more than one column gets a struct named after it, so
queries selecting the same columns return different types. `:type <TypeName>`
after the command names the row type instead, and queries that use the same
name return one struct. Generation fails if their columns give different
fields, if the name is a model's, or if the query returns a single column.

Plugins receive the name as Query.type_name. ParseQueryNameAndType now
returns the Metadata, so its callers no longer rebuild it from parts.

Fixes #781
Fixes #3595

Co-authored-by: ali <ali.dehkharghani@megadevs.de>

Author: egimbernat

docs/howto/row_types.md

@@ -0,0 +1,100 @@
+# Sharing a row type between queries
+
+sqlc generates a struct for the rows of each query that returns more than one
+column, named after the query. Queries that select the same columns therefore
+return different types, even though the structs are identical.
+
+```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: GetBook :one
+SELECT books.id, books.title, authors.name AS author_name
+FROM books
+JOIN authors ON authors.id = books.author_id
+WHERE books.id = $1;
+
+-- name: ListBooksByAuthor :many
+SELECT books.id, books.title, authors.name AS author_name
+FROM books
+JOIN authors ON authors.id = books.author_id
+WHERE books.author_id = $1;
+```
+
+```go
+type GetBookRow struct {
+	ID         int64
+	Title      string
+	AuthorName string
+}
+
+type ListBooksByAuthorRow struct {
+	ID         int64
+	Title      string
+	AuthorName string
+}
+```
+
+To have them return one type, name it with `:type <TypeName>` after the
+command:
+
+```sql
+-- name: GetBook :one :type BookWithAuthor
+SELECT books.id, books.title, authors.name AS author_name
+FROM books
+JOIN authors ON authors.id = books.author_id
+WHERE books.id = $1;
+
+-- name: ListBooksByAuthor :many :type BookWithAuthor
+SELECT books.id, books.title, authors.name AS author_name
+FROM books
+JOIN authors ON authors.id = books.author_id
+WHERE books.author_id = $1;
+```
+
+```go
+type BookWithAuthor struct {
+	ID         int64
+	Title      string
+	AuthorName string
+}
+
+func (q *Queries) GetBook(ctx context.Context, id int64) (BookWithAuthor, error) {
+	// ...
+}
+
+func (q *Queries) ListBooksByAuthor(ctx context.Context, authorID int64) ([]BookWithAuthor, error) {
+	// ...
+}
+```
+
+The type name works with [embedded structs](embedding.md) too, and a single
+query can use it just to choose the name of its row type.
+
+## Rules
+
+- Every query that names a type must return the same fields, in the same
+  order, with the same Go types and struct tags. Otherwise `sqlc generate`
+  fails and says which column differs:
+
+  ```
+  query ListBooks: :type BookWithAuthor does not match query GetBook: column 3 is AuthorID int64, want AuthorName string
+  ```
+
+- The query must return more than one column, since a query with a single
+  column returns that column's value instead of a struct.
+- The name must not be one sqlc already uses for a table's model. Queries
+  whose columns are exactly those of a table already return its model, such as
+  `Book`, without an annotation.
+- The type name always wins: a query annotated with `:type` returns that type
+  even when its columns match a table's model.

docs/reference/query-annotations.md

@@ -7,6 +7,14 @@ command. The format of this comment is as follows:
 -- name: <name> <command>
 ```
 
+A query that returns rows may also name the type they are returned as with
+`:type <TypeName>`, so that several queries can return the same type. See
+[sharing a row type between queries](../howto/row_types.md).
+
+```sql
+-- name: <name> <command> :type <TypeName>
+```
+
 ## `:exec`
 
 The generated method will return the error from

docs/toc.yaml

@@ -40,6 +40,7 @@ sections:
       - howto/ddl.md
       - howto/structs.md
       - howto/embedding.md
+      - howto/row_types.md
       - howto/overrides.md
       - howto/rename.md
 

internal/cmd/parse.go

@@ -142,12 +142,12 @@ Examples:
 				if err != nil {
 					return fmt.Errorf("failed to read statement source: %w", err)
 				}
-				name, cmd, err := metadata.ParseQueryNameAndType(rawSQL, commentSyntax)
+				md, err := metadata.ParseQueryNameAndType(rawSQL, commentSyntax)
 				if err != nil {
 					return fmt.Errorf("failed to parse query annotation: %w", err)
 				}
-				ps.Name = name
-				ps.Cmd = cmd
+				ps.Name = md.Name
+				ps.Cmd = md.Cmd
 				out = append(out, ps)
 			}
 

internal/cmd/shim.go

@@ -161,6 +161,7 @@ func pluginQueries(r *compiler.Result) []*plugin.Query {
 			Params:          params,
 			Filename:        q.Metadata.Filename,
 			InsertIntoTable: iit,
+			TypeName:        q.Metadata.TypeName,
 		})
 	}
 	return out

internal/codegen/golang/result.go

@@ -185,6 +185,7 @@ func argName(name string) string {
 func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []Enum, structs []Struct) ([]Query, error) {
 	models := buildModelTypeSet(enums, structs)
 	qualifier := options.ModelsTypeQualifier()
+	rowTypes := newRowTypes(structs)
 	qs := make([]Query, 0, len(req.Queries))
 	for _, query := range req.Queries {
 		if query.Name == "" {
@@ -269,6 +270,10 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []En
 			}
 		}
 
+		if query.TypeName != "" && !returnsStruct(query) {
+			return nil, fmt.Errorf("query %s: :type %s needs a query that returns more than one column", query.Name, query.TypeName)
+		}
+
 		if len(query.Columns) == 1 && query.Columns[0].EmbedTable == nil {
 			c := query.Columns[0]
 			name := columnName(c, 0)
@@ -303,7 +308,7 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []En
 			var emit bool
 
 			for _, s := range structs {
-				if len(s.Fields) != len(query.Columns) {
+				if query.TypeName != "" || len(s.Fields) != len(query.Columns) {
 					continue
 				}
 				same := true
@@ -331,12 +336,22 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []En
 						embed:  newGoEmbed(c.EmbedTable, structs, req.Catalog.DefaultSchema),
 					})
 				}
+				name := gq.MethodName + "Row"
+				if query.TypeName != "" {
+					name = query.TypeName
+				}
 				var err error
-				gs, err = columnsToStruct(req, options, gq.MethodName+"Row", columns, true, models, qualifier)
+				gs, err = columnsToStruct(req, options, name, columns, true, models, qualifier)
 				if err != nil {
 					return nil, err
 				}
 				emit = true
+				if query.TypeName != "" {
+					gs, emit, err = rowTypes.add(query.Name, gs)
+					if err != nil {
+						return nil, err
+					}
+				}
 			}
 			gq.Ret = QueryValue{
 				Emit:           emit,
@@ -361,6 +376,76 @@ var cmdReturnsData = map[string]struct{}{
 	metadata.CmdOne:       {},
 }
 
+// returnsStruct reports whether the Go code for query returns its rows as a
+// struct, which is what a ":type" annotation names.
+func returnsStruct(query *plugin.Query) bool {
+	if len(query.Columns) == 1 && query.Columns[0].EmbedTable == nil {
+		return false
+	}
+	return putOutColumns(query)
+}
+
+// rowTypes tracks the structs named by ":type" annotations, so that the
+// queries sharing a name return one struct.
+type rowTypes struct {
+	models map[string]bool
+	named  map[string]rowType
+}
+
+type rowType struct {
+	query string // the first query to use the name, which emits the struct
+	s     *Struct
+}
+
+func newRowTypes(models []Struct) *rowTypes {
+	r := &rowTypes{models: map[string]bool{}, named: map[string]rowType{}}
+	for _, m := range models {
+		r.models[m.Name] = true
+	}
+	return r
+}
+
+// add takes the struct built for the rows of a query annotated with ":type"
+// and returns the struct the query returns and whether to emit it. The first
+// query to use a name emits its struct; the others return that struct, as long
+// as their columns give the same fields.
+func (r *rowTypes) add(query string, s *Struct) (*Struct, bool, error) {
+	if r.models[s.Name] {
+		return nil, false, fmt.Errorf("query %s: :type %s is already the name of a model", query, s.Name)
+	}
+	first, ok := r.named[s.Name]
+	if !ok {
+		r.named[s.Name] = rowType{query: query, s: s}
+		return s, true, nil
+	}
+	if diff := fieldsDiff(first.s.Fields, s.Fields); diff != "" {
+		return nil, false, fmt.Errorf("query %s: :type %s does not match query %s: %s", query, s.Name, first.query, diff)
+	}
+	return first.s, false, nil
+}
+
+// fieldsDiff describes the first difference of got from want, or returns ""
+// if they are the same.
+func fieldsDiff(want, got []Field) string {
+	if len(got) != len(want) {
+		return fmt.Sprintf("%d columns, want %d", len(got), len(want))
+	}
+	for i, w := range want {
+		g := got[i]
+		if g.Name != w.Name || g.Type != w.Type || g.Tag() != w.Tag() || fieldsDiff(w.EmbedFields, g.EmbedFields) != "" {
+			return fmt.Sprintf("column %d is %s, want %s", i+1, describeField(g), describeField(w))
+		}
+	}
+	return ""
+}
+
+func describeField(f Field) string {
+	if tag := f.Tag(); tag != "" {
+		return fmt.Sprintf("%s %s `%s`", f.Name, f.Type, tag)
+	}
+	return f.Name + " " + f.Type
+}
+
 func putOutColumns(query *plugin.Query) bool {
 	_, found := cmdReturnsData[query.Cmd]
 	return found

internal/compiler/parse.go

@@ -54,24 +54,19 @@ func (c *Compiler) parseQuery(stmt ast.Node, pp *preprocess.Result, o opts.Parse
 		return nil, errors.New("missing semicolon at end of file")
 	}
 
-	name, cmd, err := metadata.ParseQueryNameAndType(rawSQL, metadata.CommentSyntax(c.parser.CommentSyntax()))
+	md, err := metadata.ParseQueryNameAndType(rawSQL, metadata.CommentSyntax(c.parser.CommentSyntax()))
 	if err != nil {
 		return nil, err
 	}
 
-	if name == "" {
+	if md.Name == "" {
 		return nil, nil
 	}
 
-	if err := validate.Cmd(raw.Stmt, name, cmd); err != nil {
+	if err := validate.Cmd(raw.Stmt, md.Name, md.Cmd); err != nil {
 		return nil, err
 	}
 
-	md := metadata.Metadata{
-		Name: name,
-		Cmd:  cmd,
-	}
-
 	// TODO eventually can use this for name and type/cmd parsing too
 	cleanedComments, err := source.CleanedComments(rawSQL, c.parser.CommentSyntax())
 	if err != nil {

internal/compiler/parse_core.go

@@ -24,18 +24,17 @@ func (c *Compiler) parseQueryCore(raw *ast.RawStmt, src string, pre *preprocess.
 		return nil, errors.New("missing semicolon at end of file")
 	}
 
-	name, cmd, err := metadata.ParseQueryNameAndType(rawSQL, metadata.CommentSyntax(c.parser.CommentSyntax()))
+	md, err := metadata.ParseQueryNameAndType(rawSQL, metadata.CommentSyntax(c.parser.CommentSyntax()))
 	if err != nil {
 		return nil, err
 	}
-	if name == "" {
+	if md.Name == "" {
 		return nil, nil
 	}
-	if err := validate.Cmd(raw.Stmt, name, cmd); err != nil {
+	if err := validate.Cmd(raw.Stmt, md.Name, md.Cmd); err != nil {
 		return nil, err
 	}
 
-	md := metadata.Metadata{Name: name, Cmd: cmd}
 	cleanedComments, err := source.CleanedComments(rawSQL, c.parser.CommentSyntax())
 	if err != nil {
 		return nil, err

internal/endtoend/testdata/codegen_json/gen/codegen.json

@@ -66389,7 +66389,8 @@
       ],
       "comments": [],
       "filename": "query.sql",
-      "insert_into_table": null
+      "insert_into_table": null,
+      "type_name": ""
     },
     {
       "text": "SELECT id, name, bio FROM authors\nORDER BY name",
@@ -66478,7 +66479,8 @@
       "params": [],
       "comments": [],
       "filename": "query.sql",
-      "insert_into_table": null
+      "insert_into_table": null,
+      "type_name": ""
     },
     {
       "text": "INSERT INTO authors (\n          name, bio\n) VALUES (\n  $1, $2\n)\nRETURNING id, name, bio",
@@ -66630,7 +66632,8 @@
         "catalog": "",
         "schema": "",
         "name": "authors"
-      }
+      },
+      "type_name": ""
     },
     {
       "text": "DELETE FROM authors\nWHERE id = $1",
@@ -66670,7 +66673,8 @@
       ],
       "comments": [],
       "filename": "query.sql",
-      "insert_into_table": null
+      "insert_into_table": null,
+      "type_name": ""
     }
   ],
   "sqlc_version": "v1.31.1",