scan

Documentation

Overview

Package scan maps result rows to typed Go values. It caches a per-T scan plan (computed once, reused) and adds the two things generics make possible: no interface{} dest, and iter.Seq2[T, error] streaming.

Scanning uses direct field-address scanning (rows.Scan into &struct.Field) for correctness and simplicity.

Index

• func All[T any](rows Rows) ([]T, error)
• func AllKeyedReflect(rows Rows, keyCol string, elem reflect.Type) (keys []any, items reflect.Value, err error)
• func AllReflect(rows Rows, elem reflect.Type) (reflect.Value, error)
• func AutoPrimaryKey[T any]() (string, bool)
• func Columns[T any](skipAuto bool) []string
• func EmbeddedInfo(sf reflect.StructField) (prefix string, embedded bool)
• func GoTypeName(t reflect.Type) string
• func Into[T any](rows Rows, v *T) error
• func IsRelationField(ft reflect.Type) bool
• func Iter[T any](rows Rows) iter.Seq2[T, error]
• func ParseGormTag(tag string) map[string]string
• func ParseList(tag string) (name string, opts []string)
• func PrimaryKey[T any]() (string, bool)
• func PrimaryKeys[T any]() []string
• func RegisterPlural(singular, plural string)
• func Scalars[V any](rows Rows) ([]V, error)
• func SetPluralTableNames(on bool)
• func SetPrimaryKey[T any](v *T, id int64)
• func Snake(s string) string
• func TableNameOf(t reflect.Type) string
• func Values[T any](v *T, cols []string) []any
• type ColumnInfo
  • func ResolveColumn(sf reflect.StructField) ColumnInfo
• type Rows

Functions

func All

func All[T any](rows Rows) ([]T, error)

All collects every row of rows as a typed T. It closes rows.

func AllKeyedReflect

func AllKeyedReflect(rows Rows, keyCol string, elem reflect.Type) (keys []any, items reflect.Value, err error)

AllKeyedReflect is the reflection twin of AllKeyed: it scans rows where keyCol carries an association key and the rest map to struct type elem, returning the keys aligned with a slice ([]elem) reflect.Value. Used by nested many-to-many eager loading. It closes rows.

func AllReflect

func AllReflect(rows Rows, elem reflect.Type) (reflect.Value, error)

AllReflect collects every row as a value of struct type elem, returning a reflect.Value of kind slice ([]elem). It is the reflection twin of All, used by the orm's nested loader where the target type is only known at runtime. It closes rows.

func AutoPrimaryKey

func AutoPrimaryKey[T any]() (string, bool)

AutoPrimaryKey returns the column name of T's primary key only when it is a single auto-increment column — the only case where an INSERT has a database-generated key to read back. A composite key, or a single caller-assigned key, returns false.

func Columns

func Columns[T any](skipAuto bool) []string

Columns returns the db column names of T in field order. When skipAuto is true, auto-increment primary-key columns are omitted (for INSERT).

func EmbeddedInfo

func EmbeddedInfo(sf reflect.StructField) (prefix string, embedded bool)

EmbeddedInfo reports whether a struct field should be flattened into the parent (an anonymous struct embed, or a named struct tagged `embedded`), and the column prefix to apply (from `embeddedPrefix`). A named struct WITHOUT the tag is a relation, not an embed.

func GoTypeName

func GoTypeName(t reflect.Type) string

GoTypeName maps a struct field's reflect.Type to a canonical Go type name, collapsing the database/sql.Null* wrappers and []byte. Shared by the orm schema builder and the gen codegen so the two agree on type names.

func Into

func Into[T any](rows Rows, v *T) error

Into scans the current row of rows into *v. The caller controls Next/Close. Used to read an INSERT ... RETURNING row back into the model.

func IsRelationField

func IsRelationField(ft reflect.Type) bool

IsRelationField reports whether a struct field is an association (a struct, a pointer-to-struct, or a slice-of-struct that is not time.Time and does not implement sql.Scanner/driver.Valuer) rather than a scalar column. The scanner skips these; the orm schema treats them as relations.

func Iter

func Iter[T any](rows Rows) iter.Seq2[T, error]

Iter streams rows as typed T values, lazily and early-stoppable. It streams rows lazily and closes them when the loop ends.

func ParseGormTag

func ParseGormTag(tag string) map[string]string

ParseGormTag parses a gorm struct tag (`;`-separated KEY or KEY:VALUE, keys case-insensitive) into a lowercased-key map. Bare keys map to "".

func ParseList

func ParseList(tag string) (name string, opts []string)

ParseList splits a comma-separated tag into its first token (the column name) and the remaining options.

func PrimaryKey

func PrimaryKey[T any]() (string, bool)

PrimaryKey returns the db column name of T's first primary-key column, if any.

func PrimaryKeys

func PrimaryKeys[T any]() []string

PrimaryKeys returns the db column names of T's primary key in declaration order (one element for a simple key, more for a composite key).

func RegisterPlural

func RegisterPlural(singular, plural string)

RegisterPlural registers an irregular plural for a single snake-case word, e.g. RegisterPlural("person", "people") — for names the rule-based pluralizer gets wrong. The user-facing entry point is orm.RegisterPlural.

func Scalars

func Scalars[V any](rows Rows) ([]V, error)

Scalars collects a single-column result as []V — the backing for query.Pluck. It scans through scanDest, so a bool column from a driver that returns an integer (modernc SQLite) still lands in a bool V. It closes rows.

func SetPluralTableNames

func SetPluralTableNames(on bool)

SetPluralTableNames toggles the pluralized default-table-name convention. This is the internal switch; the user-facing entry point is orm.UsePluralTableNames.

func SetPrimaryKey

func SetPrimaryKey[T any](v *T, id int64)

SetPrimaryKey assigns id into v's integer primary-key field (used after an INSERT when the backend returns a LastInsertId rather than RETURNING/OUTPUT).

func Snake

func Snake(s string) string

Snake exposes snake_case conversion for default table-name derivation.

func TableNameOf

func TableNameOf(t reflect.Type) string

TableNameOf returns t's TableName() method result if it has one (value or pointer receiver), else the snake_case of the type name — pluralized when the plural-table-names convention is enabled (orm.UsePluralTableNames).

func Values

func Values[T any](v *T, cols []string) []any

Values returns the field values of v for the given db columns, in order.

Types

type ColumnInfo

type ColumnInfo struct {
	Name string
	PK   bool
	Auto bool
	Skip bool
}

ColumnInfo is the column identity liteorm derives from a struct field's tags.

func ResolveColumn

func ResolveColumn(sf reflect.StructField) ColumnInfo

ResolveColumn derives a field's column identity from its tags, in precedence db > orm > gorm, falling back to snake_case. Shared by the scanner and the orm schema builder so both front-ends agree on column identity — a gorm-annotated model works in `query` and `orm` alike.

type Rows

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Columns() ([]string, error)
	Close() error
	Err() error
}

Rows is the minimal row cursor scan needs. liteorm.Rows satisfies it.