package sqlx

import "zgo.at/zdb/internal/sqlx"

Index ¶

• Variables
• func GetContext(ctx context.Context, q Queryer, dest any, query string, args ...any) error
• func In(query string, args ...any) (string, []any, error)
• func MapScan(r ColScanner, dest map[string]any) error
• func Named(query string, arg any) (string, []any, error)
• func NamedExec(ctx context.Context, e Ext, query string, arg any) (sql.Result, error)
• func PlaceholderRegister(driver string, style PlaceholderStyle)
• func Rebind(style PlaceholderStyle, query string) string
• func SelectContext(ctx context.Context, q Queryer, dest any, query string, args ...any) error
• func SliceScan(r ColScanner) ([]any, error)
• func StructScan(rows rowsi, dest any) error
• type ColScanner
• type Conn
• func (c *Conn) BeginTxx(ctx context.Context, opts *sql.TxOptions) (*Tx, error)
• func (c *Conn) GetContext(ctx context.Context, dest any, query string, args ...any) error
• func (c *Conn) QueryRowxContext(ctx context.Context, query string, args ...any) *Row
• func (c *Conn) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)
• func (c *Conn) Rebind(query string) string
• func (c *Conn) SelectContext(ctx context.Context, dest any, query string, args ...any) error
• type DB
• func Connect(ctx context.Context, driverName, dataSourceName string) (*DB, error)
• func NewDb(db *sql.DB, driverName string) *DB
• func Open(driverName, dataSourceName string) (*DB, error)
• func (db *DB) BeginTxx(ctx context.Context, opts *sql.TxOptions) (*Tx, error)
• func (db *DB) Beginx() (*Tx, error)
• func (db *DB) BindNamed(query string, arg any) (string, []any, error)
• func (db *DB) Connx(ctx context.Context) (*Conn, error)
• func (db *DB) DriverName() string
• func (db *DB) GetContext(ctx context.Context, dest any, query string, args ...any) error
• func (db *DB) MapperFunc(mf func(string) string)
• func (db *DB) NamedExec(ctx context.Context, query string, arg any) (sql.Result, error)
• func (db *DB) NamedQuery(ctx context.Context, query string, arg any) (*Rows, error)
• func (db *DB) QueryRowxContext(ctx context.Context, query string, args ...any) *Row
• func (db *DB) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)
• func (db *DB) Rebind(query string) string
• func (db *DB) SelectContext(ctx context.Context, dest any, query string, args ...any) error
• type ErrMissingField
• func (e ErrMissingField) Error() string
• type Ext
• type PlaceholderStyle
• func Placeholder(driver string) PlaceholderStyle
• type Queryer
• type Row
• func (r *Row) ColumnTypes() ([]*sql.ColumnType, error)
• func (r *Row) Columns() ([]string, error)
• func (r *Row) Err() error
• func (r *Row) MapScan(dest map[string]any) error
• func (r *Row) Scan(dest ...any) error
• func (r *Row) SliceScan() ([]any, error)
• func (r *Row) StructScan(dest any) error
• type Rows
• func NamedQuery(ctx context.Context, e Ext, query string, arg any) (*Rows, error)
• func (r *Rows) MapScan(dest map[string]any) error
• func (r *Rows) SliceScan() ([]any, error)
• func (r *Rows) StructScan(dest any) error
• type Tx
• func (tx *Tx) BindNamed(query string, arg any) (string, []any, error)
• func (tx *Tx) DriverName() string
• func (tx *Tx) GetContext(ctx context.Context, dest any, query string, args ...any) error
• func (tx *Tx) NamedExec(ctx context.Context, query string, arg any) (sql.Result, error)
• func (tx *Tx) QueryRowxContext(ctx context.Context, query string, args ...any) *Row
• func (tx *Tx) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)
• func (tx *Tx) Rebind(query string) string
• func (tx *Tx) SelectContext(ctx context.Context, dest any, query string, args ...any) error

Variables ¶

var NameMapper = strings.ToLower

NameMapper is used to map column names to struct field names. By default, it uses strings.ToLower to lowercase struct field names. It can be set to whatever you want, but it is encouraged to be set before sqlx is used as name-to-field mappings are cached after first use on a type.

Functions ¶

func GetContext ¶

func GetContext(ctx context.Context, q Queryer, dest any, query string, args ...any) error

GetContext does a QueryRow using the provided Queryer, and scans the resulting row to dest. If dest is scannable, the result must only have one column. Otherwise, StructScan is used. Get will return sql.ErrNoRows like row.Scan would. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func In ¶

func In(query string, args ...any) (string, []any, error)

In expands slice values in args, returning the modified query string and a new arg list that can be executed by a database.

The query should use the "?" placeholder style, and the return value the return value also uses the "?" style.

func MapScan ¶

func MapScan(r ColScanner, dest map[string]any) error

MapScan scans a single Row into the dest map[string]any.

Use this to get results for SQL that might not be under your control (for instance, if you're building an interface for an SQL server that executes SQL from input).

Please do not use this as a primary interface! This will modify the map sent to it in place, so reuse the same map with care. Columns which occur more than once in the result will overwrite each other!

func Named ¶

func Named(query string, arg any) (string, []any, error)

Named takes a query using named parameters and an argument and returns a new query with a list of args that can be executed by a database. The return value uses the `?` bindvar.

func NamedExec ¶

func NamedExec(ctx context.Context, e Ext, query string, arg any) (sql.Result, error)

NamedExec uses BindStruct to get a query executable by the driver and then runs Exec on the result. Returns an error from the binding or the query execution itself.

func PlaceholderRegister ¶

func PlaceholderRegister(driver string, style PlaceholderStyle)

PlaceholderRegister sets the placeholder style for a SQL driver.

func Rebind ¶

func Rebind(style PlaceholderStyle, query string) string

Rebind a query from the default placeholder style (PlaceholderQuestion) to the target placeholder style.

func SelectContext ¶

func SelectContext(ctx context.Context, q Queryer, dest any, query string, args ...any) error

SelectContext executes a query using the provided Queryer, and StructScans each row into dest, which must be a slice. If the slice elements are scannable, then the result set must have only one column. Otherwise, StructScan is used. The *sql.Rows are closed automatically. Any placeholder parameters are replaced with supplied args.

func SliceScan ¶

func SliceScan(r ColScanner) ([]any, error)

SliceScan a row, returning a []any with values similar to MapScan. This function is primarily intended for use where the number of columns is not known. Because you can pass an []any directly to Scan, it's recommended that you do that as it will not have to allocate new slices per row.

func StructScan ¶

func StructScan(rows rowsi, dest any) error

StructScan all rows from an sql.Rows or an sqlx.Rows into the dest slice. StructScan will scan in the entire rows result, so if you do not want to allocate structs for the entire result, use Queryx and see sqlx.Rows.StructScan. If rows is sqlx.Rows, it will use its mapper, otherwise it will use the default.

Types ¶

type ColScanner ¶

type ColScanner interface {
	Columns() ([]string, error)
	Scan(dest ...any) error
	Err() error
}

ColScanner is an interface used by MapScan and SliceScan

type Conn ¶

type Conn struct {
	*sql.Conn

	Mapper *reflectx.Mapper
	// contains filtered or unexported fields
}

Conn is a wrapper around sql.Conn with extra functionality

func (*Conn) BeginTxx ¶

func (c *Conn) BeginTxx(ctx context.Context, opts *sql.TxOptions) (*Tx, error)

BeginTxx begins a transaction and returns an *sqlx.Tx instead of an *sql.Tx.

The provided context is used until the transaction is committed or rolled back. If the context is canceled, the sql package will roll back the transaction. Tx.Commit will return an error if the context provided to Beginx is canceled.

func (*Conn) GetContext ¶

func (c *Conn) GetContext(ctx context.Context, dest any, query string, args ...any) error

GetContext using this Conn. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func (*Conn) QueryRowxContext ¶

func (c *Conn) QueryRowxContext(ctx context.Context, query string, args ...any) *Row

QueryRowxContext queries the database and returns an *sqlx.Row. Any placeholder parameters are replaced with supplied args.

func (*Conn) QueryxContext ¶

func (c *Conn) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)

QueryxContext queries the database and returns an *sqlx.Rows. Any placeholder parameters are replaced with supplied args.

func (*Conn) Rebind ¶

func (c *Conn) Rebind(query string) string

Rebind a query within a Conn's bindvar type.

func (*Conn) SelectContext ¶

func (c *Conn) SelectContext(ctx context.Context, dest any, query string, args ...any) error

SelectContext using this Conn. Any placeholder parameters are replaced with supplied args.

type DB ¶

type DB struct {
	*sql.DB

	Mapper *reflectx.Mapper
	// contains filtered or unexported fields
}

DB is a wrapper around sql.DB which keeps track of the driverName upon Open, used mostly to automatically bind named queries using the right bindvars.

func Connect ¶

func Connect(ctx context.Context, driverName, dataSourceName string) (*DB, error)

Connect to a database and verify with a ping.

func NewDb ¶

func NewDb(db *sql.DB, driverName string) *DB

NewDb returns a new sqlx DB wrapper for a pre-existing *sql.DB. The driverName of the original database is required for named query support.

func Open ¶

func Open(driverName, dataSourceName string) (*DB, error)

Open is the same as sql.Open, but returns an *sqlx.DB instead.

func (*DB) BeginTxx ¶

func (db *DB) BeginTxx(ctx context.Context, opts *sql.TxOptions) (*Tx, error)

BeginTxx begins a transaction and returns an *sqlx.Tx instead of an *sql.Tx.

The provided context is used until the transaction is committed or rolled back. If the context is canceled, the sql package will roll back the transaction. Tx.Commit will return an error if the context provided to Beginx is canceled.

func (*DB) Beginx ¶

func (db *DB) Beginx() (*Tx, error)

Beginx begins a transaction and returns an *sqlx.Tx instead of an *sql.Tx.

func (*DB) BindNamed ¶

func (db *DB) BindNamed(query string, arg any) (string, []any, error)

BindNamed binds a query using the DB driver's bindvar type.

func (*DB) Connx ¶

func (db *DB) Connx(ctx context.Context) (*Conn, error)

Connx returns an *sqlx.Conn instead of an *sql.Conn.

func (*DB) DriverName ¶

func (db *DB) DriverName() string

DriverName returns the driverName passed to the Open function for this DB.

func (*DB) GetContext ¶

func (db *DB) GetContext(ctx context.Context, dest any, query string, args ...any) error

GetContext using this DB. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func (*DB) MapperFunc ¶

func (db *DB) MapperFunc(mf func(string) string)

MapperFunc sets a new mapper for this db using the default sqlx struct tag and the provided mapper function.

func (*DB) NamedExec ¶

func (db *DB) NamedExec(ctx context.Context, query string, arg any) (sql.Result, error)

NamedExec using this DB. Any named placeholder parameters are replaced with fields from arg.

func (*DB) NamedQuery ¶

func (db *DB) NamedQuery(ctx context.Context, query string, arg any) (*Rows, error)

NamedQuery using this DB. Any named placeholder parameters are replaced with fields from arg.

func (*DB) QueryRowxContext ¶

func (db *DB) QueryRowxContext(ctx context.Context, query string, args ...any) *Row

QueryRowxContext queries the database and returns an *sqlx.Row. Any placeholder parameters are replaced with supplied args.

func (*DB) QueryxContext ¶

func (db *DB) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)

QueryxContext queries the database and returns an *sqlx.Rows. Any placeholder parameters are replaced with supplied args.

func (*DB) Rebind ¶

func (db *DB) Rebind(query string) string

Rebind transforms a query from QUESTION to the DB driver's bindvar type.

func (*DB) SelectContext ¶

func (db *DB) SelectContext(ctx context.Context, dest any, query string, args ...any) error

SelectContext using this DB. Any placeholder parameters are replaced with supplied args.

type ErrMissingField ¶

type ErrMissingField struct{ Column, Type string }

func (ErrMissingField) Error ¶

func (e ErrMissingField) Error() string

type Ext ¶

type Ext interface {
	Queryer

	DriverName() string
	Rebind(string) string
	BindNamed(string, any) (string, []any, error)
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

Ext is a union interface which can bind, query, and exec, used by NamedQuery and NamedExec.

type PlaceholderStyle ¶

type PlaceholderStyle uint8

PlaceholderStyle controls which placeholders to use parametrized queries.

const (
	PlaceholderUnknown  PlaceholderStyle = iota // Fall back to PlaceholderQuestion
	PlaceholderQuestion                         // ?
	PlaceholderDollar                           // $1, $2
	PlaceholderNamed                            // :arg1, :arg2
	PlaceholderAt                               // @p1, @p2
)

Placeholders styles we know about.

func Placeholder ¶

func Placeholder(driver string) PlaceholderStyle

Placeholder returns the placeholder style for a SQL driver.

type Queryer ¶

type Queryer interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)
	QueryRowxContext(ctx context.Context, query string, args ...any) *Row
}

Queryer is an interface used by Get and Select

type Row ¶

type Row struct {
	Mapper *reflectx.Mapper
	// contains filtered or unexported fields
}

Row is a reimplementation of sql.Row in order to gain access to the underlying sql.Rows.Columns() data, necessary for StructScan.

func (*Row) ColumnTypes ¶

func (r *Row) ColumnTypes() ([]*sql.ColumnType, error)

ColumnTypes returns the underlying sql.Rows.ColumnTypes(), or the deferred error

func (*Row) Columns ¶

func (r *Row) Columns() ([]string, error)

Columns returns the underlying sql.Rows.Columns(), or the deferred error usually returned by Row.Scan()

func (*Row) Err ¶

func (r *Row) Err() error

Err returns the error encountered while scanning.

func (*Row) MapScan ¶

func (r *Row) MapScan(dest map[string]any) error

MapScan using this Rows.

func (*Row) Scan ¶

func (r *Row) Scan(dest ...any) error

Scan is a fixed implementation of sql.Row.Scan, which does not discard the underlying error from the internal rows object if it exists.

func (*Row) SliceScan ¶

func (r *Row) SliceScan() ([]any, error)

SliceScan using this Rows.

func (*Row) StructScan ¶

func (r *Row) StructScan(dest any) error

StructScan a single Row into dest.

type Rows ¶

type Rows struct {
	*sql.Rows
	Mapper *reflectx.Mapper
	// contains filtered or unexported fields
}

Rows is a wrapper around sql.Rows which caches costly reflect operations during a looped StructScan

func NamedQuery ¶

func NamedQuery(ctx context.Context, e Ext, query string, arg any) (*Rows, error)

NamedQuery binds a named query and then runs Query on the result using the provided Ext (sqlx.Tx, sqlx.Db).

It works with both structs and with map[string]any types.

func (*Rows) MapScan ¶

func (r *Rows) MapScan(dest map[string]any) error

MapScan using this Rows.

func (*Rows) SliceScan ¶

func (r *Rows) SliceScan() ([]any, error)

SliceScan using this Rows.

func (*Rows) StructScan ¶

func (r *Rows) StructScan(dest any) error

StructScan is like sql.Rows.Scan, but scans a single Row into a single Struct. Use this and iterate over Rows manually when the memory load of Select() might be prohibitive. *Rows.StructScan caches the reflect work of matching up column positions to fields to avoid that overhead per scan, which means it is not safe to run StructScan on the same Rows instance with different struct types.

type Tx ¶

type Tx struct {
	*sql.Tx

	Mapper *reflectx.Mapper
	// contains filtered or unexported fields
}

Tx is an sqlx wrapper around sql.Tx with extra functionality

func (*Tx) BindNamed ¶

func (tx *Tx) BindNamed(query string, arg any) (string, []any, error)

BindNamed binds a query within a transaction's bindvar type.

func (*Tx) DriverName ¶

func (tx *Tx) DriverName() string

DriverName returns the driverName used by the DB which began this transaction.

func (*Tx) GetContext ¶

func (tx *Tx) GetContext(ctx context.Context, dest any, query string, args ...any) error

GetContext within a transaction and context. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func (*Tx) NamedExec ¶

func (tx *Tx) NamedExec(ctx context.Context, query string, arg any) (sql.Result, error)

NamedExec using this Tx. Any named placeholder parameters are replaced with fields from arg.

func (*Tx) QueryRowxContext ¶

func (tx *Tx) QueryRowxContext(ctx context.Context, query string, args ...any) *Row

QueryRowxContext within a transaction and context. Any placeholder parameters are replaced with supplied args.

func (*Tx) QueryxContext ¶

func (tx *Tx) QueryxContext(ctx context.Context, query string, args ...any) (*Rows, error)

QueryxContext within a transaction and context. Any placeholder parameters are replaced with supplied args.

func (*Tx) Rebind ¶

func (tx *Tx) Rebind(query string) string

Rebind a query within a transaction's bindvar type.

func (*Tx) SelectContext ¶

func (tx *Tx) SelectContext(ctx context.Context, dest any, query string, args ...any) error

SelectContext within a transaction and context. Any placeholder parameters are replaced with supplied args.

Source Files ¶

bind.go iface.go named.go scan.go sqlx.go

Directories ¶