driver

Documentation

Index

• Variables
• type Conn
• type Connector
• type Driver
• type Pinger
• type SessionResetter
• type Validator

Variables

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.

Errors will be checked using errors.Is. An error may wrap ErrBadConn or implement the Is(error) bool method.

Types

type Conn

type Conn interface {
	// Close invalidates and potentially stops any current
	// prepared statements and transactions, marking this
	// connection as no longer in use.
	//
	// Because the sql package maintains a free pool of
	// connections and only calls Close when there's a surplus of
	// idle connections, it shouldn't be necessary for drivers to
	// do their own connection caching.
	//
	// Drivers must ensure all network calls made by Close
	// do not block indefinitely (e.g. apply a timeout).
	Close() error
}

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

Conn is assumed to be stateful.

type Connector

type Connector interface {
	// Connect returns a connection to the database.
	// Connect may return a cached connection (one previously
	// closed), but doing so is unnecessary; the sql package
	// maintains a pool of idle connections for efficient re-use.
	//
	// The provided context.Context is for dialing purposes only
	// (see net.DialContext) and should not be stored or used for
	// other purposes. A default timeout should still be used
	// when dialing as a connection pool may call Connect
	// asynchronously to any query.
	//
	// The returned connection is only used by one goroutine at a
	// time.
	Connect(context.Context) (Conn, error)
}

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.

If a Connector implements io.Closer, the sql package's DB.Close method will call Close and return error (if any).

type Driver

type Driver interface {
	// Open returns a new connection to the database.
	// The name is a string in a driver-specific format.
	//
	// Open may return a cached connection (one previously
	// closed), but doing so is unnecessary; the sql package
	// maintains a pool of idle connections for efficient re-use.
	//
	// The returned connection is only used by one goroutine at a
	// time.
	Open(ctx context.Context, 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 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 SessionResetter

type SessionResetter interface {
	// ResetSession is called prior to executing a query on the connection
	// if the connection has been used before. If the driver returns ErrBadConn
	// the connection is discarded.
	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 Validator

type Validator interface {
	// IsValid is called prior to placing the connection into the
	// connection pool. The connection will be discarded if false is returned.
	IsValid() bool
}

Validator may be implemented by Conn to allow drivers to signal if a connection is valid or if it should be discarded.

If implemented, drivers may return the underlying error from queries, even if the connection should be discarded by the connection pool.