Help us shape the future of Go! Take the 2026 Go Developer Survey

read

package
v0.26.1 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: Apache-2.0 Imports: 18 Imported by: 5

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultMapperCache = NewMapperCache(8192)
View Source 
var ErrQueryOutsideScope = errors.New("read query is outside the recorded execution scope")
View Source 
var ErrRetryUnsafe = errors.New("read retry is unsafe after row materialization or with a caller-owned statement or transaction")

ErrRetryUnsafe marks a recoverable error that cannot be replayed without repeating row callbacks or replacing a caller-owned statement/transaction.

View Source 
var ErrTransactionCache = errors.New("read cache is unsafe with a caller-owned transaction")

ErrTransactionCache rejects cache-backed reads inside a caller-owned transaction: cached rows could hide that transaction's uncommitted writes.

Functions

func ShowSQL added in v0.5.4 

func ShowSQL(b bool)

Types

type CleanupError added in v0.26.1 

type CleanupError struct {
	Cause error
	// contains filtered or unexported fields
}

CleanupError identifies an actually returned close failure, preserving its original display text and causes. It grants no continuation authority.

func (*CleanupError) Error added in v0.26.1 

func (e *CleanupError) Error() string

func (*CleanupError) Unwrap added in v0.26.1 

func (e *CleanupError) Unwrap() error

type DisableMapperCache 

type DisableMapperCache bool

type Mapper 

type Mapper struct {
	// contains filtered or unexported fields
}

func NewMapper 

func NewMapper(fields []io.Field) *Mapper

func (*Mapper) MapToRow 

func (m *Mapper) MapToRow(target interface{}) ([]interface{}, error)

func (*Mapper) MapToSQLRow added in v0.7.0 

func (m *Mapper) MapToSQLRow(target interface{}) ([]interface{}, error)

type MapperCache 

type MapperCache struct {
	// contains filtered or unexported fields
}

func NewMapperCache 

func NewMapperCache(size int) *MapperCache

func (*MapperCache) Delete 

func (c *MapperCache) Delete(entry *MapperCacheEntry) error

func (*MapperCache) Get 

func (c *MapperCache) Get(structType reflect.Type, columns []io.Column, resolver io.Resolve) (*MapperCacheEntry, error)

func (*MapperCache) Put 

func (c *MapperCache) Put(entry *MapperCacheEntry, fields []io.Field)

type MapperCacheEntry 

type MapperCacheEntry struct {
	// contains filtered or unexported fields
}

func (*MapperCacheEntry) Fields 

func (e *MapperCacheEntry) Fields() []io.Field

func (*MapperCacheEntry) HasFields 

func (e *MapperCacheEntry) HasFields() bool

type NewRowMapper 

type NewRowMapper func(columns []io.Column, targetType reflect.Type, resolver io.Resolve, options ...Option) (RowMapper, error)

NewRowMapper new a row mapper function

type Option added in v0.16.0 

type Option func(o *options)

func WithCache added in v0.16.0 

func WithCache(aCache cache.Cache) Option

func WithCacheOnly added in v0.26.0 

func WithCacheOnly(only bool) Option

WithCacheOnly prohibits database fallback and requires cache.Lookup support.

func WithCacheRefresh added in v0.16.0 

func WithCacheRefresh(refresh cache.Refresh) Option

func WithCacheStats added in v0.16.0 

func WithCacheStats(stats *cache.Stats) Option

func WithCleanupErrorProvenance added in v0.26.1 

func WithCleanupErrorProvenance() Option

WithCleanupErrorProvenance preserves the causes of returned source-close failures. It does not observe discarded cleanup or certify transaction health.

func WithColumnsObserver added in v0.26.0 

func WithColumnsObserver(observer func([]io.Column) error) Option

WithColumnsObserver observes the native source schema before mapper creation, for both database reads and cache replay. It does not replace row mapping.

func WithDB added in v0.16.0 

func WithDB(db *sql.DB) Option

func WithDialect added in v0.16.0 

func WithDialect(dialect *info.Dialect) Option

func WithDisableMapperCache added in v0.16.0 

func WithDisableMapperCache(disable DisableMapperCache) Option

func WithInMatcher added in v0.16.0 

func WithInMatcher(inMatcher *cache.ParmetrizedQuery) Option

func WithInlineType added in v0.16.0 

func WithInlineType(inlineType bool) Option

func WithMapperCache added in v0.16.0 

func WithMapperCache(aCache *MapperCache) Option

func WithOptions added in v0.16.0 

func WithOptions(opts ...option.Option) Option

func WithQueryScope added in v0.26.0 

func WithQueryScope(scope *QueryScope) Option

func WithRetry added in v0.26.0 

func WithRetry(policy RetryPolicy) Option

func WithRowMapper added in v0.16.0 

func WithRowMapper(mapper NewRowMapper) Option

func WithSourceErrorProvenance added in v0.26.1 

func WithSourceErrorProvenance() Option

WithSourceErrorProvenance identifies terminal database prepare/query-start failures from QueryAll without changing retry predicate inputs. Iteration errors remain unclassified because Rows.Err can include implicit close errors.

func WithTx added in v0.26.1 

func WithTx(tx *sql.Tx) Option

WithTx prepares database reads on a caller-owned transaction. The caller commits or rolls it back; Reader never closes the transaction.

func WithUnmappedFn added in v0.16.0 

func WithUnmappedFn(fn io.Resolve) Option

type QueryScope added in v0.26.0 

type QueryScope struct {
	// contains filtered or unexported fields
}

QueryScope is an immutable set of previously executed SQL/argument identities. It validates newly built queries; it never executes stored SQL or owns results. Identity requires byte-exact SQL and equal JSON-encoded arguments. This is deliberately stricter than the native cache hash, which normalizes SQL case and whitespace. QueryScope guards recorded execution identity, not cache keys.

func NewQueryScope added in v0.26.0 

func NewQueryScope(queries []cache.ParmetrizedQuery) (*QueryScope, error)

func (*QueryScope) Validate added in v0.26.0 

func (s *QueryScope) Validate(SQL string, args []interface{}) error

type Reader 

type Reader struct {
	// contains filtered or unexported fields
}

Reader represents generic query reader

func New 

func New(ctx context.Context, db *sql.DB, query string, newRow func() interface{}, options ...Option) (*Reader, error)

New creates a records to a structs reader

func NewMap 

func NewMap(ctx context.Context, db *sql.DB, query string, options ...Option) (*Reader, error)

NewMap creates records to map reader

func NewSlice 

func NewSlice(ctx context.Context, db *sql.DB, query string, columns int, options ...Option) (*Reader, error)

NewSlice create records to a slice reader

func NewStmt 

func NewStmt(stmt *sql.Stmt, newRow func() interface{}, opts ...Option) *Reader

NewStmt creates a statement reader

func (*Reader) QueryAll 

func (r *Reader) QueryAll(ctx context.Context, emit func(interface{}) error, args ...interface{}) error

QueryAll retains one budget across prepare, query-start and pre-row failures. There is deliberately no collector reset: even allocation/schema callbacks can have effects, so entering row materialization ends replay eligibility.

func (*Reader) QueryAllWithMap 

func (r *Reader) QueryAllWithMap(ctx context.Context, emit func(row map[string]interface{}) error, args ...interface{}) error

QueryAllWithMap query all with a map

func (*Reader) QueryAllWithSlice 

func (r *Reader) QueryAllWithSlice(ctx context.Context, emit func(row []interface{}) error, args ...interface{}) error

QueryAllWithSlice query all with a slice

func (*Reader) QuerySingle 

func (r *Reader) QuerySingle(ctx context.Context, emit func(row interface{}) error, args ...interface{}) error

QuerySingle returns single row

func (*Reader) ReadAll 

func (r *Reader) ReadAll(ctx context.Context, rows *sql.Rows, emit func(row interface{}) error, options ...option.Option) error

ReadAll read all

Example 
package main

import (
	"context"
	"database/sql"
	"github.com/viant/sqlx/io/read"
	"log"
)

func main() {
	dsn := ""
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		log.Fatalln(err)
	}
	ctx := context.Background()
	type Foo struct {
		ID     int
		Name   string
		Active bool
	}
	newFoo := func() interface{} { return &Foo{} }
	reader, err := read.New(ctx, db, "SELECT * FROM foo", newFoo)
	if err != nil {
		log.Fatalln(err)
	}
	var foos []*Foo
	reader.QueryAll(ctx, func(row interface{}) error {
		foo := row.(*Foo)
		foos = append(foos, foo)
		return nil
	}, nil)
	log.Printf("read foos: %+v\n", foos)
}

func (*Reader) Stmt 

func (r *Reader) Stmt() *sql.Stmt

Stmt returns *sql.Stmt associated with Reader

type RetryPolicy added in v0.26.0 

type RetryPolicy struct {
	Attempts    int
	Recoverable func(error) bool
	Reconnect   func(context.Context) (*sql.DB, error)
}

RetryPolicy applies only to QueryAll's database reads. Attempts includes the initial attempt. Reconnect resolves the same configured source; it must not close the previous pool or replace a caller's transaction.

type RowMapper 

type RowMapper func(target interface{}) ([]interface{}, error)

RowMapper represents a target values mapped to pointer of slice

func GenericRowMapper 

func GenericRowMapper(columns []io.Column) (RowMapper, error)

GenericRowMapper creates a new row mapper for supplied slice or map type

func NewSQLStructMapper added in v0.7.0 

func NewSQLStructMapper(columns []io.Column, recordType reflect.Type, resolver io.Resolve, options ...Option) (RowMapper, error)

NewSQLStructMapper creates a new record mapper for supplied struct and prepares them to scan / send values with sql.DB

func NewStructMapper 

func NewStructMapper(columns []io.Column, recordType reflect.Type, resolver io.Resolve, options ...Option) (RowMapper, error)

NewStructMapper creates a new record mapper for supplied struct type

type Rows 

type Rows struct {
	// contains filtered or unexported fields
}

func NewRows 

func NewRows(rows *sql.Rows, cache cache.Cache, entry *cache.Entry, matcher *cache.ParmetrizedQuery) (*Rows, error)

func (*Rows) CheckType 

func (c *Rows) CheckType(ctx context.Context, values []interface{}) (bool, error)

func (*Rows) Close 

func (c *Rows) Close(ctx context.Context) error

func (*Rows) ConvertColumns 

func (c *Rows) ConvertColumns() ([]io.Column, error)

func (*Rows) Err added in v0.14.0 

func (c *Rows) Err() error

func (*Rows) Next 

func (c *Rows) Next() bool

func (*Rows) Rollback 

func (c *Rows) Rollback(ctx context.Context) error

func (*Rows) Scanner 

func (c *Rows) Scanner(ctx context.Context) cache.ScannerFn

func (*Rows) XTypes 

func (c *Rows) XTypes() []*xunsafe.Type

type Segment 

type Segment struct {
	// contains filtered or unexported fields
}

type SkipError 

type SkipError string

func (SkipError) Error 

func (s SkipError) Error() string

type SourceError added in v0.26.1 

type SourceError struct {
	// contains filtered or unexported fields
}

SourceError identifies a terminal database prepare or query-start failure. Error retains the original private diagnostic; callers must not expose it as safe public text. Stage is a fixed classification, not SQL or driver text. A zero value carries no provenance. Instances are issued only by QueryAll.

func (*SourceError) Error added in v0.26.1 

func (e *SourceError) Error() string

func (*SourceError) Stage added in v0.26.1 

func (e *SourceError) Stage() string

func (*SourceError) Unwrap added in v0.26.1 

func (e *SourceError) Unwrap() error

Source Files

View all Source files

Directories

Path Synopsis
aerospike
afs
ast
ast/matcher
hash

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.