Skip to content

feat(first): Add new command 'first' for optional returns #4286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jaglyserx wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(first): Add new command 'first' for optional returns #4286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e6bf21c
feat(first): add new command for optional return 'first'
jaglyserx Feb 4, 2026
3fa3e6e
feat(first): added documentation to query-annnotations.md
jaglyserx Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/reference/query-annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,25 @@ func (q *Queries) GetAuthor(ctx context.Context, id int64) (Author, error) {
}
```

## `:first`

The generated method will return a pointer to a single record via
[QueryRowContext](https://golang.org/pkg/database/sql/#DB.QueryRowContext).
If there are no results, it returns `nil, nil`.

```sql
-- name: GetAuthor :first
SELECT * FROM authors
WHERE id = $1 LIMIT 1;
```

```go
func (q *Queries) GetAuthor(ctx context.Context, id int64) (*Author, error) {
row := q.db.QueryRowContext(ctx, getAuthor, id)
// ...
}
```

## `:batchexec`

__NOTE: This command only works with PostgreSQL using the `pgx/v4` and `pgx/v5` drivers and outputting Go code.__
Expand Down
8 changes: 8 additions & 0 deletions internal/codegen/golang/gen.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,12 @@ func (t *tmplCtx) codegenQueryMethod(q Query) string {
}
return db + ".QueryRowContext"

case ":first":
if t.EmitPreparedQueries {
return "q.queryRow"
}
return db + ".QueryRowContext"

case ":many":
if t.EmitPreparedQueries {
return "q.query"
Expand All @@ -91,6 +97,8 @@ func (t *tmplCtx) codegenQueryMethod(q Query) string {
func (t *tmplCtx) codegenQueryRetval(q Query) (string, error) {
switch q.Cmd {
case ":one":
fallthrough
case ":first":
return "row :=", nil
case ":many":
return "rows, err :=", nil
Expand Down
19 changes: 19 additions & 0 deletions internal/codegen/golang/imports.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,25 @@ func (i *importer) queryImports(filename string) fileImports {
}
return false
})
usesFirst := false
for _, q := range gq {
if q.Cmd == metadata.CmdFirst {
usesFirst = true
break
}
}
if usesFirst {
std["errors"] = struct{}{}
sqlpkg := parseDriver(i.Options.SqlPackage)
switch sqlpkg {
case opts.SQLDriverPGXV4:
pkg[ImportSpec{Path: "github.com/jackc/pgx/v4"}] = struct{}{}
case opts.SQLDriverPGXV5:
pkg[ImportSpec{Path: "github.com/jackc/pgx/v5"}] = struct{}{}
default:
std["database/sql"] = struct{}{}
}
}

sliceScan := func() bool {
for _, q := range gq {
Expand Down
5 changes: 3 additions & 2 deletions internal/codegen/golang/query.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import (
type QueryValue struct {
Emit bool
EmitPointer bool
ForcePointer bool
Name string
DBName string // The name of the field in the database. Only set if Struct==nil.
Struct *Struct
Expand All @@ -32,7 +33,7 @@ func (v QueryValue) IsStruct() bool {
}

func (v QueryValue) IsPointer() bool {
return v.EmitPointer && v.Struct != nil
return v.ForcePointer || (v.EmitPointer && v.Struct != nil)
}

func (v QueryValue) isEmpty() bool {
Expand Down Expand Up @@ -270,7 +271,7 @@ type Query struct {
}

func (q Query) hasRetType() bool {
scanned := q.Cmd == metadata.CmdOne || q.Cmd == metadata.CmdMany ||
scanned := q.Cmd == metadata.CmdOne || q.Cmd == metadata.CmdFirst || q.Cmd == metadata.CmdMany ||
q.Cmd == metadata.CmdBatchMany || q.Cmd == metadata.CmdBatchOne
return scanned && !q.Ret.isEmpty()
}
Expand Down
4 changes: 4 additions & 0 deletions internal/codegen/golang/result.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,9 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, structs []
EmitPointer: options.EmitResultStructPointers,
}
}
if query.Cmd == metadata.CmdFirst {
gq.Ret.ForcePointer = true
}

qs = append(qs, gq)
}
Expand All @@ -334,6 +337,7 @@ var cmdReturnsData = map[string]struct{}{
metadata.CmdBatchOne: {},
metadata.CmdMany: {},
metadata.CmdOne: {},
metadata.CmdFirst: {},
}

func putOutColumns(query *plugin.Query) bool {
Expand Down
4 changes: 4 additions & 0 deletions internal/codegen/golang/result_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ func TestPutOutColumns_ForZeroColumns(t *testing.T) {
cmd: metadata.CmdOne,
want: true,
},
{
cmd: metadata.CmdFirst,
want: true,
},
{
cmd: metadata.CmdCopyFrom,
want: false,
Expand Down
9 changes: 9 additions & 0 deletions internal/codegen/golang/templates/pgx/interfaceCode.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@
{{end -}}
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- end}}
{{- if and (eq .Cmd ":first") ($dbtxParam) }}
{{range .Comments}}//{{.}}
{{end -}}
{{.MethodName}}(ctx context.Context, db DBTX, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- else if eq .Cmd ":first" }}
{{range .Comments}}//{{.}}
{{end -}}
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- end}}
{{- if and (eq .Cmd ":many") ($dbtxParam) }}
{{range .Comments}}//{{.}}
{{end -}}
Expand Down
25 changes: 25 additions & 0 deletions internal/codegen/golang/templates/pgx/queryCode.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,31 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.De
{{- end}}
return {{.Ret.ReturnName}}, err
}
{{else if eq .Cmd ":first"}}
{{range .Comments}}//{{.}}
{{end -}}
{{- if $.EmitMethodsWithDBArgument -}}
func (q *Queries) {{.MethodName}}(ctx context.Context, db DBTX, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error) {
row := db.QueryRow(ctx, {{.ConstantName}}, {{.Arg.Params}})
{{- else -}}
func (q *Queries) {{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error) {
row := q.db.QueryRow(ctx, {{.ConstantName}}, {{.Arg.Params}})
{{- end}}
{{- if or (ne .Arg.Pair .Ret.Pair) (ne .Arg.DefineType .Ret.DefineType) }}
var {{.Ret.Name}} {{.Ret.Type}}
{{- end}}
err := row.Scan({{.Ret.Scan}})
if err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return nil, nil
}
{{- if $.WrapErrors}}
err = fmt.Errorf("query {{.MethodName}}: %w", err)
{{- end}}
return nil, err
}
return {{.Ret.ReturnName}}, nil
}
{{end}}

{{if eq .Cmd ":many"}}
Expand Down
9 changes: 9 additions & 0 deletions internal/codegen/golang/templates/stdlib/interfaceCode.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@
{{end -}}
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- end}}
{{- if and (eq .Cmd ":first") ($dbtxParam) }}
{{range .Comments}}//{{.}}
{{end -}}
{{.MethodName}}(ctx context.Context, db DBTX, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- else if eq .Cmd ":first"}}
{{range .Comments}}//{{.}}
{{end -}}
{{.MethodName}}(ctx context.Context, {{.Arg.Pair}}) ({{.Ret.DefineType}}, error)
{{- end}}
{{- if and (eq .Cmd ":many") ($dbtxParam) }}
{{range .Comments}}//{{.}}
{{end -}}
Expand Down
20 changes: 20 additions & 0 deletions internal/codegen/golang/templates/stdlib/queryCode.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,26 @@ func (q *Queries) {{.MethodName}}(ctx context.Context, {{ dbarg }} {{.Arg.Pair}}
{{- end}}
return {{.Ret.ReturnName}}, err
}
{{else if eq .Cmd ":first"}}
{{range .Comments}}//{{.}}
{{end -}}
func (q *Queries) {{.MethodName}}(ctx context.Context, {{ dbarg }} {{.Arg.Pair}}) ({{.Ret.DefineType}}, error) {
{{- template "queryCodeStdExec" . }}
{{- if or (ne .Arg.Pair .Ret.Pair) (ne .Arg.DefineType .Ret.DefineType) }}
var {{.Ret.Name}} {{.Ret.Type}}
{{- end}}
err := row.Scan({{.Ret.Scan}})
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return nil, nil
}
{{- if $.WrapErrors}}
err = fmt.Errorf("query {{.MethodName}}: %w", err)
{{- end}}
return nil, err
}
return {{.Ret.ReturnName}}, nil
}
{{end}}

{{if eq .Cmd ":many"}}
Expand Down
2 changes: 1 addition & 1 deletion internal/endtoend/testdata/invalid_queries_foo/pgx/v4/stderr.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# package querytest
query.sql:1:1: missing query type [':one', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:1:1: missing query type [':one', ':first', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:5:1: invalid query comment: -- name: ListFoos :one :many
query.sql:8:1: invalid query type: :two
query.sql:11:1: query "DeleteFoo" specifies parameter ":one" without containing a RETURNING clause
Expand Down
2 changes: 1 addition & 1 deletion internal/endtoend/testdata/invalid_queries_foo/pgx/v5/stderr.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# package querytest
query.sql:1:1: missing query type [':one', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:1:1: missing query type [':one', ':first', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:5:1: invalid query comment: -- name: ListFoos :one :many
query.sql:8:1: invalid query type: :two
query.sql:11:1: query "DeleteFoo" specifies parameter ":one" without containing a RETURNING clause
Expand Down
4 changes: 2 additions & 2 deletions internal/endtoend/testdata/invalid_queries_foo/stdlib/stderr.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# package querytest
query.sql:1:1: missing query type [':one', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:1:1: missing query type [':one', ':first', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: -- name: ListFoos
query.sql:5:1: invalid query comment: -- name: ListFoos :one :many
query.sql:8:1: invalid query type: :two
query.sql:11:1: query "DeleteFoo" specifies parameter ":one" without containing a RETURNING clause
query.sql:14:1: query "UpdateFoo" specifies parameter ":one" without containing a RETURNING clause
query.sql:17:1: query "InsertFoo" specifies parameter ":one" without containing a RETURNING clause
query.sql:17:1: query "InsertFoo" specifies parameter ":one" without containing a RETURNING clause
5 changes: 3 additions & 2 deletions internal/metadata/meta.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ const (
CmdExecLastId = ":execlastid"
CmdMany = ":many"
CmdOne = ":one"
CmdFirst = ":first"
CmdCopyFrom = ":copyfrom"
CmdBatchExec = ":batchexec"
CmdBatchMany = ":batchmany"
Expand Down Expand Up @@ -98,15 +99,15 @@ func ParseQueryNameAndType(t string, commentStyle CommentSyntax) (string, string
part = part[:len(part)-1] // removes the trailing "*/" element
}
if len(part) == 3 {
return "", "", fmt.Errorf("missing query type [':one', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: %s", line)
return "", "", fmt.Errorf("missing query type [':one', ':first', ':many', ':exec', ':execrows', ':execlastid', ':execresult', ':copyfrom', 'batchexec', 'batchmany', 'batchone']: %s", line)
}
if len(part) != 4 {
return "", "", fmt.Errorf("invalid query comment: %s", line)
}
queryName := part[2]
queryType := strings.TrimSpace(part[3])
switch queryType {
case CmdOne, CmdMany, CmdExec, CmdExecResult, CmdExecRows, CmdExecLastId, CmdCopyFrom, CmdBatchExec, CmdBatchMany, CmdBatchOne:
case CmdOne, CmdFirst, CmdMany, CmdExec, CmdExecResult, CmdExecRows, CmdExecLastId, CmdCopyFrom, CmdBatchExec, CmdBatchMany, CmdBatchOne:
default:
return "", "", fmt.Errorf("invalid query type: %s", queryType)
}
Expand Down
2 changes: 1 addition & 1 deletion internal/sql/validate/cmd.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ func Cmd(n ast.Node, name, cmd string) error {
return err
}
}
if !(cmd == metadata.CmdMany || cmd == metadata.CmdOne || cmd == metadata.CmdBatchMany || cmd == metadata.CmdBatchOne) {
if !(cmd == metadata.CmdMany || cmd == metadata.CmdOne || cmd == metadata.CmdFirst || cmd == metadata.CmdBatchMany || cmd == metadata.CmdBatchOne) {
return nil
}
var list *ast.List
Expand Down
Loading