diff options
Diffstat (limited to 'libgo/go/database/sql/driver')
| -rw-r--r-- | libgo/go/database/sql/driver/driver.go | 87 |
1 files changed, 73 insertions, 14 deletions
diff --git a/libgo/go/database/sql/driver/driver.go b/libgo/go/database/sql/driver/driver.go index 0262ca2..83b2b3f 100644 --- a/libgo/go/database/sql/driver/driver.go +++ b/libgo/go/database/sql/driver/driver.go @@ -42,6 +42,10 @@ type NamedValue struct { // 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 Driver interface { // Open returns a new connection to the database. // The name is a string in a driver-specific format. @@ -55,6 +59,47 @@ type Driver interface { Open(name string) (Conn, 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 DriverContext interface { + // OpenConnector must parse the name in the same format that Driver.Open + // parses the name parameter. + OpenConnector(name string) (Connector, 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. +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. + // + // The returned connection is only used by one goroutine at a + // time. + Connect(context.Context) (Conn, error) + + // Driver returns the underlying Driver of the Connector, + // mainly to maintain compatibility with the Driver method + // on sql.DB. + Driver() Driver +} + // 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 @@ -86,22 +131,23 @@ type Pinger interface { // 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. +// 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 (or additionally). +// Deprecated: Drivers should implement ExecerContext instead. type Execer interface { Exec(query string, args []Value) (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 -// first prepare a query, execute the statement, and then close the -// statement. +// 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. // @@ -112,22 +158,23 @@ type ExecerContext interface { // 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. +// 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 (or additionally). +// Deprecated: Drivers should implement QueryerContext instead. type Queryer interface { Query(query string, args []Value) (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 -// first prepare a query, execute the statement, and then close the -// statement. +// 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. // @@ -199,6 +246,18 @@ type ConnBeginTx interface { BeginTx(ctx context.Context, opts TxOptions) (Tx, 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 SessionResetter interface { + // ResetSession is called while a connection is in the connection + // pool. No queries will run on this connection until this method returns. + // + // If the connection is bad this should return driver.ErrBadConn to prevent + // the connection from being returned to the connection pool. Any other + // error will be discarded. + ResetSession(ctx context.Context) error +} + // Result is the result of a query execution. type Result interface { // LastInsertId returns the database's auto-generated ID |