Skip to content

Commit 289098b

Browse files
committed
Add the :iter query annotation
A :iter query generates a method returning an iter.Seq over the query's rows, plus a function returning the query's error once the loop is done. The PostgreSQL authors example shows its use.
1 parent 0942ad2 commit 289098b

13 files changed

Lines changed: 228 additions & 5 deletions

File tree

‎examples/authors/postgresql/db_test.go‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ package authors
44

55
import (
66
"context"
7+
"errors"
8+
"slices"
79
"testing"
810

911
"github.com/jackc/pgx/v5"
@@ -47,3 +49,71 @@ func TestAuthors(t *testing.T) {
4749
}
4850
t.Log(fetchedAuthor)
4951
}
52+
53+
func TestIterAuthors(t *testing.T) {
54+
ctx := context.Background()
55+
uri := local.PostgreSQL(t, []string{"schema.sql"})
56+
db, err := pgx.Connect(ctx, uri)
57+
if err != nil {
58+
t.Fatal(err)
59+
}
60+
defer db.Close(ctx)
61+
62+
q := New(db)
63+
64+
var last Author
65+
for _, name := range []string{"Rob Pike", "Brian Kernighan", "Ken Thompson"} {
66+
if last, err = q.CreateAuthor(ctx, CreateAuthorParams{Name: name}); err != nil {
67+
t.Fatal(err)
68+
}
69+
}
70+
71+
// the query only runs once the iterator is ranged over, so the
72+
// connection is still free for other queries until then
73+
authors, ferr := q.IterAuthors(ctx)
74+
if _, err := q.GetAuthor(ctx, last.ID); err != nil {
75+
t.Fatalf("query before ranging: %v", err)
76+
}
77+
var names []string
78+
for author := range authors {
79+
names = append(names, author.Name)
80+
}
81+
if err := ferr(); err != nil {
82+
t.Fatal(err)
83+
}
84+
if want := []string{"Brian Kernighan", "Ken Thompson", "Rob Pike"}; !slices.Equal(names, want) {
85+
t.Fatalf("got %v, want %v", names, want)
86+
}
87+
88+
// the iterator is single-use: ranging over it again yields nothing and
89+
// reports an error
90+
for author := range authors {
91+
t.Errorf("second range yielded %v", author)
92+
}
93+
if err := ferr(); err == nil {
94+
t.Error("ranging twice reported no error")
95+
}
96+
97+
// breaking out of the loop early releases the connection
98+
authors, ferr = q.IterAuthors(ctx)
99+
for range authors {
100+
break
101+
}
102+
if err := ferr(); err != nil {
103+
t.Fatal(err)
104+
}
105+
if _, err := q.GetAuthor(ctx, last.ID); err != nil {
106+
t.Errorf("query after breaking out: %v", err)
107+
}
108+
109+
// a query that fails reports its error through the returned func
110+
cctx, cancel := context.WithCancel(ctx)
111+
cancel()
112+
authors, ferr = q.IterAuthors(cctx)
113+
for author := range authors {
114+
t.Errorf("cancelled query yielded %v", author)
115+
}
116+
if err := ferr(); !errors.Is(err, context.Canceled) {
117+
t.Errorf("got error %v, want context.Canceled", err)
118+
}
119+
}

‎examples/authors/postgresql/query.sql‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,7 @@ RETURNING *;
1717
-- name: DeleteAuthor :exec
1818
DELETE FROM authors
1919
WHERE id = $1;
20+
21+
-- name: IterAuthors :iter
22+
SELECT * FROM authors
23+
ORDER BY name;

‎examples/authors/postgresql/query.sql.go‎

Lines changed: 42 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎internal/codegen/golang/gen.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ func (t *tmplCtx) codegenQueryMethod(q Query) string {
7676
}
7777
return db + ".QueryRowContext"
7878

79-
case ":many":
79+
case ":many", ":iter":
8080
if t.EmitPreparedQueries {
8181
return "q.query"
8282
}
@@ -94,7 +94,7 @@ func (t *tmplCtx) codegenQueryRetval(q Query) (string, error) {
9494
switch q.Cmd {
9595
case ":one":
9696
return "row :=", nil
97-
case ":many":
97+
case ":many", ":iter":
9898
return "rows, err :=", nil
9999
case ":exec":
100100
return "_, err :=", nil

‎internal/codegen/golang/imports.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,9 @@ func buildImports(options *opts.Options, engine string, queries []Query, uses fu
206206
std["database/sql"] = struct{}{}
207207
}
208208
}
209+
if q.Cmd == metadata.CmdIter {
210+
std["iter"] = struct{}{}
211+
}
209212
}
210213

211214
for typeName, pkg := range stdlibTypes {
@@ -446,6 +449,13 @@ func (i *importer) queryImports(filename string) fileImports {
446449
}
447450
}
448451

452+
// An :iter method reports a second range over its iterator as an error.
453+
for _, q := range gq {
454+
if q.Cmd == metadata.CmdIter {
455+
std["errors"] = struct{}{}
456+
}
457+
}
458+
449459
if anyNonCopyFrom {
450460
std["context"] = struct{}{}
451461
}

‎internal/codegen/golang/query.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,7 @@ type Query struct {
304304
}
305305

306306
func (q Query) hasRetType() bool {
307-
scanned := q.Cmd == metadata.CmdOne || q.Cmd == metadata.CmdMany ||
307+
scanned := q.Cmd == metadata.CmdOne || q.Cmd == metadata.CmdMany || q.Cmd == metadata.CmdIter ||
308308
q.Cmd == metadata.CmdBatchMany || q.Cmd == metadata.CmdBatchOne
309309
return scanned && !q.Ret.isEmpty()
310310
}

‎internal/codegen/golang/result.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,16 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []En
205205
}
206206

207207
comments := query.Comments
208+
if query.Cmd == metadata.CmdIter {
209+
if len(comments) > 0 {
210+
comments = append(comments, "")
211+
}
212+
comments = append(comments,
213+
" "+query.Name+" returns a single-use iterator. The query runs when the",
214+
" iterator is ranged over, and the returned func reports its error",
215+
" after the loop.",
216+
)
217+
}
208218
if options.EmitSqlAsComment {
209219
if len(comments) == 0 {
210220
comments = append(comments, query.Name)
@@ -370,6 +380,7 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, enums []En
370380
var cmdReturnsData = map[string]struct{}{
371381
metadata.CmdBatchMany: {},
372382
metadata.CmdBatchOne: {},
383+
metadata.CmdIter: {},
373384
metadata.CmdMany: {},
374385
metadata.CmdOne: {},
375386
}

‎internal/codegen/golang/templates/pgx/interfaceCode.tmpl‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@
2020
{{end -}}
2121
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ([]{{.Ret.DefineType}}, error)
2222
{{- end}}
23+
{{- if eq .Cmd ":iter" }}
24+
{{range .Comments}}//{{.}}
25+
{{end -}}
26+
{{.MethodName}}(ctx context.Context, {{if $dbtxParam}}db DBTX, {{end}}{{.Arg.Pair}}) (iter.Seq[{{.Ret.DefineType}}], func() error)
27+
{{- end}}
2328
{{- if and (eq .Cmd ":exec") ($dbtxParam) }}
2429
{{range .Comments}}//{{.}}
2530
{{end -}}

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,42 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ([]{{.Ret.
7979
}
8080
{{end}}
8181

82+
{{if eq .Cmd ":iter"}}
83+
{{range .Comments}}//{{.}}
84+
{{end -}}
85+
func (q *Queries) {{.MethodName}}(ctx context.Context, {{if $.EmitMethodsWithDBArgument}}db DBTX, {{end}}{{.Arg.Pair}}) (iter.Seq[{{.Ret.DefineType}}], func() error) {
86+
var _err error
87+
var _used bool
88+
return func(_yield func({{.Ret.DefineType}}) bool) {
89+
if _used {
90+
_err = errors.New("query {{.MethodName}}: iterator already used")
91+
return
92+
}
93+
_used = true
94+
rows, err := {{if $.EmitMethodsWithDBArgument}}db{{else}}q.db{{end}}.Query(ctx, {{.ConstantName}}, {{.Arg.Params}})
95+
if err != nil {
96+
_err = {{if $.WrapErrors}}fmt.Errorf("query {{.MethodName}}: %w", err){{else}}err{{end}}
97+
return
98+
}
99+
defer rows.Close()
100+
for rows.Next() {
101+
var {{.Ret.Name}} {{.Ret.Type}}
102+
if err := rows.Scan({{.Ret.Scan}}); err != nil {
103+
_err = {{if $.WrapErrors}}fmt.Errorf("query {{.MethodName}}: %w", err){{else}}err{{end}}
104+
return
105+
}
106+
if !_yield({{.Ret.ReturnName}}) {
107+
break
108+
}
109+
}
110+
rows.Close()
111+
if err := rows.Err(); err != nil {
112+
_err = {{if $.WrapErrors}}fmt.Errorf("query {{.MethodName}}: %w", err){{else}}err{{end}}
113+
}
114+
}, func() error { return _err }
115+
}
116+
{{end}}
117+
82118
{{if eq .Cmd ":exec"}}
83119
{{range .Comments}}//{{.}}
84120
{{end -}}

‎internal/codegen/golang/templates/stdlib/interfaceCode.tmpl‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@
2020
{{end -}}
2121
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ([]{{.Ret.DefineType}}, error)
2222
{{- end}}
23+
{{- if eq .Cmd ":iter" }}
24+
{{range .Comments}}//{{.}}
25+
{{end -}}
26+
{{.MethodName}}(ctx context.Context, {{if $dbtxParam}}db DBTX, {{end}}{{.Arg.Pair}}) (iter.Seq[{{.Ret.DefineType}}], func() error)
27+
{{- end}}
2328
{{- if and (eq .Cmd ":exec") ($dbtxParam) }}
2429
{{range .Comments}}//{{.}}
2530
{{end -}}

0 commit comments

Comments
 (0)