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 ¶
- Variables
- func All[T any](ctx context.Context, db qrm.Queryable, stmt Statement) (functional.Seq[T], error)
- func AllMap[T, R any](ctx context.Context, db qrm.Queryable, stmt Statement, f func(T) R) (functional.Seq[R], error)
- func Count(ctx context.Context, db qrm.Queryable, stmt Statement) (int64, error)
- func Exec(ctx context.Context, db qrm.Executable, stmt Statement) (sql.Result, error)
- func One[T any](ctx context.Context, db qrm.Queryable, stmt Statement) (functional.Option[T], error)
- func OneMap[T, R any](ctx context.Context, db qrm.Queryable, stmt Statement, f func(T) R) (functional.Option[R], error)
- type Statement
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
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 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.