sqlx

package
v1.0.23 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2024 License: MIT Imports: 15 Imported by: 12

README

sqlx

sqlx is a library which provides a set of extensions on go's standard database/sql library. The sqlx versions of sql.DB, sql.TX, sql.Stmt, et al. all leave the underlying interfaces untouched, so that their interfaces are a superset on the standard ones. This makes it relatively painless to integrate existing codebases using database/sql with sqlx.

Major additional concepts are:

  • Marshal rows into structs (with embedded struct support), maps, and slices
  • Named parameter support including prepared statements
  • Get and Select to go quickly from query to struct/slice

install

go get github.com/askasoft/pango/sqlx

issues

Row headers can be ambiguous (SELECT 1 AS a, 2 AS a), and the result of Columns() does not fully qualify column names in queries like:

SELECT a.id, a.name, b.id, b.name FROM foos AS a JOIN foos AS b ON a.parent = b.id;

making a struct or map destination ambiguous. Use AS in your queries to give columns distinct names, rows.Scan to scan them manually, or SliceScan to get a slice of results.

usage

Below is an example which shows some common use cases for sqlx. Check sqlx_test.go for more usage.

package main

import (
    "database/sql"
    "fmt"
    "log"
    
    _ "github.com/lib/pq"
    "github.com/askasoft/pango/sqlx"
)

var schema = `
CREATE TABLE person (
    first_name text,
    last_name text,
    email text
);

CREATE TABLE place (
    country text,
    city text NULL,
    telcode integer
)`

type Person struct {
    FirstName string `db:"first_name"`
    LastName  string `db:"last_name"`
    Email     string
}

type Place struct {
    Country string
    City    sql.NullString
    TelCode int
}

func main() {
    // this Pings the database trying to connect
    // use sqlx.Open() for sql.Open() semantics
    db, err := sqlx.Connect("postgres", "user=foo dbname=bar sslmode=disable")
    if err != nil {
        log.Fatalln(err)
    }

    // exec the schema or fail; multi-statement Exec behavior varies between
    // database drivers;  pq will exec them all, sqlite3 won't, ymmv
    db.MustExec(schema)
    
    tx := db.MustBegin()
    tx.MustExec("INSERT INTO person (first_name, last_name, email) VALUES ($1, $2, $3)", "Jason", "Moiron", "jmoiron@jmoiron.net")
    tx.MustExec("INSERT INTO person (first_name, last_name, email) VALUES ($1, $2, $3)", "John", "Doe", "johndoeDNE@gmail.net")
    tx.MustExec("INSERT INTO place (country, city, telcode) VALUES ($1, $2, $3)", "United States", "New York", "1")
    tx.MustExec("INSERT INTO place (country, telcode) VALUES ($1, $2)", "Hong Kong", "852")
    tx.MustExec("INSERT INTO place (country, telcode) VALUES ($1, $2)", "Singapore", "65")
    // Named queries can use structs, so if you have an existing struct (i.e. person := &Person{}) that you have populated, you can pass it in as &person
    tx.NamedExec("INSERT INTO person (first_name, last_name, email) VALUES (:first_name, :last_name, :email)", &Person{"Jane", "Citizen", "jane.citzen@example.com"})
    tx.Commit()

    // Query the database, storing results in a []Person (wrapped in []any)
    people := []Person{}
    db.Select(&people, "SELECT * FROM person ORDER BY first_name ASC")
    jason, john := people[0], people[1]

    fmt.Printf("%#v\n%#v", jason, john)
    // Person{FirstName:"Jason", LastName:"Moiron", Email:"jmoiron@jmoiron.net"}
    // Person{FirstName:"John", LastName:"Doe", Email:"johndoeDNE@gmail.net"}

    // You can also get a single result, a la QueryRow
    jason = Person{}
    err = db.Get(&jason, "SELECT * FROM person WHERE first_name=$1", "Jason")
    fmt.Printf("%#v\n", jason)
    // Person{FirstName:"Jason", LastName:"Moiron", Email:"jmoiron@jmoiron.net"}

    // if you have null fields and use SELECT *, you must use sql.Null* in your struct
    places := []Place{}
    err = db.Select(&places, "SELECT * FROM place ORDER BY telcode ASC")
    if err != nil {
        fmt.Println(err)
        return
    }
    usa, singsing, honkers := places[0], places[1], places[2]
    
    fmt.Printf("%#v\n%#v\n%#v\n", usa, singsing, honkers)
    // Place{Country:"United States", City:sql.NullString{String:"New York", Valid:true}, TelCode:1}
    // Place{Country:"Singapore", City:sql.NullString{String:"", Valid:false}, TelCode:65}
    // Place{Country:"Hong Kong", City:sql.NullString{String:"", Valid:false}, TelCode:852}

    // Loop through rows using only one struct
    place := Place{}
    rows, err := db.Queryx("SELECT * FROM place")
    for rows.Next() {
        err := rows.StructScan(&place)
        if err != nil {
            log.Fatalln(err)
        } 
        fmt.Printf("%#v\n", place)
    }
    // Place{Country:"United States", City:sql.NullString{String:"New York", Valid:true}, TelCode:1}
    // Place{Country:"Hong Kong", City:sql.NullString{String:"", Valid:false}, TelCode:852}
    // Place{Country:"Singapore", City:sql.NullString{String:"", Valid:false}, TelCode:65}

    // Named queries, using `:name` as the bindvar.  Automatic bindvar support
    // which takes into account the dbtype based on the driverName on sqlx.Open/Connect
    _, err = db.NamedExec(`INSERT INTO person (first_name,last_name,email) VALUES (:first,:last,:email)`, 
        map[string]any{
            "first": "Bin",
            "last": "Smuth",
            "email": "bensmith@allblacks.nz",
    })

    // Selects Mr. Smith from the database
    rows, err = db.NamedQuery(`SELECT * FROM person WHERE first_name=:fn`, map[string]any{"fn": "Bin"})

    // Named queries can also use structs.  Their bind names follow the same rules
    // as the name -> db mapping, so struct fields are lowercased and the `db` tag
    // is taken into consideration.
    rows, err = db.NamedQuery(`SELECT * FROM person WHERE first_name=:first_name`, jason)
    
    
    // batch insert
    
    // batch insert with structs
    personStructs := []Person{
        {FirstName: "Ardie", LastName: "Savea", Email: "asavea@ab.co.nz"},
        {FirstName: "Sonny Bill", LastName: "Williams", Email: "sbw@ab.co.nz"},
        {FirstName: "Ngani", LastName: "Laumape", Email: "nlaumape@ab.co.nz"},
    }

    _, err = db.NamedExec(`INSERT INTO person (first_name, last_name, email)
        VALUES (:first_name, :last_name, :email)`, personStructs)

    // batch insert with maps
    personMaps := []map[string]any{
        {"first_name": "Ardie", "last_name": "Savea", "email": "asavea@ab.co.nz"},
        {"first_name": "Sonny Bill", "last_name": "Williams", "email": "sbw@ab.co.nz"},
        {"first_name": "Ngani", "last_name": "Laumape", "email": "nlaumape@ab.co.nz"},
    }

    _, err = db.NamedExec(`INSERT INTO person (first_name, last_name, email)
        VALUES (:first_name, :last_name, :email)`, personMaps)
}

Documentation

Overview

Package sqx 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.

This is package is forked from github.com/jmoiron/sqlx

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrConnDone = sql.ErrConnDone
	ErrNoRows   = sql.ErrNoRows
	ErrTxDone   = sql.ErrTxDone
)
View Source 
var NameMapper = ref.NewMapperFunc("db", str.SnakeCase)

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

Functions

func BindDriver 

func BindDriver(driverName string, binder Binder)

BindDriver sets the Binder for driverName to binder.

func Get 

func Get(q Queryerx, dest any, query string, args ...any) error

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 ErrNoRows like row.Scan would. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func GetContext 

func GetContext(ctx context.Context, q QueryerContext, 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 ErrNoRows like row.Scan would. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

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 MustExec 

func MustExec(e Execer, query string, args ...any) sql.Result

MustExec execs the query using e and panics if there was an error. Any placeholder parameters are replaced with supplied args.

func MustExecContext 

func MustExecContext(ctx context.Context, e ExecerContext, query string, args ...any) sql.Result

MustExecContext execs the query using e and panics if there was an error. Any placeholder parameters are replaced with supplied args.

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 NamedExecContext 

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

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

func Select(q Queryerx, dest any, query string, args ...any) error

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.

func SelectContext 

func SelectContext(ctx context.Context, q QueryerContext, 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 sqx.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 sqx.Rows.StructScan. If rows is sqx.Rows, it will use its mapper, otherwise it will use the default.

func Transaction 

func Transaction(db Beginxer, fc func(tx *Tx) error) (err error)

Transaction start a transaction as a block, return error will rollback, otherwise to commit. Transaction executes an arbitrary number of commands in fc within a transaction. On success the changes are committed; if an error occurs they are rolled back.

func Transactionx 

func Transactionx(db BeginTxxer, ctx context.Context, opts *sql.TxOptions, fc func(tx *Tx) error) (err error)

Transactionx start a transaction as a block, return error will rollback, otherwise to commit. Transaction executes an arbitrary number of commands in fc within a transaction. On success the changes are committed; if an error occurs they are rolled back.

Types

type BeginTxxer 

type BeginTxxer interface {
	BeginTxx(context.Context, *sql.TxOptions) (*Tx, error)
}

BeginTxxer is an interface used by Transactionx

type Beginxer 

type Beginxer interface {
	Beginx() (*Tx, error)
}

Beginxer is an interface used by Transaction

type Bind 

type Bind interface {
	Rebind(string) string
	BindNamed(string, any) (string, []any, error)
}

Bind is an interface for something which can bind queries (Tx, DB)

type Binder 

type Binder int
const (
	BindUnknown Binder = iota
	BindQuestion
	BindDollar
	BindColon
	BindAt
)

Binder types supported by Rebind, BindMap and BindStruct.

func GetBinder 

func GetBinder(driverName string) Binder

GetBinder returns the binder for a given database given a drivername.

func (Binder) Rebind 

func (binder Binder) Rebind(query string) string

Rebind a query from the default binder (QUESTION) to the target binder.

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
	// 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 *sqx.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.

func (*Conn) Binder 

func (ext *Conn) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

func (*Conn) DriverName 

func (ext *Conn) DriverName() string

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

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) IsUnsafe 

func (ext *Conn) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*Conn) Mapper 

func (ext *Conn) Mapper() *ref.Mapper

Mapper returns the mapper

func (*Conn) PreparexContext 

func (c *Conn) PreparexContext(ctx context.Context, query string) (*Stmt, error)

PreparexContext returns an sqx.Stmt instead of a sql.Stmt.

The provided context is used for the preparation of the statement, not for the execution of the statement.

func (*Conn) QueryRowxContext 

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

QueryRowxContext queries the database and returns an *sqx.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 *sqx.Rows. Any placeholder parameters are replaced with supplied args.

func (*Conn) Quote 

func (ext *Conn) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*Conn) Quoter 

func (ext *Conn) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*Conn) Rebind 

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

Rebind transforms a query from QUESTION to the DB driver'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.

func (*Conn) SupportLastInsertID 

func (ext *Conn) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

func (*Conn) Transactionx 

func (c *Conn) Transactionx(ctx context.Context, opts *sql.TxOptions, fc func(tx *Tx) error) (err error)

Transactionx start a transaction as a block, return error will rollback, otherwise to commit. Transaction executes an arbitrary number of commands in fc within a transaction. On success the changes are committed; if an error occurs they are rolled back.

type DB 

type DB struct {
	*sql.DB
	// 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(driverName, dataSourceName string) (*DB, error)

Connect to a database and verify with a ping.

func ConnectContext 

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

ConnectContext to a database and verify with a ping.

func MustConnect 

func MustConnect(driverName, dataSourceName string) *DB

MustConnect connects to a database and panics on error.

func MustOpen 

func MustOpen(driverName, dataSourceName string) *DB

MustOpen is the same as sql.Open, but returns an *sqx.DB instead and panics on error.

func NewDB 

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

NewDB returns a new sqx 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 *sqx.DB instead.

func (*DB) BeginTxx 

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

BeginTxx begins a transaction and returns an *sqx.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.

func (*DB) Beginx 

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

Beginx begins a transaction and returns an *sqx.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) Binder 

func (ext *DB) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

func (*DB) Connx 

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

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

func (*DB) DriverName 

func (ext *DB) DriverName() string

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

func (*DB) Get 

func (db *DB) Get(dest any, query string, args ...any) error

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

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) IsUnsafe 

func (ext *DB) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*DB) Mapper 

func (ext *DB) Mapper() *ref.Mapper

Mapper returns the mapper

func (*DB) MapperFunc 

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

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

func (*DB) MustBegin 

func (db *DB) MustBegin() *Tx

MustBegin starts a transaction, and panics on error. Returns an *sqx.Tx instead of an *sql.Tx.

func (*DB) MustBeginTx 

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

MustBeginTx starts a transaction, and panics on error. Returns an *sqx.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.

func (*DB) MustExec 

func (db *DB) MustExec(query string, args ...any) sql.Result

MustExec (panic) runs MustExec using this database. Any placeholder parameters are replaced with supplied args.

func (*DB) MustExecContext 

func (db *DB) MustExecContext(ctx context.Context, query string, args ...any) sql.Result

MustExecContext (panic) runs MustExec using this database. Any placeholder parameters are replaced with supplied args.

func (*DB) NamedExec 

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

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

func (*DB) NamedExecContext 

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

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

func (*DB) NamedQuery 

func (db *DB) NamedQuery(query string, arg any) (*Rows, error)

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

func (*DB) NamedQueryContext 

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

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

func (*DB) NamedQueryRow 

func (db *DB) NamedQueryRow(query string, arg any) *Row

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

func (*DB) PrepareNamed 

func (db *DB) PrepareNamed(query string) (*NamedStmt, error)

PrepareNamed returns an sqx.NamedStmt

func (*DB) PrepareNamedContext 

func (db *DB) PrepareNamedContext(ctx context.Context, query string) (*NamedStmt, error)

PrepareNamedContext returns an sqx.NamedStmt

func (*DB) Preparex 

func (db *DB) Preparex(query string) (*Stmt, error)

Preparex returns an sqx.Stmt instead of a sql.Stmt

func (*DB) PreparexContext 

func (db *DB) PreparexContext(ctx context.Context, query string) (*Stmt, error)

PreparexContext returns an sqx.Stmt instead of a sql.Stmt.

The provided context is used for the preparation of the statement, not for the execution of the statement.

func (*DB) QueryRowx 

func (db *DB) QueryRowx(query string, args ...any) *Row

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

func (*DB) QueryRowxContext 

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

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

func (*DB) Queryx 

func (db *DB) Queryx(query string, args ...any) (*Rows, error)

Queryx queries the database and returns an *sqx.Rows. 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 *sqx.Rows. Any placeholder parameters are replaced with supplied args.

func (*DB) Quote 

func (ext *DB) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*DB) Quoter 

func (ext *DB) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*DB) Rebind 

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

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

func (*DB) Select 

func (db *DB) Select(dest any, query string, args ...any) error

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

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.

func (*DB) SupportLastInsertID 

func (ext *DB) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

func (*DB) Transaction 

func (db *DB) Transaction(fc func(tx *Tx) error) (err error)

Transaction start a transaction as a block, return error will rollback, otherwise to commit. Transaction executes an arbitrary number of commands in fc within a transaction. On success the changes are committed; if an error occurs they are rolled back.

func (*DB) Transactionx 

func (db *DB) Transactionx(ctx context.Context, opts *sql.TxOptions, fc func(tx *Tx) error) (err error)

Transactionx start a transaction as a block, return error will rollback, otherwise to commit. Transaction executes an arbitrary number of commands in fc within a transaction. On success the changes are committed; if an error occurs they are rolled back.

func (*DB) Unsafe 

func (db *DB) Unsafe() *DB

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. sqx.Stmt and sqx.Tx which are created from this DB will inherit its safety behavior.

type Execer 

type Execer interface {
	Exec(query string, args ...any) (sql.Result, error)
}

Execer is an interface used by MustExec

type ExecerContext 

type ExecerContext interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

ExecerContext is an interface used by MustExecContext and LoadFileContext

type ExtContext 

type ExtContext interface {
	QueryerContext
	ExecerContext
	// contains filtered or unexported methods
}

ExtContext is a union interface which can bind, query, and exec, with Context used by NamedQueryContext and NamedExecContext.

type NamedExecer 

type NamedExecer interface {
	NamedExec(query string, arg any) (sql.Result, error)
}

NamedExecer is an interface used by MustExec

type NamedQueryer 

type NamedQueryer interface {
	NamedQuery(query string, arg any) (*Rows, error)
	NamedQueryRow(query string, arg any) *Row
}

type NamedStmt 

type NamedStmt struct {
	Stmt        *Stmt
	Params      []string
	QueryString string
}

NamedStmt is a prepared statement that executes named queries. Prepare it how you would execute a NamedQuery, but pass in a struct or map when executing.

func (*NamedStmt) Close 

func (n *NamedStmt) Close() error

Close closes the named statement.

func (*NamedStmt) Exec 

func (n *NamedStmt) Exec(arg any) (sql.Result, error)

Exec executes a named statement using the struct passed. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) ExecContext 

func (n *NamedStmt) ExecContext(ctx context.Context, arg any) (sql.Result, error)

ExecContext executes a named statement using the struct passed. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) Get 

func (n *NamedStmt) Get(dest any, arg any) error

Get using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) GetContext 

func (n *NamedStmt) GetContext(ctx context.Context, dest any, arg any) error

GetContext using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) IsUnsafe 

func (n *NamedStmt) IsUnsafe() bool

IsUnsafe return unsafe

func (*NamedStmt) MustExec 

func (n *NamedStmt) MustExec(arg any) sql.Result

MustExec execs a NamedStmt, panicing on error Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) MustExecContext 

func (n *NamedStmt) MustExecContext(ctx context.Context, arg any) sql.Result

MustExecContext execs a NamedStmt, panicing on error Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) Query 

func (n *NamedStmt) Query(arg any) (*sql.Rows, error)

Query executes a named statement using the struct argument, returning rows. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) QueryContext 

func (n *NamedStmt) QueryContext(ctx context.Context, arg any) (*sql.Rows, error)

QueryContext executes a named statement using the struct argument, returning rows. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) QueryRow 

func (n *NamedStmt) QueryRow(arg any) *Row

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

func (*NamedStmt) QueryRowContext 

func (n *NamedStmt) QueryRowContext(ctx context.Context, arg any) *Row

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

func (*NamedStmt) QueryRowx 

func (n *NamedStmt) QueryRowx(arg any) *Row

QueryRowx this NamedStmt. Because of limitations with QueryRow, this is an alias for QueryRow. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) QueryRowxContext 

func (n *NamedStmt) QueryRowxContext(ctx context.Context, arg any) *Row

QueryRowxContext this NamedStmt. Because of limitations with QueryRow, this is an alias for QueryRow. Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) Queryx 

func (n *NamedStmt) Queryx(arg any) (*Rows, error)

Queryx using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) QueryxContext 

func (n *NamedStmt) QueryxContext(ctx context.Context, arg any) (*Rows, error)

QueryxContext using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) Select 

func (n *NamedStmt) Select(dest any, arg any) error

Select using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) SelectContext 

func (n *NamedStmt) SelectContext(ctx context.Context, dest any, arg any) error

SelectContext using this NamedStmt Any named placeholder parameters are replaced with fields from arg.

func (*NamedStmt) Unsafe 

func (n *NamedStmt) Unsafe() *NamedStmt

Unsafe creates an unsafe version of the NamedStmt

type Preparer 

type Preparer interface {
	Prepare(query string) (*sql.Stmt, error)
}

type PreparerContext 

type PreparerContext interface {
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
}

PreparerContext is an interface used by PreparexContext.

type Preparerx 

type Preparerx interface {
	Preparex(query string) (*Stmt, error)
}

type PreparerxContext 

type PreparerxContext interface {
	PreparexContext(ctx context.Context, query string) (*Stmt, error)
}

PreparerxContext is an interface used by PreparexContext.

type Queryer 

type Queryer interface {
	Query(query string, args ...any) (*sql.Rows, error)
}

Queryer is an interface used by Get and Select

type QueryerContext 

type QueryerContext 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
}

QueryerContext is an interface used by GetContext and SelectContext

type Queryerx 

type Queryerx interface {
	Queryx(query string, args ...any) (*Rows, error)
	QueryRowx(query string, args ...any) *Row
}

type Result 

type Result = sql.Result

type Row 

type Row struct {
	// 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) Binder 

func (ext *Row) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

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) DriverName 

func (ext *Row) DriverName() string

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

func (*Row) Err 

func (r *Row) Err() error

Err returns the error encountered while scanning.

func (*Row) IsUnsafe 

func (ext *Row) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*Row) MapScan 

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

MapScan using this Rows.

func (*Row) Mapper 

func (ext *Row) Mapper() *ref.Mapper

Mapper returns the mapper

func (*Row) Quote 

func (ext *Row) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*Row) Quoter 

func (ext *Row) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*Row) Rebind 

func (ext *Row) Rebind(query string) string

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

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.

func (*Row) SupportLastInsertID 

func (ext *Row) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

type Rows 

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

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

func NamedQueryContext 

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

NamedQueryContext binds a named query and then runs Query on the result using the provided Ext (sqx.Tx, sqx.Db). It works with both structs and with map[string]any types.

func (*Rows) Binder 

func (ext *Rows) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

func (*Rows) DriverName 

func (ext *Rows) DriverName() string

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

func (*Rows) IsUnsafe 

func (ext *Rows) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*Rows) MapScan 

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

MapScan using this Rows.

func (*Rows) Mapper 

func (ext *Rows) Mapper() *ref.Mapper

Mapper returns the mapper

func (*Rows) Quote 

func (ext *Rows) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*Rows) Quoter 

func (ext *Rows) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*Rows) Rebind 

func (ext *Rows) Rebind(query string) string

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

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.

func (*Rows) SupportLastInsertID 

func (ext *Rows) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

type Selector 

type Selector interface {
	Get(dest any, query string, args ...any) error
	Select(dest any, query string, args ...any) error
}

type Sql 

type Sql interface {
	Queryer
	Execer
	Preparer
}

Sql the basic interface for sql.DB, sql.Tx

type Sqlx 

type Sqlx interface {
	Sql
	Supporter
	Bind
	Selector
	Queryerx
	NamedQueryer
	NamedExecer
	Preparerx
}

type Stmt 

type Stmt struct {
	*sql.Stmt
	// contains filtered or unexported fields
}

Stmt is an sqx wrapper around sql.Stmt with extra functionality

func (*Stmt) Binder 

func (ext *Stmt) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

func (*Stmt) DriverName 

func (ext *Stmt) DriverName() string

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

func (*Stmt) Get 

func (s *Stmt) Get(dest any, args ...any) error

Get using the prepared statement. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func (*Stmt) GetContext 

func (s *Stmt) GetContext(ctx context.Context, dest any, args ...any) error

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

func (*Stmt) IsUnsafe 

func (ext *Stmt) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*Stmt) Mapper 

func (ext *Stmt) Mapper() *ref.Mapper

Mapper returns the mapper

func (*Stmt) MustExec 

func (s *Stmt) MustExec(args ...any) sql.Result

MustExec (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.

func (*Stmt) MustExecContext 

func (s *Stmt) MustExecContext(ctx context.Context, args ...any) sql.Result

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.

func (*Stmt) QueryRowx 

func (s *Stmt) QueryRowx(args ...any) *Row

QueryRowx using this statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) QueryRowxContext 

func (s *Stmt) QueryRowxContext(ctx context.Context, args ...any) *Row

QueryRowxContext using this statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) Queryx 

func (s *Stmt) Queryx(args ...any) (*Rows, error)

Queryx using this statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) QueryxContext 

func (s *Stmt) QueryxContext(ctx context.Context, args ...any) (*Rows, error)

QueryxContext using this statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) Quote 

func (ext *Stmt) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*Stmt) Quoter 

func (ext *Stmt) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*Stmt) Rebind 

func (ext *Stmt) Rebind(query string) string

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

func (*Stmt) Select 

func (s *Stmt) Select(dest any, args ...any) error

Select using the prepared statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) SelectContext 

func (s *Stmt) SelectContext(ctx context.Context, dest any, args ...any) error

SelectContext using the prepared statement. Any placeholder parameters are replaced with supplied args.

func (*Stmt) SupportLastInsertID 

func (ext *Stmt) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

func (*Stmt) Unsafe 

func (s *Stmt) Unsafe() *Stmt

Unsafe returns a version of Stmt which will silently succeed to scan when columns in the SQL result have no fields in the destination struct.

type Supporter 

type Supporter interface {
	SupportLastInsertID() bool
}

type Tx 

type Tx struct {
	*sql.Tx
	// contains filtered or unexported fields
}

Tx is an sqx 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) Binder 

func (ext *Tx) Binder() Binder

Binder returns the binder by driverName passed to the Open function for this DB.

func (*Tx) DriverName 

func (ext *Tx) DriverName() string

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

func (*Tx) Get 

func (tx *Tx) Get(dest any, query string, args ...any) error

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

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) IsUnsafe 

func (ext *Tx) IsUnsafe() bool

IsUnsafe returns the unsafe

func (*Tx) Mapper 

func (ext *Tx) Mapper() *ref.Mapper

Mapper returns the mapper

func (*Tx) MustExec 

func (tx *Tx) MustExec(query string, args ...any) sql.Result

MustExec runs MustExec within a transaction. Any placeholder parameters are replaced with supplied args.

func (*Tx) MustExecContext 

func (tx *Tx) MustExecContext(ctx context.Context, query string, args ...any) sql.Result

MustExecContext runs MustExecContext within a transaction. Any placeholder parameters are replaced with supplied args.

func (*Tx) NamedExec 

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

NamedExec a named query within a transaction. Any named placeholder parameters are replaced with fields from arg.

func (*Tx) NamedExecContext 

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

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

func (*Tx) NamedQuery 

func (tx *Tx) NamedQuery(query string, arg any) (*Rows, error)

NamedQuery within a transaction. Any named placeholder parameters are replaced with fields from arg.

func (*Tx) NamedQueryRow 

func (tx *Tx) NamedQueryRow(query string, arg any) *Row

NamedQueryRow within a transaction. Any named placeholder parameters are replaced with fields from arg.

func (*Tx) NamedStmt 

func (tx *Tx) NamedStmt(stmt *NamedStmt) *NamedStmt

NamedStmt returns a version of the prepared statement which runs within a transaction.

func (*Tx) NamedStmtContext 

func (tx *Tx) NamedStmtContext(ctx context.Context, stmt *NamedStmt) *NamedStmt

NamedStmtContext returns a version of the prepared statement which runs within a transaction.

func (*Tx) PrepareNamed 

func (tx *Tx) PrepareNamed(query string) (*NamedStmt, error)

PrepareNamed returns an sqx.NamedStmt

func (*Tx) PrepareNamedContext 

func (tx *Tx) PrepareNamedContext(ctx context.Context, query string) (*NamedStmt, error)

PrepareNamedContext returns an sqx.NamedStmt

func (*Tx) Preparex 

func (tx *Tx) Preparex(query string) (*Stmt, error)

Preparex a statement within a transaction.

func (*Tx) PreparexContext 

func (tx *Tx) PreparexContext(ctx context.Context, query string) (*Stmt, error)

PreparexContext returns an sqx.Stmt instead of a sql.Stmt.

The provided context is used for the preparation of the statement, not for the execution of the statement.

func (*Tx) QueryRowx 

func (tx *Tx) QueryRowx(query string, args ...any) *Row

QueryRowx within a transaction. Any placeholder parameters are replaced with supplied args.

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) Queryx 

func (tx *Tx) Queryx(query string, args ...any) (*Rows, error)

Queryx within a transaction. 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) Quote 

func (ext *Tx) Quote(s string) string

Quote quote string 's' with quote marks [2]rune, return (m[0] + s + m[1])

func (*Tx) Quoter 

func (ext *Tx) Quoter() sqx.Quoter

Quoter returns the quoter by driverName passed to the Open function for this DB.

func (*Tx) Rebind 

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

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

func (*Tx) Select 

func (tx *Tx) Select(dest any, query string, args ...any) error

Select within a transaction. Any placeholder parameters are replaced with supplied args.

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.

func (*Tx) Stmtx 

func (tx *Tx) Stmtx(stmt any) *Stmt

Stmtx returns a version of the prepared statement which runs within a transaction. Provided stmt can be either *sql.Stmt or *sqx.Stmt.

func (*Tx) StmtxContext 

func (tx *Tx) StmtxContext(ctx context.Context, stmt any) *Stmt

StmtxContext returns a version of the prepared statement which runs within a transaction. Provided stmt can be either *sql.Stmt or *sqx.Stmt.

func (*Tx) SupportLastInsertID 

func (ext *Tx) SupportLastInsertID() bool

SupportRetuning check sql driver support "RETUNING"

func (*Tx) Unsafe 

func (tx *Tx) Unsafe() *Tx

Unsafe returns a version of Tx which will silently succeed to scan when columns in the SQL result have no fields in the destination struct.

Source Files

View all Source files

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.