Package sqlx

Overview ▹

Overview ▾

Package sqlx provides general purpose extensions to database/sql.

It 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.

Additions include scanning into structs, named query support, rebinding
queries for different drivers, convenient shorthands for common error handling
and more.

Package files

Internal call graph ▹

Internal call graph ▾

In the call graph viewer below, each node
is a function belonging to this package
and its children are the functions it
calls—perhaps dynamically.

The root nodes are the entry points of the
package: functions that may be called from
outside the package.
There may be non-exported or anonymous
functions among them if they are called
dynamically from another package.

Click a node to visit that function's source code.
From there you can visit its callers by
clicking its declaring func
token.

Functions may be omitted if they were
determined to be unreachable in the
particular programs or tests that were
analyzed.

Constants

Bindvar types supported by Rebind, BindMap and BindStruct.

const (
UNKNOWN = iota
QUESTION
DOLLAR
NAMED
)

Variables

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.

Get 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.

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.

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 `?` bindVar. The return value uses the `?` bindVar.

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.

LoadFileContext exec's every statement in a file (as a single call to Exec).
LoadFileContext 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.

MapScan scans a single Row into the dest 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 reuse the same map with
care. Columns which occur more than once in the result will overwrite
each other!

Select 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.

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.

SliceScan a row, returning a []interface{} 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 []interface{} directly to Scan,
it's recommended that you do that as it will not have to allocate new
slices per row.

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.

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
BeginxContext is canceled.

MustBeginTx starts a transaction, and panics on error. 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
MustBeginContext is canceled.

Unsafe returns a version of DB which will silently succeed to scan when
columns in the SQL result have no fields in the destination struct.
sqlx.Stmt and sqlx.Tx which are created from this DB will inherit its
safety behavior.

QueryRow executes a named statement against the database. Because sqlx cannot
create a *sql.Row with an error condition pre-set for binding errors, sqlx
returns a *sqlx.Row instead.
Any named placeholder parameters are replaced with fields from arg.

QueryRowContext executes a named statement against the database. Because sqlx cannot
create a *sql.Row with an error condition pre-set for binding errors, sqlx
returns a *sqlx.Row instead.
Any named placeholder parameters are replaced with fields from arg.

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.

MustExecContext (panic) using this statement. Note that the query portion of
the error output will be blank, as Stmt does not expose its query.
Any placeholder parameters are replaced with supplied args.