Documentation
¶
Overview ¶
Package SQLX provides general purpose extensions to database/sql.t
sqlx is intended to seamlessly wrap database/sql and provide convenience methods which are useful in the development of database driven applications. None of the underlying database/sql methods are changed, instead all extended behavior is implemented through new methods defined on wrapper types.
sqlx adds struct scanning, named queries, query rebinding between drivers, convenient shorthand for common error handling, from-file query execution, and more.
Index ¶
- Constants
- Variables
- func BaseSliceType(t reflect.Type) (reflect.Type, error)
- func BaseStructType(t reflect.Type) (reflect.Type, error)
- func BindMap(bindType int, query string, args map[string]interface{}) (string, []interface{}, error)
- func BindStruct(bindType int, query string, arg interface{}) (string, []interface{}, error)
- func BindType(driverName string) int
- func Execf(e Execer, query string, args ...interface{}) sql.Result
- func Execl(e Execer, query string, args ...interface{}) sql.Result
- func Execp(e Execer, query string, args ...interface{}) sql.Result
- func Execv(e Execer, query string, args ...interface{}) (sql.Result, error)
- func Get(q Queryer, dest interface{}, query string, args ...interface{}) error
- func LoadFile(e Execer, path string) (*sql.Result, error)
- func MapScan(r ColScanner, dest map[string]interface{}) error
- func MustExec(e Execer, query string, args ...interface{}) sql.Result
- func NamedExec(e Ext, query string, arg interface{}) (sql.Result, error)
- func NamedExecMap(e Ext, query string, argmap map[string]interface{}) (sql.Result, error)
- func Rebind(bindType int, query string) string
- func Select(q Queryer, dest interface{}, query string, args ...interface{}) error
- func Selectf(q Queryer, dest interface{}, query string, args ...interface{})
- func Selectv(q Queryer, dest interface{}, query string, args ...interface{}) error
- func SliceScan(r ColScanner) ([]interface{}, error)
- func StructScan(rows *sql.Rows, dest interface{}) error
- type Binder
- type ColScanner
- type DB
- func (db *DB) Beginx() (*Tx, error)
- func (db *DB) BindMap(query string, argmap map[string]interface{}) (string, []interface{}, error)
- func (db *DB) BindStruct(query string, arg interface{}) (string, []interface{}, error)
- func (db *DB) DriverName() string
- func (db *DB) Execf(query string, args ...interface{}) sql.Result
- func (db *DB) Execl(query string, args ...interface{}) sql.Result
- func (db *DB) Execp(query string, args ...interface{}) sql.Result
- func (db *DB) Execv(query string, args ...interface{}) (sql.Result, error)
- func (db *DB) Get(dest interface{}, query string, args ...interface{}) error
- func (db *DB) LoadFile(path string) (*sql.Result, error)
- func (db *DB) MustBegin() *Tx
- func (db *DB) MustExec(query string, args ...interface{}) sql.Result
- func (db *DB) NamedExec(query string, arg interface{}) (sql.Result, error)
- func (db *DB) NamedExecMap(query string, argmap map[string]interface{}) (sql.Result, error)
- func (db *DB) NamedQuery(query string, arg interface{}) (*Rows, error)
- func (db *DB) NamedQueryMap(query string, argmap map[string]interface{}) (*Rows, error)
- func (db *DB) Preparex(query string) (*Stmt, error)
- func (db *DB) QueryRowx(query string, args ...interface{}) *Row
- func (db *DB) Queryx(query string, args ...interface{}) (*Rows, error)
- func (db *DB) Rebind(query string) string
- func (db *DB) Select(dest interface{}, query string, args ...interface{}) error
- func (db *DB) Selectf(dest interface{}, query string, args ...interface{})
- func (db *DB) Selectv(dest interface{}, query string, args ...interface{}) error
- type Execer
- type Ext
- type Preparer
- type Queryer
- type Row
- type Rows
- type Stmt
- func (s *Stmt) Execf(args ...interface{}) sql.Result
- func (s *Stmt) Execl(args ...interface{}) sql.Result
- func (s *Stmt) Execp(args ...interface{}) sql.Result
- func (s *Stmt) Execv(args ...interface{}) (sql.Result, error)
- func (s *Stmt) Get(dest interface{}, args ...interface{}) error
- func (s *Stmt) MustExec(args ...interface{}) sql.Result
- func (s *Stmt) QueryRowx(args ...interface{}) *Row
- func (s *Stmt) Queryx(args ...interface{}) (*Rows, error)
- func (s *Stmt) Select(dest interface{}, args ...interface{}) error
- func (s *Stmt) Selectf(dest interface{}, args ...interface{})
- func (s *Stmt) Selectv(dest interface{}, args ...interface{}) error
- type Tx
- func (tx *Tx) BindMap(query string, argmap map[string]interface{}) (string, []interface{}, error)
- func (tx *Tx) BindStruct(query string, arg interface{}) (string, []interface{}, error)
- func (tx *Tx) DriverName() string
- func (tx *Tx) Execf(query string, args ...interface{}) sql.Result
- func (tx *Tx) Execl(query string, args ...interface{}) sql.Result
- func (tx *Tx) Execp(query string, args ...interface{}) sql.Result
- func (tx *Tx) Execv(query string, args ...interface{}) (sql.Result, error)
- func (tx *Tx) Get(dest interface{}, query string, args ...interface{}) error
- func (tx *Tx) LoadFile(path string) (*sql.Result, error)
- func (tx *Tx) MustExec(query string, args ...interface{}) sql.Result
- func (tx *Tx) NamedExec(query string, arg interface{}) (sql.Result, error)
- func (tx *Tx) NamedQuery(query string, arg interface{}) (*Rows, error)
- func (tx *Tx) Preparex(query string) (*Stmt, error)
- func (tx *Tx) QueryRowx(query string, args ...interface{}) *Row
- func (tx *Tx) Queryx(query string, args ...interface{}) (*Rows, error)
- func (tx *Tx) Rebind(query string) string
- func (tx *Tx) Select(dest interface{}, query string, args ...interface{}) error
- func (tx *Tx) Selectf(dest interface{}, query string, args ...interface{})
- func (tx *Tx) Selectv(dest interface{}, query string, args ...interface{}) error
- func (tx *Tx) Stmtx(stmt interface{}) *Stmt
Constants ¶
const ( UNKNOWN = iota QUESTION DOLLAR )
Bindvar types supported by sqlx's Rebind & BindMap/Struct functions.
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 field-to-name mappings are cached after first use on a type.
Functions ¶
func BaseSliceType ¶
Return the type for a slice, dereferencing it if it is a pointer. Returns an error if the destination is not a slice or a pointer to a slice.
func BaseStructType ¶
Return the type of a struct, dereferencing it if it is a pointer. Returns an error if the destination is not a struct or a pointer to a struct.
func BindMap ¶
func BindMap(bindType int, query string, args map[string]interface{}) (string, []interface{}, error)
Bind a named parameter query with a map of arguments.
func BindStruct ¶
Bind a named parameter query with fields from a struct argument. The rules for binding field names to parameter names follow the same conventions as for StructScan, including obeying the `db` struct tags.
func Execf ¶
Execf (fatal) runs Exec on the query and args and uses log.Fatal to print the query, result, and error in the event of an error.
func Execl ¶
Execl (log) runs Exec on the query and args and ses log.Println to print the query, result, and error in the event of an error. Unlike Execv, Execl does not return the error, and can be used in single-value contexts.
Do not abuse Execl; it is convenient for experimentation but generally not for production use.
func Execv ¶
Execv (verbose) Exec's the query using the Execer and uses log.Println to print the query, result, and error in the event of an error.
func Get ¶
QueryRow using the provided Queryer, and StructScan the resulting row into dest, which must be a pointer to a struct. If there was no row, Get will return sql.ErrNoRows.
func LoadFile ¶
LoadFile exec's every statement in a file (as a single call to Exec). LoadFile may return a nil *sql.Result if errors are encountered locating or reading the file at path. LoadFile reads the entire file into memory, so it is not suitable for loading large data dumps, but can be useful for initializing schemas or loading indexes. FIXME: this does not really work with multi-statement files for mattn/go-sqlite3 or the go-mysql-driver/mysql drivers; pq seems to be an exception here. Detecting this by requiring something with DriverName() and then attempting to split the queries will be difficult to get right, and its current driver-specific behavior is deemed at least not complex in its incorrectness.
func MapScan ¶
func MapScan(r ColScanner, dest map[string]interface{}) error
Like sql.Rows.Scan, but scans a single Row into a map[string]interface{}. 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 do not reuse the same one on different queries or you may end up with something odd!
The resultant map values will be string representations of the various SQL datatypes for existing values and a nil for null values.
func NamedExecMap ¶
Like NamedQuery, but use Exec instead of Queryx.
func Select ¶
Query using the provided Queryer, and StructScan each row into dest, which must be a slice of structs. The resulting *sql.Rows are closed automatically.
func Selectf ¶
Selectf (fatal) will Select using a Queryer and use log.Fatal to print the query and the error in the event of an error.
func Selectv ¶
Selectv (verbose) will Select using a Queryer and use log.Println to print the query and the error in the event of an error.
func SliceScan ¶
func SliceScan(r ColScanner) ([]interface{}, error)
Scan a row, returning a []interface{} with values similar to MapScan. This function is primarly intended for use where the number of columns is not known. Because you can pass an []interface{} directly to Scan, it's recommended that you do that as it will not have to allocate new slices per row.
func StructScan ¶
Fully scan a sql.Rows result into the dest slice. StructScan destinations MUST have fields that map to every column in the result, and they MAY have fields in addition to those. Fields are mapped to column names by lowercasing the field names by default: use the struct tag `db` to specify exact column names for each field.
StructScan will scan in the entire rows result, so if you need do not want to allocate structs for the entire result, use Queryx and see sqlx.Rows.StructScan.
Types ¶
type Binder ¶
type Binder interface { DriverName() string Rebind(string) string BindMap(string, map[string]interface{}) (string, []interface{}, error) BindStruct(string, interface{}) (string, []interface{}, error) }
An interface for something which can bind queries (Tx, DB)
type ColScanner ¶
type ColScanner interface { Columns() ([]string, error) Scan(dest ...interface{}) error Err() error }
An interface for something which can Scan and return a list of columns (Row, Rows)
type DB ¶
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 MustConnect ¶
Connect, but panic on error.
func (*DB) BindStruct ¶
BindStruct's a query using the DB driver's bindvar type.
func (*DB) DriverName ¶
DriverName returns the driverName passed to the Open function for this DB.
func (*DB) MustBegin ¶
Begin starts a transaction, and panics on error. Returns an *sqlx.Tx instead of an *sql.Tx.
func (*DB) NamedExecMap ¶
NamedExecMap using this DB.
func (*DB) NamedQuery ¶
NamedQuery using this DB.
func (*DB) NamedQueryMap ¶
NamedQueryMap using this DB.
type Ext ¶
A union interface which can bind, query, and exec (Tx, DB), used for NamedQuery and NamedExec, which requires exec/query and BindMap/Struct
type Queryer ¶
type Queryer interface { Query(query string, args ...interface{}) (*sql.Rows, error) Queryx(query string, args ...interface{}) (*Rows, error) QueryRowx(query string, args ...interface{}) *Row }
An interface for something which can Execute sql queries (Tx, DB, Stmt)
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
A reimplementation of sql.Row in order to gain access to the underlying sql.Rows.Columns() data, necessary for StructScan.
func (*Row) Columns ¶
Return the underlying sql.Rows.Columns(), or the deferred error usually returned by Row.Scan()
func (*Row) StructScan ¶
StructScan's a single Row (result of QueryRowx) into dest
type Rows ¶
A wrapper around sql.Rows which caches costly reflect operations during a looped StructScan
func NamedQuery ¶
Issue a named query using BindStruct to get a query executable by the driver and then run Queryx on the result. May return an error from the binding or from the execution itself.
func NamedQueryMap ¶
Issue a named query using BindMap to get a query executable by the driver and then run Queryx on the result. May return an error from the binding or from the query execution itself.
func (*Rows) StructScan ¶
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 Stmt ¶
An sqlx wrapper around database/sql's Stmt with extra functionality Although a Stmt's interface differs from Tx and DB's, internally, a wrapper is used to satisfy the Queryer & Execer interfaces.
func (*Stmt) Execf ¶
Execf (fatal) using this statement. Note that the query portion of the error output will be blank, as Stmt does not expose its query.
func (*Stmt) Execl ¶
Execl (log) using this statement. Note that the query portion of the error output will be blank, as Stmt does not expose its query.
func (*Stmt) Execp ¶
Execf (panic) using this statement. Note that the query portion of the error output will be blank, as Stmt does not expose its query.
func (*Stmt) Execv ¶
Execv (verbose) runs Execv using this statement. Note that the query portion of the error output will be blank, as Stmt does not expose its query.
func (*Stmt) MustExec ¶
MustExec (panic) using this statement. Note that the query portion of the error output will be blank, as Stmt does not expose its query.
type Tx ¶
An sqlx wrapper around database/sql's Tx with extra functionality
func (*Tx) BindStruct ¶
BindStruct's a query within a transaction's bindvar type.
func (*Tx) DriverName ¶
Return the driverName used by the DB which began a transaction.
func (*Tx) NamedQuery ¶
NamedQuery within a transaction.
func (*Tx) Preparex ¶
Prepare's a statement within a transaction, returning a *sqlx.Stmt instead of an *sql.Stmt.