diff --git a/src/database/sql/driver/driver.go b/src/database/sql/driver/driver.go index 5f6dccdbb97..da310bfb12a 100644 --- a/src/database/sql/driver/driver.go +++ b/src/database/sql/driver/driver.go @@ -5,7 +5,7 @@ // Package driver defines interfaces to be implemented by database // drivers as used by package sql. // -// Most code should use package sql. +// Most code should use the [database/sql] package. // // The driver interface has evolved over time. Drivers should implement // [Connector] and [DriverContext] interfaces. @@ -30,11 +30,12 @@ // 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 -// called if implemented. Before a connection is reused for another query, -// ResetSession is called if implemented. If a connection is never returned to the -// connection pool but immediately reused, then ResetSession is called prior to -// reuse but IsValid is not called. +// If a [Conn] implements [Validator], then the IsValid method is called +// before returning the connection to the connection pool. If an entry in the +// connection pool implements [SessionResetter], then ResetSession +// is called before reusing the connection for another query. If a connection is +// never returned to the connection pool but is immediately reused, then +// ResetSession is called prior to reuse but IsValid is not called. package driver import ( @@ -94,12 +95,12 @@ type Driver interface { Open(name string) (Conn, error) } -// If a [Driver] implements [DriverContext], then sql.DB will call +// If a [Driver] implements DriverContext, then [database/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. +// 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. @@ -111,13 +112,13 @@ type DriverContext interface { // by multiple goroutines. // // A Connector can be passed to [database/sql.OpenDB], to allow drivers -// to implement their own sql.DB constructors, or returned by +// to implement their own [database/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 [database/sql.DB.Close] -// method will call Close and return error (if any). +// method will call the Close method and return error (if any). type Connector interface { // Connect returns a connection to the database. // Connect may return a cached connection (one previously @@ -147,9 +148,9 @@ type Connector interface { // documented. 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 -// having earlier closed the connection) and the sql package should +// ErrBadConn should be returned by a driver to signal to the [database/sql] +// package that a driver.[Conn] is in a bad state (such as the server +// having earlier closed the connection) and the [database/sql] package should // retry on a new connection. // // To prevent duplicate operations, ErrBadConn should NOT be returned @@ -157,7 +158,7 @@ var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") // 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 +// Errors will be checked using [errors.Is]. An error may // wrap ErrBadConn or implement the Is(error) bool method. var ErrBadConn = errors.New("driver: bad connection") @@ -172,9 +173,9 @@ type Pinger interface { Ping(ctx context.Context) error } -// Execer is an optional interface that may be implemented by a Conn. +// Execer is an optional interface that may be implemented by a [Conn]. // -// If a [Conn] implements neither [ExecerContext] nor Execer, +// 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. // @@ -187,7 +188,7 @@ type Execer interface { // ExecerContext is an optional interface that may be implemented by a [Conn]. // -// If a Conn does not implement ExecerContext, the [database/sql.DB.Exec] +// 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. @@ -201,7 +202,7 @@ type ExecerContext interface { // Queryer is an optional interface that may be implemented by a [Conn]. // -// If a Conn implements neither [QueryerContext] nor Queryer, +// 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. // @@ -212,7 +213,7 @@ type Queryer interface { Query(query string, args []Value) (Rows, error) } -// QueryerContext is an optional interface that may be implemented by a Conn. +// QueryerContext is an optional interface that may be implemented by a [Conn]. // // 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, @@ -263,7 +264,7 @@ type ConnPrepareContext interface { // IsolationLevel is the transaction isolation level stored in [TxOptions]. // -// This type should be considered identical to sql.IsolationLevel along +// This type should be considered identical to [database/sql.IsolationLevel] along // with any values defined on it. type IsolationLevel int @@ -379,18 +380,18 @@ type StmtQueryContext interface { } // ErrRemoveArgument may be returned from [NamedValueChecker] to instruct the -// sql package to not pass the argument to the driver query interface. +// [database/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 // the driver more control to handle Go and database types beyond the default -// Values types allowed. +// [Value] types allowed. // -// The sql package checks for value checkers in the following order, -// stopping at the first found match: [database/sql.Stmt.NamedValueChecker], -// Conn.NamedValueChecker, [database/sql.Stmt.ColumnConverter], [DefaultParameterConverter]. +// The [database/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 @@ -479,7 +480,7 @@ type RowsColumnTypeDatabaseTypeName interface { // 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. +// 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) diff --git a/src/database/sql/driver/types.go b/src/database/sql/driver/types.go index 4fec453cdd3..0380572ab19 100644 --- a/src/database/sql/driver/types.go +++ b/src/database/sql/driver/types.go @@ -25,7 +25,7 @@ import ( // - 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 +// - by the [database/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. @@ -35,7 +35,7 @@ type ValueConverter interface { // Valuer is the interface providing the Value method. // // Types implementing Valuer interface are able to convert -// themselves to a driver Value. +// themselves to a driver [Value]. type Valuer interface { // Value returns a driver Value. // Value must not panic. @@ -186,7 +186,7 @@ func IsValue(v any) bool { return false } -// IsScanValue is equivalent to IsValue. +// IsScanValue is equivalent to [IsValue]. // It exists for compatibility. func IsScanValue(v any) bool { return IsValue(v) @@ -202,9 +202,9 @@ func IsScanValue(v any) bool { // 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, [defaultConverter.ConvertValue] returns a nil [Value]. +// 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 +// defaultConverter.ConvertValue is called recursively. Other types // are an error. var DefaultParameterConverter defaultConverter diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go index e70aa8b5500..44b202192a4 100644 --- a/src/database/sql/sql.go +++ b/src/database/sql/sql.go @@ -73,7 +73,7 @@ func Drivers() []string { } // A NamedArg is a named argument. NamedArg values may be used as -// arguments to Query or Exec and bind to the corresponding named +// arguments to [DB.Query] or [DB.Exec] and bind to the corresponding named // parameter in the SQL statement. // // For a more concise way to create NamedArg values, see @@ -118,7 +118,7 @@ func Named(name string, value any) NamedArg { // IsolationLevel is the transaction isolation level used in [TxOptions]. type IsolationLevel int -// Various isolation levels that drivers may support in BeginTx. +// Various isolation levels that drivers may support in [DB.BeginTx]. // If a driver does not support a given isolation level an error may be returned. // // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels. @@ -168,8 +168,8 @@ type TxOptions struct { } // RawBytes is a byte slice that holds a reference to memory owned by -// the database itself. After a Scan into a RawBytes, the slice is only -// valid until the next call to Next, Scan, or Close. +// the database itself. After a [Rows.Scan] into a RawBytes, the slice is only +// valid until the next call to [Rows.Next], [Rows.Scan], or [Rows.Close]. type RawBytes []byte // NullString represents a string that may be null. @@ -424,7 +424,7 @@ func (n Null[T]) Value() (driver.Value, error) { return n.V, nil } -// Scanner is an interface used by [Scan]. +// Scanner is an interface used by [Rows.Scan]. type Scanner interface { // Scan assigns a value from a database driver. // @@ -468,8 +468,8 @@ type Out struct { In bool } -// ErrNoRows is returned by Scan when QueryRow doesn't return a -// row. In such a case, QueryRow returns a placeholder *[Row] value that +// ErrNoRows is returned by [Row.Scan] when [DB.QueryRow] doesn't return a +// row. In such a case, QueryRow returns a placeholder [*Row] value that // defers this error until a Scan. var ErrNoRows = errors.New("sql: no rows in result set") @@ -481,10 +481,10 @@ var ErrNoRows = errors.New("sql: no rows in result set") // also maintains a free pool of idle connections. If the database has // a concept of per-connection state, such state can be reliably observed // within a transaction ([Tx]) or connection ([Conn]). Once [DB.Begin] is called, the -// returned [Tx] is bound to a single connection. Once Commit or -// Rollback is called on the transaction, that transaction's +// returned [Tx] is bound to a single connection. Once [Tx.Commit] or +// [Tx.Rollback] is called on the transaction, that transaction's // connection is returned to [DB]'s idle connection pool. The pool size -// can be controlled with SetMaxIdleConns. +// can be controlled with [DB.SetMaxIdleConns]. type DB struct { // Total time waited for new connections. waitDuration atomic.Int64 @@ -777,7 +777,7 @@ func (db *DB) removeDepLocked(x finalCloser, dep any) func() error { // This is the size of the connectionOpener request chan (DB.openerCh). // This value should be larger than the maximum typical value -// used for db.maxOpen. If maxOpen is significantly larger than +// used for DB.maxOpen. If maxOpen is significantly larger than // connectionRequestQueueSize then it is possible for ALL calls into the *DB // to block until the connectionOpener can satisfy the backlog of requests. var connectionRequestQueueSize = 1000000 @@ -795,17 +795,17 @@ func (t dsnConnector) Driver() driver.Driver { return t.driver } -// OpenDB opens a database using a Connector, allowing drivers to +// OpenDB opens a database using a [driver.Connector], allowing drivers to // bypass a string based data source name. // // Most users will open a database via a driver-specific connection -// helper function that returns a *[DB]. No database drivers are included +// helper function that returns a [*DB]. No database drivers are included // in the Go standard library. See https://golang.org/s/sqldrivers for // a list of third-party drivers. // // OpenDB may just validate its arguments without creating a connection // to the database. To verify that the data source name is valid, call -// Ping. +// [DB.Ping]. // // The returned [DB] is safe for concurrent use by multiple goroutines // and maintains its own pool of idle connections. Thus, the OpenDB @@ -831,13 +831,13 @@ func OpenDB(c driver.Connector) *DB { // database name and connection information. // // Most users will open a database via a driver-specific connection -// helper function that returns a *[DB]. No database drivers are included +// helper function that returns a [*DB]. No database drivers are included // in the Go standard library. See https://golang.org/s/sqldrivers for // a list of third-party drivers. // // Open may just validate its arguments without creating a connection // to the database. To verify that the data source name is valid, call -// Ping. +// [DB.Ping]. // // The returned [DB] is safe for concurrent use by multiple goroutines // and maintains its own pool of idle connections. Thus, the Open @@ -895,7 +895,7 @@ func (db *DB) PingContext(ctx context.Context) error { // establishing a connection if necessary. // // Ping uses [context.Background] internally; to specify the context, use -// [PingContext]. +// [DB.PingContext]. func (db *DB) Ping() error { return db.PingContext(context.Background()) } @@ -1576,7 +1576,7 @@ func (db *DB) retry(fn func(strategy connReuseStrategy) error) error { // PrepareContext creates a prepared statement for later queries or executions. // Multiple queries or executions may be run concurrently from the // returned statement. -// The caller must call the statement's [DB.Close] method +// The caller must call the statement's [*Stmt.Close] method // when the statement is no longer needed. // // The provided context is used for the preparation of the statement, not for the @@ -1596,7 +1596,7 @@ func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) { // Prepare creates a prepared statement for later queries or executions. // Multiple queries or executions may be run concurrently from the // returned statement. -// The caller must call the statement's Close method +// The caller must call the statement's [*Stmt.Close] method // when the statement is no longer needed. // // Prepare uses [context.Background] internally; to specify the context, use @@ -1825,8 +1825,8 @@ func (db *DB) queryDC(ctx, txctx context.Context, dc *driverConn, releaseConn fu // QueryRowContext executes a query that is expected to return at most one row. // QueryRowContext always returns a non-nil value. Errors are deferred until // [Row]'s Scan method is called. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, [*Row.Scan] scans the first selected row and discards // the rest. func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row { rows, err := db.QueryContext(ctx, query, args...) @@ -1836,8 +1836,8 @@ func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *R // QueryRow executes a query that is expected to return at most one row. // QueryRow always returns a non-nil value. Errors are deferred until // [Row]'s Scan method is called. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, [*Row.Scan] scans the first selected row and discards // the rest. // // QueryRow uses [context.Background] internally; to specify the context, use @@ -2029,9 +2029,9 @@ func (c *Conn) QueryContext(ctx context.Context, query string, args ...any) (*Ro // QueryRowContext executes a query that is expected to return at most one row. // QueryRowContext always returns a non-nil value. Errors are deferred until -// [Row]'s Scan method is called. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// the [*Row.Scan] method is called. +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, the [*Row.Scan] scans the first selected row and discards // the rest. func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row { rows, err := c.QueryContext(ctx, query, args...) @@ -2041,7 +2041,7 @@ func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) * // PrepareContext creates a prepared statement for later queries or executions. // Multiple queries or executions may be run concurrently from the // returned statement. -// The caller must call the statement's [Conn.Close] method +// The caller must call the statement's [*Stmt.Close] method // when the statement is no longer needed. // // The provided context is used for the preparation of the statement, not for the @@ -2057,7 +2057,7 @@ func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error) // Raw executes f exposing the underlying driver connection for the // duration of f. The driverConn must not be used outside of f. // -// Once f returns and err is not driver.ErrBadConn, the [Conn] will continue to be usable +// Once f returns and err is not [driver.ErrBadConn], the [Conn] will continue to be usable // until [Conn.Close] is called. func (c *Conn) Raw(f func(driverConn any) error) (err error) { var dc *driverConn @@ -2257,7 +2257,7 @@ func (tx *Tx) txCtx() context.Context { } // closemuRUnlockRelease is used as a func(error) method value in -// ExecContext and QueryContext. Unlocking in the releaseConn keeps +// [DB.ExecContext] and [DB.QueryContext]. Unlocking in the releaseConn keeps // the driver conn from being returned to the connection pool until // the Rows has been closed. func (tx *Tx) closemuRUnlockRelease(error) { @@ -2536,8 +2536,8 @@ func (tx *Tx) Query(query string, args ...any) (*Rows, error) { // QueryRowContext executes a query that is expected to return at most one row. // QueryRowContext always returns a non-nil value. Errors are deferred until // [Row]'s Scan method is called. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, the [*Row.Scan] scans the first selected row and discards // the rest. func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row { rows, err := tx.QueryContext(ctx, query, args...) @@ -2547,8 +2547,8 @@ func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *R // QueryRow executes a query that is expected to return at most one row. // QueryRow always returns a non-nil value. Errors are deferred until // [Row]'s Scan method is called. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, the [*Row.Scan] scans the first selected row and discards // the rest. // // QueryRow uses [context.Background] internally; to specify the context, use @@ -2769,7 +2769,7 @@ func (s *Stmt) prepareOnConnLocked(ctx context.Context, dc *driverConn) (*driver } // QueryContext executes a prepared query statement with the given arguments -// and returns the query results as a *[Rows]. +// and returns the query results as a [*Rows]. func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error) { s.closemu.RLock() defer s.closemu.RUnlock() @@ -2838,9 +2838,9 @@ func rowsiFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, arg // QueryRowContext executes a prepared query statement with the given arguments. // If an error occurs during the execution of the statement, that error will -// be returned by a call to Scan on the returned *[Row], which is always non-nil. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// be returned by a call to Scan on the returned [*Row], which is always non-nil. +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, the [*Row.Scan] scans the first selected row and discards // the rest. func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row { rows, err := s.QueryContext(ctx, args...) @@ -2852,9 +2852,9 @@ func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row { // QueryRow executes a prepared query statement with the given arguments. // If an error occurs during the execution of the statement, that error will -// be returned by a call to Scan on the returned *[Row], which is always non-nil. -// If the query selects no rows, the *[Row]'s Scan will return [ErrNoRows]. -// Otherwise, the *[Row]'s Scan scans the first selected row and discards +// be returned by a call to Scan on the returned [*Row], which is always non-nil. +// If the query selects no rows, the [*Row.Scan] will return [ErrNoRows]. +// Otherwise, the [*Row.Scan] scans the first selected row and discards // the rest. // // Example usage: @@ -3271,9 +3271,9 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType { // *bool // *float32, *float64 // *interface{} -// *[RawBytes] -// *[Rows] (cursor value) -// any type implementing [Scanner] (see Scanner docs) +// *RawBytes +// *Rows (cursor value) +// any type implementing Scanner (see Scanner docs) // // In the most simple case, if the type of the value from the source // column is an integer, bool or string type T and dest is of type *T, @@ -3292,7 +3292,7 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType { // If a dest argument has type *[]byte, Scan saves in that argument a // copy of the corresponding data. The copy is owned by the caller and // can be modified and held indefinitely. The copy can be avoided by -// using an argument of type *[RawBytes] instead; see the documentation +// using an argument of type [*RawBytes] instead; see the documentation // for [RawBytes] for restrictions on its use. // // If an argument has type *interface{}, Scan copies the value @@ -3300,20 +3300,20 @@ func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType { // from a source value of type []byte to *interface{}, a copy of the // slice is made and the caller owns the result. // -// Source values of type time.Time may be scanned into values of type +// Source values of type [time.Time] may be scanned into values of type // *time.Time, *interface{}, *string, or *[]byte. When converting to -// the latter two, time.RFC3339Nano is used. +// the latter two, [time.RFC3339Nano] is used. // // Source values of type bool may be scanned into types *bool, -// *interface{}, *string, *[]byte, or *[RawBytes]. +// *interface{}, *string, *[]byte, or [*RawBytes]. // // For scanning into *bool, the source may be true, false, 1, 0, or // string inputs parseable by [strconv.ParseBool]. // // Scan can also convert a cursor returned from a query, such as // "select cursor(select * from my_table) from dual", into a -// *[Rows] value that can itself be scanned from. The parent -// select query will close any cursor *[Rows] if the parent *[Rows] is closed. +// [*Rows] value that can itself be scanned from. The parent +// select query will close any cursor [*Rows] if the parent [*Rows] is closed. // // If any of the first arguments implementing [Scanner] returns an error, // that error will be wrapped in the returned error. @@ -3427,7 +3427,7 @@ func (rs *Rows) close(err error) error { return err } -// Row is the result of calling QueryRow to select a single row. +// Row is the result of calling [DB.QueryRow] to select a single row. type Row struct { // One of these two will be non-nil: err error // deferred error for easy chaining