driver

Documentation

Overview

Package driver defines interfaces to be implemented by database drivers as used by package sql.

Most code should use package sql.

Index

• Variables
• func IsScanValue(v interface{}) bool
• func IsValue(v interface{}) bool
• type ColumnConverter
• type Conn
• type Driver
• type Execer
• type NotNull
  • func (n NotNull) ConvertValue(v interface{}) (Value, error)
• type Null
  • func (n Null) ConvertValue(v interface{}) (Value, error)
• type Queryer
• type Result
• type Rows
• type RowsAffected
  • func (RowsAffected) LastInsertId() (int64, error)
  • func (v RowsAffected) RowsAffected() (int64, error)
• type Stmt
• type Tx
• type Value
• type ValueConverter
• type Valuer

Variables

var Bool boolType

Bool is a ValueConverter that converts input values to bools.

The conversion rules are:

• booleans are returned unchanged
• for integer types, 1 is true 0 is false, other integers are an error
• for strings and []byte, same rules as strconv.ParseBool
• all other types are an error

var DefaultParameterConverter defaultConverter

DefaultParameterConverter is the default implementation of ValueConverter that's used when a Stmt doesn't implement ColumnConverter.

DefaultParameterConverter returns the given value directly if IsValue(value). Otherwise integer type are converted to int64, floats to float64, and strings to []byte. Other types are an error.

var ErrBadConn = errors.New("driver: bad connection")

ErrBadConn should be returned by a driver to signal to the sql package that a driver.Conn is in a bad state (such as the server having earlier closed the connection) and the sql package should retry on a new connection.

To prevent duplicate operations, ErrBadConn should NOT be returned if there's a possibility that the database server might have performed the operation. Even if the server sends back an error, you shouldn't return ErrBadConn.

var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

ErrSkip may be returned by some optional interfaces' methods to indicate at runtime that the fast path is unavailable and the sql package should continue as if the optional interface was not implemented. ErrSkip is only supported where explicitly documented.

var Int32 int32Type

Int32 is a ValueConverter that converts input values to int64, respecting the limits of an int32 value.

var ResultNoRows noRows

ResultNoRows is a pre-defined Result for drivers to return when a DDL command (such as a CREATE TABLE) succeeds. It returns an error for both LastInsertId and RowsAffected.

var String stringType

String is a ValueConverter that converts its input to a string. If the value is already a string or []byte, it's unchanged. If the value is of another type, conversion to string is done with fmt.Sprintf("%v", v).

Functions

func IsScanValue

func IsScanValue(v interface{}) bool

IsScanValue reports whether v is a valid Value scan type. Unlike IsValue, IsScanValue does not permit the string type.

func IsValue

func IsValue(v interface{}) bool

IsValue reports whether v is a valid Value parameter type. Unlike IsScanValue, IsValue permits the string type.

Types

type ColumnConverter

type ColumnConverter interface {
	ColumnConverter(idx int) ValueConverter
}

ColumnConverter may be optionally implemented by Stmt if the the statement is aware of its own columns' types and can convert from any type to a driver Value.

type Conn

type Conn interface {
	Prepare(query string) (Stmt, error)

	Close() error

	Begin() (Tx, error)
}

Conn is a connection to a database. It is not used concurrently by multiple goroutines.

Conn is assumed to be stateful.

type Driver

type Driver interface {
	Open(name string) (Conn, error)
}

Driver is the interface that must be implemented by a database driver.

type Execer

type Execer interface {
	Exec(query string, args []Value) (Result, error)
}

Execer is an optional interface that may be implemented by a Conn.

If a Conn does not implement Execer, the sql package's DB.Exec will first prepare a query, execute the statement, and then close the statement.

Exec may return ErrSkip.

type NotNull

type NotNull struct {
	Converter ValueConverter
}

NotNull is a type that implements ValueConverter by disallowing nil values but otherwise delegating to another ValueConverter.

func (NotNull) ConvertValue

func (n NotNull) ConvertValue(v interface{}) (Value, error)

type Null

type Null struct {
	Converter ValueConverter
}

Null is a type that implements ValueConverter by allowing nil values but otherwise delegating to another ValueConverter.

func (Null) ConvertValue

func (n Null) ConvertValue(v interface{}) (Value, error)

type Queryer

type Queryer interface {
	Query(query string, args []Value) (Rows, error)
}

Queryer is an optional interface that may be implemented by a Conn.

If a Conn does not implement Queryer, the sql package's DB.Query will first prepare a query, execute the statement, and then close the statement.

Query may return ErrSkip.

type Result

type Result interface {
	LastInsertId() (int64, error)

	RowsAffected() (int64, error)
}

Result is the result of a query execution.

type Rows

type Rows interface {
	Columns() []string

	Close() error

	Next(dest []Value) error
}

Rows is an iterator over an executed query's results.

type RowsAffected

type RowsAffected int64

RowsAffected implements Result for an INSERT or UPDATE operation which mutates a number of rows.

func (RowsAffected) LastInsertId

func (RowsAffected) LastInsertId() (int64, error)

func (RowsAffected) RowsAffected

func (v RowsAffected) RowsAffected() (int64, error)

type Stmt

type Stmt interface {
	Close() error

	NumInput() int

	Exec(args []Value) (Result, error)

	Query(args []Value) (Rows, error)
}

Stmt is a prepared statement. It is bound to a Conn and not used by multiple goroutines concurrently.

type Tx

type Tx interface {
	Commit() error
	Rollback() error
}

Tx is a transaction.

type Value

type Value interface{}

Value is a value that drivers must be able to handle. It is either nil or an instance of one of these types:

int64
float64
bool
[]byte
string   [*] everywhere except from Rows.Next.
time.Time

type ValueConverter

type ValueConverter interface {
	ConvertValue(v interface{}) (Value, error)
}

ValueConverter is the interface providing the ConvertValue method.

Various implementations of ValueConverter are provided by the driver package to provide consistent implementations of conversions between drivers. The ValueConverters have several uses:

• converting from the Value types as provided by the sql package into a database table's specific column type and making sure it fits, such as making sure a particular int64 fits in a table's uint16 column.

• converting a value as given from the database into one of the driver Value types.

• by the sql package, for converting from a driver's Value type to a user's type in a scan.

type Valuer

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

Valuer is the interface providing the Value method.

Types implementing Valuer interface are able to convert themselves to a driver Value.