csql

README

Package csql provides convenience functions for use with the types and functions defined in the standard library database/sql package.

Installation

If you have Go installed and your GOPATH is setup, then csql can be installed with go get:

go get github.com/BurntSushi/csql

Documentation

Documentation is available at godoc.org/github.com/BurntSushi/csql.

Unstable

At the moment, this project is a bit of an experiment. I'd like to try and use it in a few packages to see if it shortens the amount of boiler plate error handling and makes other menial tasks easier.

Expect breaking changes to be made while I experiment.

Documentation

Overview

Package csql provides convenience functions for use with the types and functions defined in the standard library `database/sql` package.

Index

• func Count(db Queryer, query string, args ...interface{}) int
• func Exec(db Execer, query string, args ...interface{}) sql.Result
• func ForRow(rows *sql.Rows, do func(RowScanner))
• func Panic(err error)
• func Prepare(db Preparer, query string) *sql.Stmt
• func Query(db Queryer, query string, args ...interface{}) *sql.Rows
• func Safe(errp *error)
• func SafeFunc(f func()) (err error)
• func Scan(scanner RowScanner, dest ...interface{})
• func Truncate(db Execer, driver, table string)
• func Tx(db Beginner, f func(*sql.Tx))
• func Value(v Valuer) driver.Value
• type Beginner
• type Error
  • func (se Error) Error() string
• type Execer
• type Inserter
  • func NewInserter(tx *sql.Tx, driver string, table string, columns ...string) (ins *Inserter, err error)
  • func (in *Inserter) Exec(args ...interface{}) error
• type Preparer
• type QExecer
• type Queryer
• type RowScanner
• type Valuer

Functions

func Count

func Count(db Queryer, query string, args ...interface{}) int

Count accepts any query of the form "SELECT COUNT(*) FROM ..." and returns the count. If an error occurs, it is panic'd as a SQLError.

Any args given are passed to the query.

func Exec

func Exec(db Execer, query string, args ...interface{}) sql.Result

Exec returns the result of a running a query that doesn't return any rows. If an error occurs, it is panic'd as a SQLError.

func ForRow

func ForRow(rows *sql.Rows, do func(RowScanner))

func Panic

func Panic(err error)

Panic will wrap the given error in Error and pass it to panic. If the error is nil, this function does nothing.

func Prepare

func Prepare(db Preparer, query string) *sql.Stmt

Prepare returns a prepared statement. If an error occurs, it is panic'd as a SQLError.

func Query

func Query(db Queryer, query string, args ...interface{}) *sql.Rows

Query returns the result of a query that fetches many rows. If an error occurs, it is panic'd as a SQLError.

func Safe

func Safe(errp *error)

Safe can be used to recover from a SQLError panic and convert it to an error. A pointer to the error must be passed. If a panic occurs with anything other than a SQLError, then it is re-panic'd.

This function is typically useful with 'defer' and a named error return value. For example:

func DoSomething(db Execer) (err error) {
	defer Safe(&err)

	Exec(db, "INSERT INTO ...")
	return
}

In this case, if the Exec (included in this package) fails, then it is converted to an error and used as the return value of DoSomething.

func SafeFunc

func SafeFunc(f func()) (err error)

SafeFunc executes any function that may panic with a SQLError safely. In particular, if `f` panics with a SQLError, then Safe recovers and returns the error wrapped by SQLError.

If `f` panics with any other type of error, the panic is not recovered.

func Scan

func Scan(scanner RowScanner, dest ...interface{})

Scan performs a scan on a row. If an error occurs, it is panic'd as a SQLError.

func Truncate

func Truncate(db Execer, driver, table string)

Truncate truncates the table given. It uses the driver given to determine what kind of query to run.

func Tx

func Tx(db Beginner, f func(*sql.Tx))

Tx runs the given function safely within a transaction. If the function panics with a SQLError, then the transaction is rolled back. Otherwise, the transaction is committed.

The first error that occurs (including beginning and ending the transaction) is panic'd.

func Value

func Value(v Valuer) driver.Value

Value returns the driver value. If an error occurs, it is panic'd as a SQLError.

Types

type Beginner

type Beginner interface {
	Begin() (*sql.Tx, error)
}

Beginner describes values that can begin a transaction.

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error satisfies the error interface. All panic'd errors in this package are Errors.

func (Error) Error

func (se Error) Error() string

type Execer

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

Execer describes values that can execute queries without returning any rows.

type Inserter

type Inserter struct {
	// contains filtered or unexported fields
}

func NewInserter

func NewInserter(
	tx *sql.Tx,
	driver string,
	table string,
	columns ...string,
) (ins *Inserter, err error)

func (*Inserter) Exec

func (in *Inserter) Exec(args ...interface{}) error

type Preparer

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

Preparer describes values that can create prepared statements.

type QExecer

type QExecer interface {
	Exec(query string, args ...interface{}) (sql.Result, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
}

QExecer is the composition of the Queryer and Execer interfaces.

type Queryer

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

Queryer describes values that can run queries which return 1 or many rows.

type RowScanner

type RowScanner interface {
	Scan(dest ...interface{}) error
}

RowScanner describes values that can scan a row of values.

type Valuer

type Valuer interface {
	Value() (driver.Value, error)
}

Valuer describes values that can convert themselves to a driver value.