Documentation
¶
Overview ¶
Package sqlbind provides generated, reflection-free database/sql row mapping.
Index ¶
- Variables
- func AppendValues[T any](b *Builder, values []T) error
- func Bool(row Row, column string) (bool, error)
- func Float64(row Row, column string) (float64, error)
- func ForEach(rows Rows, fn func(Row) error) error
- func Int(row Row, column string) (int, error)
- func Int64(row Row, column string) (int64, error)
- func Key(row Row, column string) (key string, present bool, err error)
- func RegisterScanRows[T any](fn func(Rows) ([]T, error))
- func RequiredKey(row Row, column string) (string, error)
- func ScanOptionalURL(target **url.URL) optionalURLTarget
- func ScanRows[T any](rows Rows) ([]T, error)
- func ScanURL(target *url.URL) urlTarget
- func String(row Row, column string) (string, error)
- func WithSQLExecutor(ctx context.Context, executor SQLExecutor, options ...ExecutorOption) context.Context
- type Builder
- type Execer
- type ExecutorOption
- type PlaceholderStyle
- type Querier
- type Row
- type Rows
- type RowsQuerier
- type SQLExecutor
- type Statement
- type UnimplementedQuerier
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyValueList = errors.New("tinybind SQL: an expanded value list cannot be empty")
ErrEmptyValueList reports that an expanded value list had no elements, which would produce invalid SQL such as "IN ()".
var ErrNoSQLExecutor = errors.New("sqlbind: no SQL executor in context")
ErrNoSQLExecutor reports that a Context does not contain a database executor. It is returned instead of panicking so generated Context wrappers remain ordinary error-returning APIs.
var ErrReadOnlyExecutor = errors.New("sqlbind: SQL executor in context is read-only")
ErrReadOnlyExecutor reports that a write statement resolved an executor the caller declared read-only. It is returned before the statement is built, so a misrouted write fails deterministically instead of depending on whether the connection happens to reach a read replica.
Functions ¶
func AppendValues ¶ added in v0.1.16
AppendValues expands a slice into a comma-separated placeholder list. It is a package function because a Go method cannot introduce its own type parameter.
func RegisterScanRows ¶
RegisterScanRows registers a generated SQL tree scanner for T.
func RequiredKey ¶
RequiredKey is Key with NULL rejected for a root object.
func ScanOptionalURL ¶ added in v0.2.2
ScanOptionalURL is ScanURL for an optional field, where SQL NULL leaves a nil pointer instead of failing.
func ScanURL ¶ added in v0.2.2
ScanURL adapts a url.URL field to Rows.Scan. Generated code passes it in place of the field address, so the column is parsed rather than assigned.
func WithSQLExecutor ¶ added in v0.1.6
func WithSQLExecutor(ctx context.Context, executor SQLExecutor, options ...ExecutorOption) context.Context
WithSQLExecutor returns a child Context containing a database executor. Framework transaction middleware can store a *sql.Tx for generated <Component>Context wrappers to resolve.
Types ¶
type Builder ¶ added in v0.1.16
Builder accumulates SQL text and its bound arguments. Generated statement builders write into it; template authors never construct placeholders themselves.
func NewBuilder ¶ added in v0.1.16
func NewBuilder(style PlaceholderStyle) Builder
NewBuilder returns a Builder emitting placeholders in the given style.
type Execer ¶ added in v0.1.16
Execer is the minimal executor a generated sql.exec component needs. It is satisfied by *sql.DB, *sql.Conn, and *sql.Tx.
type ExecutorOption ¶ added in v0.2.1
type ExecutorOption func(*sqlExecutorEntry)
ExecutorOption configures how a stored executor may be used.
func AsReadOnly ¶ added in v0.2.1
func AsReadOnly() ExecutorOption
AsReadOnly marks the stored executor as read-only, so a generated write statement resolving it fails with ErrReadOnlyExecutor. Use it for a handle pointing at a read replica, or for a transaction begun with sql.TxOptions{ReadOnly: true}.
type PlaceholderStyle ¶ added in v0.1.16
type PlaceholderStyle int
PlaceholderStyle selects the bind-placeholder syntax of the target dialect. Generated code passes the style chosen at generation time, so one Builder implementation serves every dialect.
const ( // Dollar emits PostgreSQL-style $1, $2, ... placeholders. Dollar PlaceholderStyle = iota // Question emits ?-style placeholders. Question )
type Querier ¶ added in v0.1.16
Querier is the minimal executor a generated row-returning component needs. It is satisfied by *sql.DB, *sql.Conn, and *sql.Tx. Its QueryContext must return the concrete *sql.Rows because those types do, and Go interface satisfaction is exact; a backend outside database/sql cannot construct a *sql.Rows, so it additionally implements RowsQuerier and embeds UnimplementedQuerier.
type Rows ¶ added in v0.4.2
type Rows interface {
Next() bool
Scan(dest ...any) error
Err() error
Close() error
Columns() ([]string, error)
}
Rows is the row cursor generated code and the sqlbind scanners consume. It is satisfied by *sql.Rows unchanged; a non-database/sql backend such as pgx returns its own implementation (wrapping Close to add the error return, and deriving Columns from its field descriptions). Columns is required by ForEach, which builds column-indexed Row maps; generated statement bodies use only Next, Scan, Err, and Close.
func Query ¶ added in v0.4.2
Query executes a row-returning statement through db. A backend implementing RowsQuerier is queried through it; otherwise db is a database/sql handle and its *sql.Rows is returned as Rows. Generated row-returning statements call this instead of db.QueryContext directly, so one generated body serves both kinds of backend.
type RowsQuerier ¶ added in v0.4.2
type RowsQuerier interface {
QueryRows(ctx context.Context, query string, args ...any) (Rows, error)
}
RowsQuerier is the driver-agnostic query surface a non-database/sql executor implements alongside Querier. Query prefers it over Querier.QueryContext, the same way io.Copy prefers io.ReaderFrom: the optional interface upgrades the backend without forking the generated code path or the executor parameter type.
type SQLExecutor ¶ added in v0.1.6
SQLExecutor is implemented by *sql.DB, *sql.Conn, and *sql.Tx. It combines the two minimal interfaces generated code takes, so one Context value serves both mutating and row-returning components.
func SQLExecutorFromContext ¶ added in v0.1.6
func SQLExecutorFromContext(ctx context.Context) (SQLExecutor, error)
SQLExecutorFromContext returns the executor installed by WithSQLExecutor. It is the resolver generated read statements use, and it accepts a read-only executor.
func WriteExecutorFromContext ¶ added in v0.2.1
func WriteExecutorFromContext(ctx context.Context, statement string) (SQLExecutor, error)
WriteExecutorFromContext is the resolver generated write statements use. It rejects an executor stored with AsReadOnly, naming the statement so the error identifies which one was misrouted.
type Statement ¶ added in v0.1.16
Statement is the low-level result of a generated SQL component: the compiled SQL text plus its bound arguments, with no database handle attached.
type UnimplementedQuerier ¶ added in v0.4.2
type UnimplementedQuerier struct{}
UnimplementedQuerier satisfies Querier's QueryContext with an error, for embedding in an executor whose real query path is QueryRows. Query never reaches it when RowsQuerier is implemented; it exists so a custom backend can satisfy Querier without being able to construct a *sql.Rows.
func (UnimplementedQuerier) QueryContext ¶ added in v0.4.2
QueryContext always fails: a backend embedding UnimplementedQuerier queries through RowsQuerier. Reaching this method means the executor was used where sqlbind.Query cannot dispatch, such as pre-Rows generated code.
Source Files