GetQuery
Use db.GetQuery to read zero or one database row from a prepared db.Query value.
Use db.GetQuery when you already have a db.Query value and expect zero or one row.
It scans one row into a typed Go value and returns whether a row was found.
user, found, err := db.GetQuery[User](ctx, conn, q)
if err != nil {
return User{}, false, err
}
if !found {
return User{}, false, nil
}GetQuery is the query-object version of db.Get.
Function
func GetQuery[T any](ctx context.Context, c db.Querier, q db.Query) (T, bool, error)GetQuery accepts:
- a
context.Context - a connection or query-capable value
- a
db.Query
It returns:
T, found, errorfound is false when the query returns no rows.
When to Use GetQuery
Use db.GetQuery when:
- you already created a
db.Query - the query should return one row or no rows
- query creation and query execution are separate steps
- the query was created by
db.Rawordb.Dialect - a missing row is a normal application case
- the result shape is known
For direct query strings, use db.Get.
Define a Model
type User struct {
ID int64 `db:"id"`
Name string `db:"name"`
Email string `db:"email"`
Active bool `db:"active"`
CreatedAt time.Time `db:"created_at"`
}Create a Query Object
Create a db.Query using db.Raw.
For MySQL and Scylla, use ? placeholders.
const selectUserQuery = `
SELECT *
FROM users
WHERE id = ?
LIMIT 1
`q, err := db.Raw(selectUserQuery, id)
if err != nil {
return User{}, false, err
}For PostgreSQL, the query uses numbered placeholders.
const selectUserQuery = `
SELECT *
FROM users
WHERE id = $1
LIMIT 1
`The Go code stays the same:
q, err := db.Raw(selectUserQuery, id)
if err != nil {
return User{}, false, err
}Execute the Query Object
Pass the query object into db.GetQuery.
user, found, err := db.GetQuery[User](ctx, conn, q)
if err != nil {
return User{}, false, err
}
if !found {
return User{}, false, nil
}
return user, true, nilComplete Query Example
This example creates a db.Query and reads one user by ID.
package main
import (
"context"
"time"
"github.com/netlifeguru/db"
)
type User struct {
ID int64 `db:"id"`
Name string `db:"name"`
Email string `db:"email"`
Active bool `db:"active"`
CreatedAt time.Time `db:"created_at"`
}
const selectUserQuery = `
SELECT *
FROM users
WHERE id = ?
LIMIT 1
`
func GetUserQuery(ctx context.Context, conn db.Conn, id int64) (User, bool, error) {
q, err := db.Raw(selectUserQuery, id)
if err != nil {
return User{}, false, err
}
return db.GetQuery[User](ctx, conn, q)
}Complete Usage Example
This example connects to the database, executes the query-object helper, and handles the not-found case.
package main
import (
"context"
"fmt"
"log"
_ "github.com/go-sql-driver/mysql"
"github.com/joho/godotenv"
)
func main() {
err := godotenv.Load()
if err != nil {
log.Println(".env file not found, I'm using system env variables")
}
conn, err := connectDB()
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
user, found, err := GetUserQuery(ctx, conn, 1)
if err != nil {
log.Fatal(err)
}
if !found {
log.Println("user not found")
return
}
fmt.Printf(
"ID: %d | Name: %s | Email: %s | Active: %t | Created: %s\n",
user.ID,
user.Name,
user.Email,
user.Active,
user.CreatedAt.Format("2006-01-02 15:04:05"),
)
}Not Found
db.GetQuery does not return an error when no row is found.
Instead, it returns found = false.
user, found, err := db.GetQuery[User](ctx, conn, q)
if err != nil {
return User{}, false, err
}
if !found {
return User{}, false, nil
}This is useful for optional lookups.
Too Many Rows
db.GetQuery expects zero or one row.
If the query returns more than one row, it returns an error.
Use a unique condition or LIMIT 1 when only one row should be returned.
SELECT *
FROM users
WHERE id = ?
LIMIT 1Avoid LIMIT 1 when duplicate rows should be detected by the application.
Raw Query Validation
db.Raw returns an error when the query string is empty.
q, err := db.Raw("", id)
if err != nil {
return User{}, false, err
}This prevents empty query objects from being executed accidentally.
Query Objects From Dialect SQL
GetQuery is often used together with db.Dialect.
q, err := db.Dialect(conn, queries.GetUser, id)
if err != nil {
return User{}, false, err
}
return db.GetQuery[User](ctx, conn, q)For direct dialect usage, you can also use db.GetDialect.
user, found, err := db.GetDialect[User](ctx, conn, queries.GetUser, id)Related Helpers
Use db.Get when you want to pass the query string directly.
user, found, err := db.Get[User](ctx, conn, selectUserQuery, id)Use db.ListQuery when the query object can return multiple rows.
users, err := db.ListQuery[User](ctx, conn, q)Use db.ValueQuery when the query object returns one scalar value.
total, found, err := db.ValueQuery[int64](ctx, conn, q)Use db.MapsQuery when the query object returns dynamic map rows.
rows, err := db.MapsQuery(ctx, conn, q)Related Examples
Standalone examples are available in the examples repository: