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 ConnBeginTx
• type ConnPrepareContext
• type Connector
• type Driver
• type DriverContext
• type Execer
• type ExecerContext
• type IsolationLevel
• type NamedValue
• type NamedValueChecker
• type NotNull
  • func (n NotNull) ConvertValue(v interface{}) (Value, error)
• type Null
  • func (n Null) ConvertValue(v interface{}) (Value, error)
• type Pinger
• type Queryer
• type QueryerContext
• type Result
• type Rows
• type RowsAffected
  • func (RowsAffected) LastInsertId() (int64, error)
  • func (v RowsAffected) RowsAffected() (int64, error)
• type RowsColumnTypeDatabaseTypeName
• type RowsColumnTypeLength
• type RowsColumnTypeNullable
• type RowsColumnTypePrecisionScale
• type RowsColumnTypeScanType
• type RowsNextResultSet
• type SessionResetter
• type Stmt
• type StmtExecContext
• type StmtQueryContext
• type Tx
• type TxOptions
• 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 its argument directly if IsValue(arg). Otherwise, if the argument implements Valuer, its Value method is used to return a Value. As a fallback, the provided argument's underlying type is used to convert it to a Value: underlying integer types are converted to int64, floats to float64, bool, string, and []byte to themselves. If the argument is a nil pointer, ConvertValue returns a nil Value. If the argument is a non-nil pointer, it is dereferenced and ConvertValue is called recursively. 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 ErrRemoveArgument = errors.New("driver: remove argument from query")

ErrRemoveArgument may be returned from NamedValueChecker to instruct the sql package to not pass the argument to the driver query interface. Return when accepting query specific options or structures that aren't SQL query arguments.

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 is equivalent to IsValue. It exists for compatibility.

func IsValue

func IsValue(v interface{}) bool

IsValue reports whether v is a valid Value parameter type.

Types

type ColumnConverter

type ColumnConverter interface {
	ColumnConverter(idx int) ValueConverter
}

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

Deprecated: Drivers should implement NamedValueChecker.

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 ConnBeginTx

type ConnBeginTx interface {
	BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
}

ConnBeginTx enhances the Conn interface with context and TxOptions.

type ConnPrepareContext

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

ConnPrepareContext enhances the Conn interface with context.

type Connector

type Connector interface {
	Connect(context.Context) (Conn, error)

	Driver() Driver
}

A Connector represents a driver in a fixed configuration and can create any number of equivalent Conns for use by multiple goroutines.

A Connector can be passed to sql.OpenDB, to allow drivers to implement their own sql.DB constructors, or returned by DriverContext's OpenConnector method, to allow drivers access to context and to avoid repeated parsing of driver configuration.

type Driver

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

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

Database drivers may implement DriverContext for access to contexts and to parse the name only once for a pool of connections, instead of once per connection.

type DriverContext

type DriverContext interface {
	OpenConnector(name string) (Connector, error)
}

If a Driver implements DriverContext, then sql.DB will call OpenConnector to obtain a Connector and then invoke that Connector's Conn method to obtain each needed connection, instead of invoking the Driver's Open method for each connection. The two-step sequence allows drivers to parse the name just once and also provides access to per-Conn contexts.

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 implements neither ExecerContext nor Execer, the sql package's DB.Exec will first prepare a query, execute the statement, and then close the statement.

Exec may return ErrSkip.

Deprecated: Drivers should implement ExecerContext instead.

type ExecerContext

type ExecerContext interface {
	ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

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

If a Conn does not implement ExecerContext, the sql package's DB.Exec will fall back to Execer; if the Conn does not implement Execer either, DB.Exec will first prepare a query, execute the statement, and then close the statement.

ExecerContext may return ErrSkip.

ExecerContext must honor the context timeout and return when the context is canceled.

type IsolationLevel

type IsolationLevel int

IsolationLevel is the transaction isolation level stored in TxOptions.

This type should be considered identical to sql.IsolationLevel along with any values defined on it.

type NamedValue

type NamedValue struct {
	Name string

	Ordinal int

	Value Value
}

NamedValue holds both the value name and value.

type NamedValueChecker

type NamedValueChecker interface {
	CheckNamedValue(*NamedValue) error
}

NamedValueChecker may be optionally implemented by Conn or Stmt. It provides the driver more control to handle Go and database types beyond the default Values types allowed.

The sql package checks for value checkers in the following order, stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConverter, DefaultParameterConverter.

If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in the final query arguments. This may be used to pass special options to the query itself.

If ErrSkip is returned the column converter error checking path is used for the argument. Drivers may wish to return ErrSkip after they have exhausted their own special cases.

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 Pinger

type Pinger interface {
	Ping(ctx context.Context) error
}

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

If a Conn does not implement Pinger, the sql package's DB.Ping and DB.PingContext will check if there is at least one Conn available.

If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove the Conn from pool.

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 implements neither QueryerContext nor Queryer, the sql package's DB.Query will first prepare a query, execute the statement, and then close the statement.

Query may return ErrSkip.

Deprecated: Drivers should implement QueryerContext instead.

type QueryerContext

type QueryerContext interface {
	QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

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

If a Conn does not implement QueryerContext, the sql package's DB.Query will fall back to Queryer; if the Conn does not implement Queryer either, DB.Query will first prepare a query, execute the statement, and then close the statement.

QueryerContext may return ErrSkip.

QueryerContext must honor the context timeout and return when the context is canceled.

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 RowsColumnTypeDatabaseTypeName

type RowsColumnTypeDatabaseTypeName interface {
	Rows
	ColumnTypeDatabaseTypeName(index int) string
}

RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the database system type name without the length. Type names should be uppercase. Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP".

type RowsColumnTypeLength

type RowsColumnTypeLength interface {
	Rows
	ColumnTypeLength(index int) (length int64, ok bool)
}

RowsColumnTypeLength may be implemented by Rows. It should return the length of the column type if the column is a variable length type. If the column is not a variable length type ok should return false. If length is not limited other than system limits, it should return math.MaxInt64. The following are examples of returned values for various types:

TEXT          (math.MaxInt64, true)
varchar(10)   (10, true)
nvarchar(10)  (10, true)
decimal       (0, false)
int           (0, false)
bytea(30)     (30, true)

type RowsColumnTypeNullable

type RowsColumnTypeNullable interface {
	Rows
	ColumnTypeNullable(index int) (nullable, ok bool)
}

RowsColumnTypeNullable may be implemented by Rows. The nullable value should be true if it is known the column may be null, or false if the column is known to be not nullable. If the column nullability is unknown, ok should be false.

type RowsColumnTypePrecisionScale

type RowsColumnTypePrecisionScale interface {
	Rows
	ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
}

RowsColumnTypePrecisionScale may be implemented by Rows. It should return the precision and scale for decimal types. If not applicable, ok should be false. The following are examples of returned values for various types:

decimal(38, 4)    (38, 4, true)
int               (0, 0, false)
decimal           (math.MaxInt64, math.MaxInt64, true)

type RowsColumnTypeScanType

type RowsColumnTypeScanType interface {
	Rows
	ColumnTypeScanType(index int) reflect.Type
}

RowsColumnTypeScanType may be implemented by Rows. It should return the value type that can be used to scan types into. For example, the database column type "bigint" this should return "reflect.TypeOf(int64(0))".

type RowsNextResultSet

type RowsNextResultSet interface {
	Rows

	HasNextResultSet() bool

	NextResultSet() error
}

RowsNextResultSet extends the Rows interface by providing a way to signal the driver to advance to the next result set.

type SessionResetter

type SessionResetter interface {
	ResetSession(ctx context.Context) error
}

SessionResetter may be implemented by Conn to allow drivers to reset the session state associated with the connection and to signal a bad connection.

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 StmtExecContext

type StmtExecContext interface {
	ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

StmtExecContext enhances the Stmt interface by providing Exec with context.

type StmtQueryContext

type StmtQueryContext interface {
	QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

StmtQueryContext enhances the Stmt interface by providing Query with context.

type Tx

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

Tx is a transaction.

type TxOptions

type TxOptions struct {
	Isolation IsolationLevel
	ReadOnly  bool
}

TxOptions holds the transaction options.

This type should be considered identical to sql.TxOptions.

type Value

type Value interface{}

Value is a value that drivers must be able to handle. It is either nil, a type handled by a database driver's NamedValueChecker interface, or an instance of one of these types:

int64
float64
bool
[]byte
string
time.Time

If the driver supports cursors, a returned Value may also implement the Rows interface in this package. This is used, for example, when a user selects a cursor such as "select cursor(select * from my_table) from dual". If the Rows from the select is closed, the cursor Rows will also be closed.

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.