version: 1.10

package driver

import "database/sql/driver"

Overview

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

Most code should use package sql.

Index

Package files

driver.go types.go

Variables

  1. var Bool boolType

Bool is a ValueConverter that converts input values to bools.

The conversion rules are:

  1. - booleans are returned unchanged
  2. - for integer types,
  3.      1 is true
  4.      0 is false,
  5.      other integers are an error
  6. - for strings and []byte, same rules as strconv.ParseBool
  7. - all other types are an error
  1. 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.

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

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

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

  1. var Int32 int32Type

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

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

  1. 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).

func IsScanValue

  1. func IsScanValue(v interface{}) bool

IsScanValue is equivalent to IsValue. It exists for compatibility.

func IsValue

  1. func IsValue(v interface{}) bool

IsValue reports whether v is a valid Value parameter type.

type ColumnConverter

  1. type ColumnConverter interface {
  2.     // ColumnConverter returns a ValueConverter for the provided
  3.     // column index. If the type of a specific column isn't known
  4.     // or shouldn't be handled specially, DefaultValueConverter
  5.     // can be returned.
  6.     ColumnConverter(idx int) ValueConverter
  7. }

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

  1. type Conn interface {
  2.     // Prepare returns a prepared statement, bound to this connection.
  3.     Prepare(query string) (Stmt, error)
  4.  
  5.     // Close invalidates and potentially stops any current
  6.     // prepared statements and transactions, marking this
  7.     // connection as no longer in use.
  8.     //
  9.     // Because the sql package maintains a free pool of
  10.     // connections and only calls Close when there's a surplus of
  11.     // idle connections, it shouldn't be necessary for drivers to
  12.     // do their own connection caching.
  13.     Close() error
  14.  
  15.     // Begin starts and returns a new transaction.
  16.     //
  17.     // Deprecated: Drivers should implement ConnBeginTx instead (or additionally).
  18.     Begin() (Tx, error)
  19. }

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

Conn is assumed to be stateful.

type ConnBeginTx

  1. type ConnBeginTx interface {
  2.     // BeginTx starts and returns a new transaction.
  3.     // If the context is canceled by the user the sql package will
  4.     // call Tx.Rollback before discarding and closing the connection.
  5.     //
  6.     // This must check opts.Isolation to determine if there is a set
  7.     // isolation level. If the driver does not support a non-default
  8.     // level and one is set or if there is a non-default isolation level
  9.     // that is not supported, an error must be returned.
  10.     //
  11.     // This must also check opts.ReadOnly to determine if the read-only
  12.     // value is true to either set the read-only transaction property if supported
  13.     // or return an error if it is not supported.
  14.     BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
  15. }

ConnBeginTx enhances the Conn interface with context and TxOptions.

type ConnPrepareContext

  1. type ConnPrepareContext interface {
  2.     // PrepareContext returns a prepared statement, bound to this connection.
  3.     // context is for the preparation of the statement,
  4.     // it must not store the context within the statement itself.
  5.     PrepareContext(ctx context.Context, query string) (Stmt, error)
  6. }

ConnPrepareContext enhances the Conn interface with context.

type Connector

  1. type Connector interface {
  2.     // Connect returns a connection to the database.
  3.     // Connect may return a cached connection (one previously
  4.     // closed), but doing so is unnecessary; the sql package
  5.     // maintains a pool of idle connections for efficient re-use.
  6.     //
  7.     // The provided context.Context is for dialing purposes only
  8.     // (see net.DialContext) and should not be stored or used for
  9.     // other purposes.
  10.     //
  11.     // The returned connection is only used by one goroutine at a
  12.     // time.
  13.     Connect(context.Context) (Conn, error)
  14.  
  15.     // Driver returns the underlying Driver of the Connector,
  16.     // mainly to maintain compatibility with the Driver method
  17.     // on sql.DB.
  18.     Driver() Driver
  19. }

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

  1. type Driver interface {
  2.     // Open returns a new connection to the database.
  3.     // The name is a string in a driver-specific format.
  4.     //
  5.     // Open may return a cached connection (one previously
  6.     // closed), but doing so is unnecessary; the sql package
  7.     // maintains a pool of idle connections for efficient re-use.
  8.     //
  9.     // The returned connection is only used by one goroutine at a
  10.     // time.
  11.     Open(name string) (Conn, error)
  12. }

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

  1. type DriverContext interface {
  2.     // OpenConnector must parse the name in the same format that Driver.Open
  3.     // parses the name parameter.
  4.     OpenConnector(name string) (Connector, error)
  5. }

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

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

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

If a Conn implements neither ExecerContext nor Execer 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

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

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

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

  1. type NamedValue struct {
  2.     // If the Name is not empty it should be used for the parameter identifier and
  3.     // not the ordinal position.
  4.     //
  5.     // Name will not have a symbol prefix.
  6.     Name string
  7.  
  8.     // Ordinal position of the parameter starting from one and is always set.
  9.     Ordinal int
  10.  
  11.     // Value is the parameter value.
  12.     Value Value
  13. }

NamedValue holds both the value name and value.

type NamedValueChecker

  1. type NamedValueChecker interface {
  2.     // CheckNamedValue is called before passing arguments to the driver
  3.     // and is called in place of any ColumnConverter. CheckNamedValue must do type
  4.     // validation and conversion as appropriate for the driver.
  5.     CheckNamedValue(*NamedValue) error
  6. }

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

  1. type NotNull struct {
  2.     Converter ValueConverter
  3. }

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

func (NotNull) ConvertValue

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

type Null

  1. type Null struct {
  2.     Converter ValueConverter
  3. }

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

func (Null) ConvertValue

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

type Pinger

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

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

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

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

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

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

  1. type Result interface {
  2.     // LastInsertId returns the database's auto-generated ID
  3.     // after, for example, an INSERT into a table with primary
  4.     // key.
  5.     LastInsertId() (int64, error)
  6.  
  7.     // RowsAffected returns the number of rows affected by the
  8.     // query.
  9.     RowsAffected() (int64, error)
  10. }

Result is the result of a query execution.

type Rows

  1. type Rows interface {
  2.     // Columns returns the names of the columns. The number of
  3.     // columns of the result is inferred from the length of the
  4.     // slice. If a particular column name isn't known, an empty
  5.     // string should be returned for that entry.
  6.     Columns() []string
  7.  
  8.     // Close closes the rows iterator.
  9.     Close() error
  10.  
  11.     // Next is called to populate the next row of data into
  12.     // the provided slice. The provided slice will be the same
  13.     // size as the Columns() are wide.
  14.     //
  15.     // Next should return io.EOF when there are no more rows.
  16.     //
  17.     // The dest should not be written to outside of Next. Care
  18.     // should be taken when closing Rows not to modify
  19.     // a buffer held in dest.
  20.     Next(dest []Value) error
  21. }

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

type RowsAffected

  1. type RowsAffected int64

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

func (RowsAffected) LastInsertId

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

func (RowsAffected) RowsAffected

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

type RowsColumnTypeDatabaseTypeName

  1. type RowsColumnTypeDatabaseTypeName interface {
  2.     Rows
  3.     ColumnTypeDatabaseTypeName(index int) string
  4. }

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

  1. type RowsColumnTypeLength interface {
  2.     Rows
  3.     ColumnTypeLength(index int) (length int64, ok bool)
  4. }

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:

  1. TEXT          (math.MaxInt64, true)
  2. varchar(10)   (10, true)
  3. nvarchar(10)  (10, true)
  4. decimal       (0, false)
  5. int           (0, false)
  6. bytea(30)     (30, true)

type RowsColumnTypeNullable

  1. type RowsColumnTypeNullable interface {
  2.     Rows
  3.     ColumnTypeNullable(index int) (nullable, ok bool)
  4. }

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

  1. type RowsColumnTypePrecisionScale interface {
  2.     Rows
  3.     ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
  4. }

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:

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

type RowsColumnTypeScanType

  1. type RowsColumnTypeScanType interface {
  2.     Rows
  3.     ColumnTypeScanType(index int) reflect.Type
  4. }

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

  1. type RowsNextResultSet interface {
  2.     Rows
  3.  
  4.     // HasNextResultSet is called at the end of the current result set and
  5.     // reports whether there is another result set after the current one.
  6.     HasNextResultSet() bool
  7.  
  8.     // NextResultSet advances the driver to the next result set even
  9.     // if there are remaining rows in the current result set.
  10.     //
  11.     // NextResultSet should return io.EOF when there are no more result sets.
  12.     NextResultSet() error
  13. }

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

type SessionResetter

  1. type SessionResetter interface {
  2.     // ResetSession is called while a connection is in the connection
  3.     // pool. No queries will run on this connection until this method returns.
  4.     //
  5.     // If the connection is bad this should return driver.ErrBadConn to prevent
  6.     // the connection from being returned to the connection pool. Any other
  7.     // error will be discarded.
  8.     ResetSession(ctx context.Context) error
  9. }

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

  1. type Stmt interface {
  2.     // Close closes the statement.
  3.     //
  4.     // As of Go 1.1, a Stmt will not be closed if it's in use
  5.     // by any queries.
  6.     Close() error
  7.  
  8.     // NumInput returns the number of placeholder parameters.
  9.     //
  10.     // If NumInput returns >= 0, the sql package will sanity check
  11.     // argument counts from callers and return errors to the caller
  12.     // before the statement's Exec or Query methods are called.
  13.     //
  14.     // NumInput may also return -1, if the driver doesn't know
  15.     // its number of placeholders. In that case, the sql package
  16.     // will not sanity check Exec or Query argument counts.
  17.     NumInput() int
  18.  
  19.     // Exec executes a query that doesn't return rows, such
  20.     // as an INSERT or UPDATE.
  21.     //
  22.     // Deprecated: Drivers should implement StmtExecContext instead (or additionally).
  23.     Exec(args []Value) (Result, error)
  24.  
  25.     // Query executes a query that may return rows, such as a
  26.     // SELECT.
  27.     //
  28.     // Deprecated: Drivers should implement StmtQueryContext instead (or additionally).
  29.     Query(args []Value) (Rows, error)
  30. }

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

type StmtExecContext

  1. type StmtExecContext interface {
  2.     // ExecContext executes a query that doesn't return rows, such
  3.     // as an INSERT or UPDATE.
  4.     //
  5.     // ExecContext must honor the context timeout and return when it is canceled.
  6.     ExecContext(ctx context.Context, args []NamedValue) (Result, error)
  7. }

StmtExecContext enhances the Stmt interface by providing Exec with context.

type StmtQueryContext

  1. type StmtQueryContext interface {
  2.     // QueryContext executes a query that may return rows, such as a
  3.     // SELECT.
  4.     //
  5.     // QueryContext must honor the context timeout and return when it is canceled.
  6.     QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
  7. }

StmtQueryContext enhances the Stmt interface by providing Query with context.

type Tx

  1. type Tx interface {
  2.     Commit() error
  3.     Rollback() error
  4. }

Tx is a transaction.

type TxOptions

  1. type TxOptions struct {
  2.     Isolation IsolationLevel
  3.     ReadOnly  bool
  4. }

TxOptions holds the transaction options.

This type should be considered identical to sql.TxOptions.

type Value

  1. 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:

  1. int64
  2. float64
  3. bool
  4. []byte
  5. string
  6. time.Time

type ValueConverter

  1. type ValueConverter interface {
  2.     // ConvertValue converts a value to a driver Value.
  3.     ConvertValue(v interface{}) (Value, error)
  4. }

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:

  1. * converting from the Value types as provided by the sql package
  2.   into a database table's specific column type and making sure it
  3.   fits, such as making sure a particular int64 fits in a
  4.   table's uint16 column.
  6. * converting a value as given from the database into one of the
  7.   driver Value types.
  9. * by the sql package, for converting from a driver's Value type
  10.   to a user's type in a scan.

type Valuer

  1. type Valuer interface {
  2.     // Value returns a driver Value.
  3.     Value() (Value, error)
  4. }

Valuer is the interface providing the Value method.

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