query

package
v0.23.0-beta.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0, BSD-3-Clause, MIT Imports: 8 Imported by: 0

Documentation

Overview

Package query runs Nanostack DB statements and maps their results. Absence is not failure: a statement that finds nothing returns None or an empty Seq, never sql.ErrNoRows.

stmt := SELECT(Invoice.AllColumns).FROM(Invoice).WHERE(Invoice.ID.EQ(UUID(id)))
invoice, err := query.One[model.Invoice](ctx, db, stmt) // (functional.Option[model.Invoice], error)
if err != nil {
	return err
}
inv, err := invoice.ToResult(ErrInvoiceNotFound).Value() // absence becomes an error here, by choice

open, err := query.All[model.Invoice](ctx, db, SELECT(...)) // functional.Seq[model.Invoice], never nil
n, err := query.Count(ctx, db, SELECT(COUNT(STAR)).FROM(Invoice))

The helpers take the executor explicitly: a *sql.DB, *sql.Tx, *sql.Conn, a stmtcache DB or Tx, or anything with QueryContext/ExecContext. They never look a transaction up in the context: the context-carried transaction belongs to the caller's transaction manager, which passes its executor in, for example

query.One[model.Invoice](ctx, transactor.Executor(ctx, db), stmt)

Statements run through stmt.QueryContext and stmt.ExecContext, so the statement and query loggers (SetLogger, SetQueryLogger) see them. Errors are wrapped once ("query.One[model.Invoice]: ..."), so errors.As still finds the driver's error. Invalid statements still panic, as they do in jet: they are programming errors.

This package is Nanostack-only (not in go-jet). See db/UPSTREAM.md.

Index

Constants

This section is empty.

Variables

View Source
var ErrTooManyRows = errors.New("query: statement returned more than one result")

ErrTooManyRows is returned (wrapped, with the count) by One and Count when the result maps to more than one value.

Functions

func All

func All[T any](ctx context.Context, db qrm.Queryable, stmt Statement) (functional.Seq[T], error)

All runs stmt and returns every value its result maps to. The result is never nil: no rows give an empty Seq. Rows that map to no value (every mapped column NULL) are left out. SELECT_JSON_ARR works; SELECT_JSON_OBJ does not (see One).

func AllMap

func AllMap[T, R any](ctx context.Context, db qrm.Queryable, stmt Statement, f func(T) R) (functional.Seq[R], error)

AllMap is All followed by Seq.Map. The result is never nil.

func Count

func Count(ctx context.Context, db qrm.Queryable, stmt Statement) (int64, error)

Count runs a statement whose single column is an integer, such as SELECT COUNT(*). It returns 0 when the statement yields no row (COUNT ... GROUP BY with no groups) or NULL, and ErrTooManyRows when it yields more than one non-NULL row.

func Exec

func Exec(ctx context.Context, db qrm.Executable, stmt Statement) (sql.Result, error)

Exec runs a statement that returns no rows.

func One

func One[T any](ctx context.Context, db qrm.Queryable, stmt Statement) (functional.Option[T], error)

One runs stmt and returns the single value its result maps to.

  • None: no row, or rows that map to no value (every mapped column NULL).
  • Some: exactly one value. Rows are grouped the way qrm groups them, so one parent whose nested slices spread over many rows is one value.
  • ErrTooManyRows (wrapped, with the count): more than one value.

T is a model struct, a custom destination struct or a scalar (One[int64] reads the first column; a NULL value is None). Results are scanned into []T, never into a struct, so duplicates are detected. SELECT_JSON_ARR works; SELECT_JSON_OBJ does not (its destination is one object, not rows: qrm panics), use stmt.QueryContext for it. T must not be a functional.Option.

func OneMap

func OneMap[T, R any](
	ctx context.Context,
	db qrm.Queryable,
	stmt Statement,
	f func(T) R,
) (functional.Option[R], error)

OneMap is One followed by Option.Map. It exists because One returns a pair, which cannot be chained.

Types

type Statement

type Statement = jet.Statement

Statement is any statement built with the postgres, mysql or sqlite packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL