diff options
Diffstat (limited to 'src/database/sql/driver')
| -rw-r--r-- | src/database/sql/driver/driver.go | 156 | ||||
| -rw-r--r-- | src/database/sql/driver/types.go | 41 |
2 files changed, 99 insertions, 98 deletions
diff --git a/src/database/sql/driver/driver.go b/src/database/sql/driver/driver.go index daf282bf74..5f6dccdbb9 100644 --- a/src/database/sql/driver/driver.go +++ b/src/database/sql/driver/driver.go @@ -8,26 +8,26 @@ // Most code should use package sql. // // The driver interface has evolved over time. Drivers should implement -// Connector and DriverContext interfaces. -// The Connector.Connect and Driver.Open methods should never return ErrBadConn. -// ErrBadConn should only be returned from Validator, SessionResetter, or +// [Connector] and [DriverContext] interfaces. +// The Connector.Connect and Driver.Open methods should never return [ErrBadConn]. +// [ErrBadConn] should only be returned from [Validator], [SessionResetter], or // a query method if the connection is already in an invalid (e.g. closed) state. // -// All Conn implementations should implement the following interfaces: -// Pinger, SessionResetter, and Validator. +// All [Conn] implementations should implement the following interfaces: +// [Pinger], [SessionResetter], and [Validator]. // -// If named parameters or context are supported, the driver's Conn should implement: -// ExecerContext, QueryerContext, ConnPrepareContext, and ConnBeginTx. +// If named parameters or context are supported, the driver's [Conn] should implement: +// [ExecerContext], [QueryerContext], [ConnPrepareContext], and [ConnBeginTx]. // -// To support custom data types, implement NamedValueChecker. NamedValueChecker +// To support custom data types, implement [NamedValueChecker]. [NamedValueChecker] // also allows queries to accept per-query options as a parameter by returning -// ErrRemoveArgument from CheckNamedValue. +// [ErrRemoveArgument] from CheckNamedValue. // -// If multiple result sets are supported, Rows should implement RowsNextResultSet. +// If multiple result sets are supported, [Rows] should implement [RowsNextResultSet]. // If the driver knows how to describe the types present in the returned result -// it should implement the following interfaces: RowsColumnTypeScanType, -// RowsColumnTypeDatabaseTypeName, RowsColumnTypeLength, RowsColumnTypeNullable, -// and RowsColumnTypePrecisionScale. A given row value may also return a Rows +// it should implement the following interfaces: [RowsColumnTypeScanType], +// [RowsColumnTypeDatabaseTypeName], [RowsColumnTypeLength], [RowsColumnTypeNullable], +// and [RowsColumnTypePrecisionScale]. A given row value may also return a [Rows] // type, which may represent a database cursor value. // // Before a connection is returned to the connection pool after use, IsValid is @@ -44,7 +44,7 @@ import ( ) // Value is a value that drivers must be able to handle. -// It is either nil, a type handled by a database driver's NamedValueChecker +// It is either nil, a type handled by a database driver's [NamedValueChecker] // interface, or an instance of one of these types: // // int64 @@ -54,10 +54,10 @@ import ( // string // time.Time // -// If the driver supports cursors, a returned Value may also implement the Rows interface +// 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. +// 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 Value any // NamedValue holds both the value name and value. @@ -78,7 +78,7 @@ type NamedValue struct { // Driver is the interface that must be implemented by a database // driver. // -// Database drivers may implement DriverContext for access +// 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 { @@ -94,10 +94,10 @@ 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 Connect method to obtain each needed connection, -// instead of invoking the Driver's Open method for each connection. +// If a [Driver] implements [DriverContext], then sql.DB will call +// OpenConnector to obtain a [Connector] and then invoke +// that [Connector]'s Connect 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 { @@ -110,13 +110,13 @@ type DriverContext interface { // and can create any number of equivalent Conns for use // by multiple goroutines. // -// A Connector can be passed to sql.OpenDB, to allow drivers +// A Connector can be passed to [database/sql.OpenDB], to allow drivers // to implement their own sql.DB constructors, or returned by -// DriverContext's OpenConnector method, to allow drivers +// [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 +// If a Connector implements [io.Closer], the [database/sql.DB.Close] // method will call Close and return error (if any). type Connector interface { // Connect returns a connection to the database. @@ -148,7 +148,7 @@ type Connector interface { var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") // 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 +// 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. // @@ -161,65 +161,65 @@ var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") // wrap ErrBadConn or implement the Is(error) bool method. var ErrBadConn = errors.New("driver: bad connection") -// Pinger is an optional interface that may be implemented by a Conn. +// 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 a [Conn] does not implement Pinger, the [database/sql.DB.Ping] and +// [database/sql.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. +// If Conn.Ping returns [ErrBadConn], [database/sql.DB.Ping] and [database/sql.DB.PingContext] will remove +// the [Conn] from pool. type Pinger interface { Ping(ctx context.Context) 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, +// If a [Conn] implements neither [ExecerContext] nor Execer, +// the [database/sql.DB.Exec] will first prepare a query, execute the statement, // and then close the statement. // -// Exec may return ErrSkip. +// Exec may return [ErrSkip]. // -// Deprecated: Drivers should implement ExecerContext instead. +// 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. +// 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 +// If a Conn does not implement ExecerContext, the [database/sql.DB.Exec] +// will fall back to [Execer]; if the Conn does not implement Execer either, +// [database/sql.DB.Exec] will first prepare a query, execute the statement, and then // close the statement. // -// ExecContext may return ErrSkip. +// ExecContext may return [ErrSkip]. // // ExecContext must honor the context timeout and return when the context is canceled. type ExecerContext interface { ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error) } -// Queryer is an optional interface that may be implemented by a Conn. +// 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, +// If a Conn implements neither [QueryerContext] nor Queryer, +// the [database/sql.DB.Query] will first prepare a query, execute the statement, // and then close the statement. // -// Query may return ErrSkip. +// Query may return [ErrSkip]. // -// Deprecated: Drivers should implement QueryerContext instead. +// 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 fall back to Queryer; if the Conn does not implement Queryer either, -// DB.Query will first prepare a query, execute the statement, and then +// If a [Conn] does not implement QueryerContext, the [database/sql.DB.Query] +// will fall back to [Queryer]; if the [Conn] does not implement [Queryer] either, +// [database/sql.DB.Query] will first prepare a query, execute the statement, and then // close the statement. // -// QueryContext may return ErrSkip. +// QueryContext may return [ErrSkip]. // // QueryContext must honor the context timeout and return when the context is canceled. type QueryerContext interface { @@ -253,7 +253,7 @@ type Conn interface { Begin() (Tx, error) } -// ConnPrepareContext enhances the Conn interface with context. +// ConnPrepareContext enhances the [Conn] interface with context. type ConnPrepareContext interface { // PrepareContext returns a prepared statement, bound to this connection. // context is for the preparation of the statement, @@ -261,7 +261,7 @@ type ConnPrepareContext interface { PrepareContext(ctx context.Context, query string) (Stmt, error) } -// IsolationLevel is the transaction isolation level stored in TxOptions. +// 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. @@ -269,13 +269,13 @@ type IsolationLevel int // TxOptions holds the transaction options. // -// This type should be considered identical to sql.TxOptions. +// This type should be considered identical to [database/sql.TxOptions]. type TxOptions struct { Isolation IsolationLevel ReadOnly bool } -// ConnBeginTx enhances the Conn interface with context and TxOptions. +// ConnBeginTx enhances the [Conn] interface with context and [TxOptions]. type ConnBeginTx interface { // BeginTx starts and returns a new transaction. // If the context is canceled by the user the sql package will @@ -292,7 +292,7 @@ type ConnBeginTx interface { BeginTx(ctx context.Context, opts TxOptions) (Tx, error) } -// SessionResetter may be implemented by Conn to allow drivers to reset the +// 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 prior to executing a query on the connection @@ -301,7 +301,7 @@ type SessionResetter interface { ResetSession(ctx context.Context) error } -// Validator may be implemented by Conn to allow drivers to +// 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, @@ -324,7 +324,7 @@ type Result interface { RowsAffected() (int64, error) } -// Stmt is a prepared statement. It is bound to a Conn and not +// Stmt is a prepared statement. It is bound to a [Conn] and not // used by multiple goroutines concurrently. type Stmt interface { // Close closes the statement. @@ -360,7 +360,7 @@ type Stmt interface { Query(args []Value) (Rows, error) } -// StmtExecContext enhances the Stmt interface by providing Exec with context. +// StmtExecContext enhances the [Stmt] interface by providing Exec with context. type StmtExecContext interface { // ExecContext executes a query that doesn't return rows, such // as an INSERT or UPDATE. @@ -369,7 +369,7 @@ type StmtExecContext interface { ExecContext(ctx context.Context, args []NamedValue) (Result, error) } -// StmtQueryContext enhances the Stmt interface by providing Query with context. +// StmtQueryContext enhances the [Stmt] interface by providing Query with context. type StmtQueryContext interface { // QueryContext executes a query that may return rows, such as a // SELECT. @@ -378,26 +378,26 @@ type StmtQueryContext interface { QueryContext(ctx context.Context, args []NamedValue) (Rows, error) } -// ErrRemoveArgument may be returned from NamedValueChecker to instruct the +// 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 ErrRemoveArgument = errors.New("driver: remove argument from query") -// NamedValueChecker may be optionally implemented by Conn or Stmt. It provides +// 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. +// stopping at the first found match: [database/sql.Stmt.NamedValueChecker], +// Conn.NamedValueChecker, [database/sql.Stmt.ColumnConverter], [DefaultParameterConverter]. // -// If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in +// 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 +// 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 NamedValueChecker interface { // CheckNamedValue is called before passing arguments to the driver @@ -406,11 +406,11 @@ type NamedValueChecker interface { CheckNamedValue(*NamedValue) error } -// ColumnConverter may be optionally implemented by Stmt if the +// 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. +// any type to a driver [Value]. // -// Deprecated: Drivers should implement NamedValueChecker. +// Deprecated: Drivers should implement [NamedValueChecker]. type ColumnConverter interface { // ColumnConverter returns a ValueConverter for the provided // column index. If the type of a specific column isn't known @@ -442,7 +442,7 @@ type Rows interface { Next(dest []Value) error } -// RowsNextResultSet extends the Rows interface by providing a way to signal +// RowsNextResultSet extends the [Rows] interface by providing a way to signal // the driver to advance to the next result set. type RowsNextResultSet interface { Rows @@ -458,15 +458,15 @@ type RowsNextResultSet interface { NextResultSet() error } -// RowsColumnTypeScanType may be implemented by Rows. It should return +// 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))". +// column type "bigint" this should return "[reflect.TypeOf](int64(0))". type RowsColumnTypeScanType interface { Rows ColumnTypeScanType(index int) reflect.Type } -// RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the +// 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", @@ -476,7 +476,7 @@ type RowsColumnTypeDatabaseTypeName interface { ColumnTypeDatabaseTypeName(index int) string } -// RowsColumnTypeLength may be implemented by Rows. It should return the length +// 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. @@ -493,7 +493,7 @@ type RowsColumnTypeLength interface { ColumnTypeLength(index int) (length int64, ok bool) } -// RowsColumnTypeNullable may be implemented by Rows. The nullable value should +// 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. @@ -502,7 +502,7 @@ type RowsColumnTypeNullable interface { ColumnTypeNullable(index int) (nullable, ok bool) } -// RowsColumnTypePrecisionScale may be implemented by Rows. It should return +// 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: // @@ -520,7 +520,7 @@ type Tx interface { Rollback() error } -// RowsAffected implements Result for an INSERT or UPDATE operation +// RowsAffected implements [Result] for an INSERT or UPDATE operation // which mutates a number of rows. type RowsAffected int64 @@ -534,9 +534,9 @@ func (v RowsAffected) RowsAffected() (int64, error) { return int64(v), nil } -// ResultNoRows is a pre-defined Result for drivers to return when a DDL +// 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. +// LastInsertId and [RowsAffected]. var ResultNoRows noRows type noRows struct{} diff --git a/src/database/sql/driver/types.go b/src/database/sql/driver/types.go index c4a253b3e5..4fec453cdd 100644 --- a/src/database/sql/driver/types.go +++ b/src/database/sql/driver/types.go @@ -17,15 +17,15 @@ import ( // 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 +// - 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. +// driver [Value] types. // -// - by the sql package, for converting from a driver's Value type +// - by the sql package, for converting from a driver's [Value] type // to a user's type in a scan. type ValueConverter interface { // ConvertValue converts a value to a driver Value. @@ -42,7 +42,7 @@ type Valuer interface { Value() (Value, error) } -// Bool is a ValueConverter that converts input values to bools. +// Bool is a [ValueConverter] that converts input values to bool. // // The conversion rules are: // - booleans are returned unchanged @@ -50,7 +50,7 @@ type Valuer interface { // 1 is true // 0 is false, // other integers are an error -// - for strings and []byte, same rules as strconv.ParseBool +// - for strings and []byte, same rules as [strconv.ParseBool] // - all other types are an error var Bool boolType @@ -97,7 +97,7 @@ func (boolType) ConvertValue(src any) (Value, error) { return nil, fmt.Errorf("sql/driver: couldn't convert %v (%T) into type bool", src, src) } -// Int32 is a ValueConverter that converts input values to int64, +// Int32 is a [ValueConverter] that converts input values to int64, // respecting the limits of an int32 value. var Int32 int32Type @@ -130,7 +130,7 @@ func (int32Type) ConvertValue(v any) (Value, error) { return nil, fmt.Errorf("sql/driver: unsupported value %v (type %T) converting to int32", v, v) } -// String is a ValueConverter that converts its input to a string. +// 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). @@ -146,8 +146,8 @@ func (stringType) ConvertValue(v any) (Value, error) { return fmt.Sprintf("%v", v), nil } -// Null is a type that implements ValueConverter by allowing nil -// values but otherwise delegating to another ValueConverter. +// Null is a type that implements [ValueConverter] by allowing nil +// values but otherwise delegating to another [ValueConverter]. type Null struct { Converter ValueConverter } @@ -159,8 +159,8 @@ func (n Null) ConvertValue(v any) (Value, error) { return n.Converter.ConvertValue(v) } -// NotNull is a type that implements ValueConverter by disallowing nil -// values but otherwise delegating to another ValueConverter. +// NotNull is a type that implements [ValueConverter] by disallowing nil +// values but otherwise delegating to another [ValueConverter]. type NotNull struct { Converter ValueConverter } @@ -172,7 +172,7 @@ func (n NotNull) ConvertValue(v any) (Value, error) { return n.Converter.ConvertValue(v) } -// IsValue reports whether v is a valid Value parameter type. +// IsValue reports whether v is a valid [Value] parameter type. func IsValue(v any) bool { if v == nil { return true @@ -193,18 +193,19 @@ func IsScanValue(v any) bool { } // DefaultParameterConverter is the default implementation of -// ValueConverter that's used when a Stmt doesn't implement -// ColumnConverter. +// [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: +// 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. +// pointer, [defaultConverter.ConvertValue] returns a nil [Value]. +// If the argument is a non-nil pointer, it is dereferenced and +// [defaultConverter.ConvertValue] is called recursively. Other types +// are an error. var DefaultParameterConverter defaultConverter type defaultConverter struct{} |