qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-23 01:50:04 -07:00
Code Releases Activity

database/sql: add godoc links

Browse Source 
Add godoc links in database/sql and database/sql/driver.

Change-Id: I96ed79645a7cc656f5d23450ba3cfe005b04b31a
Reviewed-on: https://go-review.googlesource.com/c/go/+/486815
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Benny Siegert <bsiegert@gmail.com>
This commit is contained in:
Olivier Mengué 2023-04-19 21:29:59 +02:00 committed by Benny Siegert
parent 95974b379f
commit 6ba6e72e39
3 changed files with 82 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
src/database/sql/driver/driver.go
View File

@ -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)

10
src/database/sql/driver/types.go
View File

@ -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

100
src/database/sql/sql.go
View File

@ -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