Source file src/database/sql/sql.go

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package sql provides a generic interface around SQL (or SQL-like)
     6  // databases.
     7  //
     8  // The sql package must be used in conjunction with a database driver.
     9  // See https://golang.org/s/sqldrivers for a list of drivers.
    10  //
    11  // Drivers that do not support context cancellation will not return until
    12  // after the query is completed.
    13  //
    14  // For usage examples, see the wiki page at
    15  // https://golang.org/s/sqlwiki.
    16  package sql
    17  
    18  import (
    19  	"context"
    20  	"database/sql/driver"
    21  	"errors"
    22  	"fmt"
    23  	"io"
    24  	"reflect"
    25  	"runtime"
    26  	"sort"
    27  	"strconv"
    28  	"sync"
    29  	"sync/atomic"
    30  	"time"
    31  )
    32  
    33  var (
    34  	driversMu sync.RWMutex
    35  	drivers   = make(map[string]driver.Driver)
    36  )
    37  
    38  // nowFunc returns the current time; it's overridden in tests.
    39  var nowFunc = time.Now
    40  
    41  // Register makes a database driver available by the provided name.
    42  // If Register is called twice with the same name or if driver is nil,
    43  // it panics.
    44  func Register(name string, driver driver.Driver) {
    45  	driversMu.Lock()
    46  	defer driversMu.Unlock()
    47  	if driver == nil {
    48  		panic("sql: Register driver is nil")
    49  	}
    50  	if _, dup := drivers[name]; dup {
    51  		panic("sql: Register called twice for driver " + name)
    52  	}
    53  	drivers[name] = driver
    54  }
    55  
    56  func unregisterAllDrivers() {
    57  	driversMu.Lock()
    58  	defer driversMu.Unlock()
    59  	// For tests.
    60  	drivers = make(map[string]driver.Driver)
    61  }
    62  
    63  // Drivers returns a sorted list of the names of the registered drivers.
    64  func Drivers() []string {
    65  	driversMu.RLock()
    66  	defer driversMu.RUnlock()
    67  	list := make([]string, 0, len(drivers))
    68  	for name := range drivers {
    69  		list = append(list, name)
    70  	}
    71  	sort.Strings(list)
    72  	return list
    73  }
    74  
    75  // A NamedArg is a named argument. NamedArg values may be used as
    76  // arguments to Query or Exec and bind to the corresponding named
    77  // parameter in the SQL statement.
    78  //
    79  // For a more concise way to create NamedArg values, see
    80  // the Named function.
    81  type NamedArg struct {
    82  	_Named_Fields_Required struct{}
    83  
    84  	// Name is the name of the parameter placeholder.
    85  	//
    86  	// If empty, the ordinal position in the argument list will be
    87  	// used.
    88  	//
    89  	// Name must omit any symbol prefix.
    90  	Name string
    91  
    92  	// Value is the value of the parameter.
    93  	// It may be assigned the same value types as the query
    94  	// arguments.
    95  	Value any
    96  }
    97  
    98  // Named provides a more concise way to create NamedArg values.
    99  //
   100  // Example usage:
   101  //
   102  //     db.ExecContext(ctx, `
   103  //         delete from Invoice
   104  //         where
   105  //             TimeCreated < @end
   106  //             and TimeCreated >= @start;`,
   107  //         sql.Named("start", startTime),
   108  //         sql.Named("end", endTime),
   109  //     )
   110  func Named(name string, value any) NamedArg {
   111  	// This method exists because the go1compat promise
   112  	// doesn't guarantee that structs don't grow more fields,
   113  	// so unkeyed struct literals are a vet error. Thus, we don't
   114  	// want to allow sql.NamedArg{name, value}.
   115  	return NamedArg{Name: name, Value: value}
   116  }
   117  
   118  // IsolationLevel is the transaction isolation level used in TxOptions.
   119  type IsolationLevel int
   120  
   121  // Various isolation levels that drivers may support in BeginTx.
   122  // If a driver does not support a given isolation level an error may be returned.
   123  //
   124  // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.
   125  const (
   126  	LevelDefault IsolationLevel = iota
   127  	LevelReadUncommitted
   128  	LevelReadCommitted
   129  	LevelWriteCommitted
   130  	LevelRepeatableRead
   131  	LevelSnapshot
   132  	LevelSerializable
   133  	LevelLinearizable
   134  )
   135  
   136  // String returns the name of the transaction isolation level.
   137  func (i IsolationLevel) String() string {
   138  	switch i {
   139  	case LevelDefault:
   140  		return "Default"
   141  	case LevelReadUncommitted:
   142  		return "Read Uncommitted"
   143  	case LevelReadCommitted:
   144  		return "Read Committed"
   145  	case LevelWriteCommitted:
   146  		return "Write Committed"
   147  	case LevelRepeatableRead:
   148  		return "Repeatable Read"
   149  	case LevelSnapshot:
   150  		return "Snapshot"
   151  	case LevelSerializable:
   152  		return "Serializable"
   153  	case LevelLinearizable:
   154  		return "Linearizable"
   155  	default:
   156  		return "IsolationLevel(" + strconv.Itoa(int(i)) + ")"
   157  	}
   158  }
   159  
   160  var _ fmt.Stringer = LevelDefault
   161  
   162  // TxOptions holds the transaction options to be used in DB.BeginTx.
   163  type TxOptions struct {
   164  	// Isolation is the transaction isolation level.
   165  	// If zero, the driver or database's default level is used.
   166  	Isolation IsolationLevel
   167  	ReadOnly  bool
   168  }
   169  
   170  // RawBytes is a byte slice that holds a reference to memory owned by
   171  // the database itself. After a Scan into a RawBytes, the slice is only
   172  // valid until the next call to Next, Scan, or Close.
   173  type RawBytes []byte
   174  
   175  // NullString represents a string that may be null.
   176  // NullString implements the Scanner interface so
   177  // it can be used as a scan destination:
   178  //
   179  //  var s NullString
   180  //  err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
   181  //  ...
   182  //  if s.Valid {
   183  //     // use s.String
   184  //  } else {
   185  //     // NULL value
   186  //  }
   187  //
   188  type NullString struct {
   189  	String string
   190  	Valid  bool // Valid is true if String is not NULL
   191  }
   192  
   193  // Scan implements the Scanner interface.
   194  func (ns *NullString) Scan(value any) error {
   195  	if value == nil {
   196  		ns.String, ns.Valid = "", false
   197  		return nil
   198  	}
   199  	ns.Valid = true
   200  	return convertAssign(&ns.String, value)
   201  }
   202  
   203  // Value implements the driver Valuer interface.
   204  func (ns NullString) Value() (driver.Value, error) {
   205  	if !ns.Valid {
   206  		return nil, nil
   207  	}
   208  	return ns.String, nil
   209  }
   210  
   211  // NullInt64 represents an int64 that may be null.
   212  // NullInt64 implements the Scanner interface so
   213  // it can be used as a scan destination, similar to NullString.
   214  type NullInt64 struct {
   215  	Int64 int64
   216  	Valid bool // Valid is true if Int64 is not NULL
   217  }
   218  
   219  // Scan implements the Scanner interface.
   220  func (n *NullInt64) Scan(value any) error {
   221  	if value == nil {
   222  		n.Int64, n.Valid = 0, false
   223  		return nil
   224  	}
   225  	n.Valid = true
   226  	return convertAssign(&n.Int64, value)
   227  }
   228  
   229  // Value implements the driver Valuer interface.
   230  func (n NullInt64) Value() (driver.Value, error) {
   231  	if !n.Valid {
   232  		return nil, nil
   233  	}
   234  	return n.Int64, nil
   235  }
   236  
   237  // NullInt32 represents an int32 that may be null.
   238  // NullInt32 implements the Scanner interface so
   239  // it can be used as a scan destination, similar to NullString.
   240  type NullInt32 struct {
   241  	Int32 int32
   242  	Valid bool // Valid is true if Int32 is not NULL
   243  }
   244  
   245  // Scan implements the Scanner interface.
   246  func (n *NullInt32) Scan(value any) error {
   247  	if value == nil {
   248  		n.Int32, n.Valid = 0, false
   249  		return nil
   250  	}
   251  	n.Valid = true
   252  	return convertAssign(&n.Int32, value)
   253  }
   254  
   255  // Value implements the driver Valuer interface.
   256  func (n NullInt32) Value() (driver.Value, error) {
   257  	if !n.Valid {
   258  		return nil, nil
   259  	}
   260  	return int64(n.Int32), nil
   261  }
   262  
   263  // NullInt16 represents an int16 that may be null.
   264  // NullInt16 implements the Scanner interface so
   265  // it can be used as a scan destination, similar to NullString.
   266  type NullInt16 struct {
   267  	Int16 int16
   268  	Valid bool // Valid is true if Int16 is not NULL
   269  }
   270  
   271  // Scan implements the Scanner interface.
   272  func (n *NullInt16) Scan(value any) error {
   273  	if value == nil {
   274  		n.Int16, n.Valid = 0, false
   275  		return nil
   276  	}
   277  	err := convertAssign(&n.Int16, value)
   278  	n.Valid = err == nil
   279  	return err
   280  }
   281  
   282  // Value implements the driver Valuer interface.
   283  func (n NullInt16) Value() (driver.Value, error) {
   284  	if !n.Valid {
   285  		return nil, nil
   286  	}
   287  	return int64(n.Int16), nil
   288  }
   289  
   290  // NullByte represents a byte that may be null.
   291  // NullByte implements the Scanner interface so
   292  // it can be used as a scan destination, similar to NullString.
   293  type NullByte struct {
   294  	Byte  byte
   295  	Valid bool // Valid is true if Byte is not NULL
   296  }
   297  
   298  // Scan implements the Scanner interface.
   299  func (n *NullByte) Scan(value any) error {
   300  	if value == nil {
   301  		n.Byte, n.Valid = 0, false
   302  		return nil
   303  	}
   304  	err := convertAssign(&n.Byte, value)
   305  	n.Valid = err == nil
   306  	return err
   307  }
   308  
   309  // Value implements the driver Valuer interface.
   310  func (n NullByte) Value() (driver.Value, error) {
   311  	if !n.Valid {
   312  		return nil, nil
   313  	}
   314  	return int64(n.Byte), nil
   315  }
   316  
   317  // NullFloat64 represents a float64 that may be null.
   318  // NullFloat64 implements the Scanner interface so
   319  // it can be used as a scan destination, similar to NullString.
   320  type NullFloat64 struct {
   321  	Float64 float64
   322  	Valid   bool // Valid is true if Float64 is not NULL
   323  }
   324  
   325  // Scan implements the Scanner interface.
   326  func (n *NullFloat64) Scan(value any) error {
   327  	if value == nil {
   328  		n.Float64, n.Valid = 0, false
   329  		return nil
   330  	}
   331  	n.Valid = true
   332  	return convertAssign(&n.Float64, value)
   333  }
   334  
   335  // Value implements the driver Valuer interface.
   336  func (n NullFloat64) Value() (driver.Value, error) {
   337  	if !n.Valid {
   338  		return nil, nil
   339  	}
   340  	return n.Float64, nil
   341  }
   342  
   343  // NullBool represents a bool that may be null.
   344  // NullBool implements the Scanner interface so
   345  // it can be used as a scan destination, similar to NullString.
   346  type NullBool struct {
   347  	Bool  bool
   348  	Valid bool // Valid is true if Bool is not NULL
   349  }
   350  
   351  // Scan implements the Scanner interface.
   352  func (n *NullBool) Scan(value any) error {
   353  	if value == nil {
   354  		n.Bool, n.Valid = false, false
   355  		return nil
   356  	}
   357  	n.Valid = true
   358  	return convertAssign(&n.Bool, value)
   359  }
   360  
   361  // Value implements the driver Valuer interface.
   362  func (n NullBool) Value() (driver.Value, error) {
   363  	if !n.Valid {
   364  		return nil, nil
   365  	}
   366  	return n.Bool, nil
   367  }
   368  
   369  // NullTime represents a time.Time that may be null.
   370  // NullTime implements the Scanner interface so
   371  // it can be used as a scan destination, similar to NullString.
   372  type NullTime struct {
   373  	Time  time.Time
   374  	Valid bool // Valid is true if Time is not NULL
   375  }
   376  
   377  // Scan implements the Scanner interface.
   378  func (n *NullTime) Scan(value any) error {
   379  	if value == nil {
   380  		n.Time, n.Valid = time.Time{}, false
   381  		return nil
   382  	}
   383  	n.Valid = true
   384  	return convertAssign(&n.Time, value)
   385  }
   386  
   387  // Value implements the driver Valuer interface.
   388  func (n NullTime) Value() (driver.Value, error) {
   389  	if !n.Valid {
   390  		return nil, nil
   391  	}
   392  	return n.Time, nil
   393  }
   394  
   395  // Scanner is an interface used by Scan.
   396  type Scanner interface {
   397  	// Scan assigns a value from a database driver.
   398  	//
   399  	// The src value will be of one of the following types:
   400  	//
   401  	//    int64
   402  	//    float64
   403  	//    bool
   404  	//    []byte
   405  	//    string
   406  	//    time.Time
   407  	//    nil - for NULL values
   408  	//
   409  	// An error should be returned if the value cannot be stored
   410  	// without loss of information.
   411  	//
   412  	// Reference types such as []byte are only valid until the next call to Scan
   413  	// and should not be retained. Their underlying memory is owned by the driver.
   414  	// If retention is necessary, copy their values before the next call to Scan.
   415  	Scan(src any) error
   416  }
   417  
   418  // Out may be used to retrieve OUTPUT value parameters from stored procedures.
   419  //
   420  // Not all drivers and databases support OUTPUT value parameters.
   421  //
   422  // Example usage:
   423  //
   424  //   var outArg string
   425  //   _, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", sql.Out{Dest: &outArg}))
   426  type Out struct {
   427  	_Named_Fields_Required struct{}
   428  
   429  	// Dest is a pointer to the value that will be set to the result of the
   430  	// stored procedure's OUTPUT parameter.
   431  	Dest any
   432  
   433  	// In is whether the parameter is an INOUT parameter. If so, the input value to the stored
   434  	// procedure is the dereferenced value of Dest's pointer, which is then replaced with
   435  	// the output value.
   436  	In bool
   437  }
   438  
   439  // ErrNoRows is returned by Scan when QueryRow doesn't return a
   440  // row. In such a case, QueryRow returns a placeholder *Row value that
   441  // defers this error until a Scan.
   442  var ErrNoRows = errors.New("sql: no rows in result set")
   443  
   444  // DB is a database handle representing a pool of zero or more
   445  // underlying connections. It's safe for concurrent use by multiple
   446  // goroutines.
   447  //
   448  // The sql package creates and frees connections automatically; it
   449  // also maintains a free pool of idle connections. If the database has
   450  // a concept of per-connection state, such state can be reliably observed
   451  // within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the
   452  // returned Tx is bound to a single connection. Once Commit or
   453  // Rollback is called on the transaction, that transaction's
   454  // connection is returned to DB's idle connection pool. The pool size
   455  // can be controlled with SetMaxIdleConns.
   456  type DB struct {
   457  	// Atomic access only. At top of struct to prevent mis-alignment
   458  	// on 32-bit platforms. Of type time.Duration.
   459  	waitDuration int64 // Total time waited for new connections.
   460  
   461  	connector driver.Connector
   462  	// numClosed is an atomic counter which represents a total number of
   463  	// closed connections. Stmt.openStmt checks it before cleaning closed
   464  	// connections in Stmt.css.
   465  	numClosed uint64
   466  
   467  	mu           sync.Mutex    // protects following fields
   468  	freeConn     []*driverConn // free connections ordered by returnedAt oldest to newest
   469  	connRequests map[uint64]chan connRequest
   470  	nextRequest  uint64 // Next key to use in connRequests.
   471  	numOpen      int    // number of opened and pending open connections
   472  	// Used to signal the need for new connections
   473  	// a goroutine running connectionOpener() reads on this chan and
   474  	// maybeOpenNewConnections sends on the chan (one send per needed connection)
   475  	// It is closed during db.Close(). The close tells the connectionOpener
   476  	// goroutine to exit.
   477  	openerCh          chan struct{}
   478  	closed            bool
   479  	dep               map[finalCloser]depSet
   480  	lastPut           map[*driverConn]string // stacktrace of last conn's put; debug only
   481  	maxIdleCount      int                    // zero means defaultMaxIdleConns; negative means 0
   482  	maxOpen           int                    // <= 0 means unlimited
   483  	maxLifetime       time.Duration          // maximum amount of time a connection may be reused
   484  	maxIdleTime       time.Duration          // maximum amount of time a connection may be idle before being closed
   485  	cleanerCh         chan struct{}
   486  	waitCount         int64 // Total number of connections waited for.
   487  	maxIdleClosed     int64 // Total number of connections closed due to idle count.
   488  	maxIdleTimeClosed int64 // Total number of connections closed due to idle time.
   489  	maxLifetimeClosed int64 // Total number of connections closed due to max connection lifetime limit.
   490  
   491  	stop func() // stop cancels the connection opener.
   492  }
   493  
   494  // connReuseStrategy determines how (*DB).conn returns database connections.
   495  type connReuseStrategy uint8
   496  
   497  const (
   498  	// alwaysNewConn forces a new connection to the database.
   499  	alwaysNewConn connReuseStrategy = iota
   500  	// cachedOrNewConn returns a cached connection, if available, else waits
   501  	// for one to become available (if MaxOpenConns has been reached) or
   502  	// creates a new database connection.
   503  	cachedOrNewConn
   504  )
   505  
   506  // driverConn wraps a driver.Conn with a mutex, to
   507  // be held during all calls into the Conn. (including any calls onto
   508  // interfaces returned via that Conn, such as calls on Tx, Stmt,
   509  // Result, Rows)
   510  type driverConn struct {
   511  	db        *DB
   512  	createdAt time.Time
   513  
   514  	sync.Mutex  // guards following
   515  	ci          driver.Conn
   516  	needReset   bool // The connection session should be reset before use if true.
   517  	closed      bool
   518  	finalClosed bool // ci.Close has been called
   519  	openStmt    map[*driverStmt]bool
   520  
   521  	// guarded by db.mu
   522  	inUse      bool
   523  	returnedAt time.Time // Time the connection was created or returned.
   524  	onPut      []func()  // code (with db.mu held) run when conn is next returned
   525  	dbmuClosed bool      // same as closed, but guarded by db.mu, for removeClosedStmtLocked
   526  }
   527  
   528  func (dc *driverConn) releaseConn(err error) {
   529  	dc.db.putConn(dc, err, true)
   530  }
   531  
   532  func (dc *driverConn) removeOpenStmt(ds *driverStmt) {
   533  	dc.Lock()
   534  	defer dc.Unlock()
   535  	delete(dc.openStmt, ds)
   536  }
   537  
   538  func (dc *driverConn) expired(timeout time.Duration) bool {
   539  	if timeout <= 0 {
   540  		return false
   541  	}
   542  	return dc.createdAt.Add(timeout).Before(nowFunc())
   543  }
   544  
   545  // resetSession checks if the driver connection needs the
   546  // session to be reset and if required, resets it.
   547  func (dc *driverConn) resetSession(ctx context.Context) error {
   548  	dc.Lock()
   549  	defer dc.Unlock()
   550  
   551  	if !dc.needReset {
   552  		return nil
   553  	}
   554  	if cr, ok := dc.ci.(driver.SessionResetter); ok {
   555  		return cr.ResetSession(ctx)
   556  	}
   557  	return nil
   558  }
   559  
   560  // validateConnection checks if the connection is valid and can
   561  // still be used. It also marks the session for reset if required.
   562  func (dc *driverConn) validateConnection(needsReset bool) bool {
   563  	dc.Lock()
   564  	defer dc.Unlock()
   565  
   566  	if needsReset {
   567  		dc.needReset = true
   568  	}
   569  	if cv, ok := dc.ci.(driver.Validator); ok {
   570  		return cv.IsValid()
   571  	}
   572  	return true
   573  }
   574  
   575  // prepareLocked prepares the query on dc. When cg == nil the dc must keep track of
   576  // the prepared statements in a pool.
   577  func (dc *driverConn) prepareLocked(ctx context.Context, cg stmtConnGrabber, query string) (*driverStmt, error) {
   578  	si, err := ctxDriverPrepare(ctx, dc.ci, query)
   579  	if err != nil {
   580  		return nil, err
   581  	}
   582  	ds := &driverStmt{Locker: dc, si: si}
   583  
   584  	// No need to manage open statements if there is a single connection grabber.
   585  	if cg != nil {
   586  		return ds, nil
   587  	}
   588  
   589  	// Track each driverConn's open statements, so we can close them
   590  	// before closing the conn.
   591  	//
   592  	// Wrap all driver.Stmt is *driverStmt to ensure they are only closed once.
   593  	if dc.openStmt == nil {
   594  		dc.openStmt = make(map[*driverStmt]bool)
   595  	}
   596  	dc.openStmt[ds] = true
   597  	return ds, nil
   598  }
   599  
   600  // the dc.db's Mutex is held.
   601  func (dc *driverConn) closeDBLocked() func() error {
   602  	dc.Lock()
   603  	defer dc.Unlock()
   604  	if dc.closed {
   605  		return func() error { return errors.New("sql: duplicate driverConn close") }
   606  	}
   607  	dc.closed = true
   608  	return dc.db.removeDepLocked(dc, dc)
   609  }
   610  
   611  func (dc *driverConn) Close() error {
   612  	dc.Lock()
   613  	if dc.closed {
   614  		dc.Unlock()
   615  		return errors.New("sql: duplicate driverConn close")
   616  	}
   617  	dc.closed = true
   618  	dc.Unlock() // not defer; removeDep finalClose calls may need to lock
   619  
   620  	// And now updates that require holding dc.mu.Lock.
   621  	dc.db.mu.Lock()
   622  	dc.dbmuClosed = true
   623  	fn := dc.db.removeDepLocked(dc, dc)
   624  	dc.db.mu.Unlock()
   625  	return fn()
   626  }
   627  
   628  func (dc *driverConn) finalClose() error {
   629  	var err error
   630  
   631  	// Each *driverStmt has a lock to the dc. Copy the list out of the dc
   632  	// before calling close on each stmt.
   633  	var openStmt []*driverStmt
   634  	withLock(dc, func() {
   635  		openStmt = make([]*driverStmt, 0, len(dc.openStmt))
   636  		for ds := range dc.openStmt {
   637  			openStmt = append(openStmt, ds)
   638  		}
   639  		dc.openStmt = nil
   640  	})
   641  	for _, ds := range openStmt {
   642  		ds.Close()
   643  	}
   644  	withLock(dc, func() {
   645  		dc.finalClosed = true
   646  		err = dc.ci.Close()
   647  		dc.ci = nil
   648  	})
   649  
   650  	dc.db.mu.Lock()
   651  	dc.db.numOpen--
   652  	dc.db.maybeOpenNewConnections()
   653  	dc.db.mu.Unlock()
   654  
   655  	atomic.AddUint64(&dc.db.numClosed, 1)
   656  	return err
   657  }
   658  
   659  // driverStmt associates a driver.Stmt with the
   660  // *driverConn from which it came, so the driverConn's lock can be
   661  // held during calls.
   662  type driverStmt struct {
   663  	sync.Locker // the *driverConn
   664  	si          driver.Stmt
   665  	closed      bool
   666  	closeErr    error // return value of previous Close call
   667  }
   668  
   669  // Close ensures driver.Stmt is only closed once and always returns the same
   670  // result.
   671  func (ds *driverStmt) Close() error {
   672  	ds.Lock()
   673  	defer ds.Unlock()
   674  	if ds.closed {
   675  		return ds.closeErr
   676  	}
   677  	ds.closed = true
   678  	ds.closeErr = ds.si.Close()
   679  	return ds.closeErr
   680  }
   681  
   682  // depSet is a finalCloser's outstanding dependencies
   683  type depSet map[any]bool // set of true bools
   684  
   685  // The finalCloser interface is used by (*DB).addDep and related
   686  // dependency reference counting.
   687  type finalCloser interface {
   688  	// finalClose is called when the reference count of an object
   689  	// goes to zero. (*DB).mu is not held while calling it.
   690  	finalClose() error
   691  }
   692  
   693  // addDep notes that x now depends on dep, and x's finalClose won't be
   694  // called until all of x's dependencies are removed with removeDep.
   695  func (db *DB) addDep(x finalCloser, dep any) {
   696  	db.mu.Lock()
   697  	defer db.mu.Unlock()
   698  	db.addDepLocked(x, dep)
   699  }
   700  
   701  func (db *DB) addDepLocked(x finalCloser, dep any) {
   702  	if db.dep == nil {
   703  		db.dep = make(map[finalCloser]depSet)
   704  	}
   705  	xdep := db.dep[x]
   706  	if xdep == nil {
   707  		xdep = make(depSet)
   708  		db.dep[x] = xdep
   709  	}
   710  	xdep[dep] = true
   711  }
   712  
   713  // removeDep notes that x no longer depends on dep.
   714  // If x still has dependencies, nil is returned.
   715  // If x no longer has any dependencies, its finalClose method will be
   716  // called and its error value will be returned.
   717  func (db *DB) removeDep(x finalCloser, dep any) error {
   718  	db.mu.Lock()
   719  	fn := db.removeDepLocked(x, dep)
   720  	db.mu.Unlock()
   721  	return fn()
   722  }
   723  
   724  func (db *DB) removeDepLocked(x finalCloser, dep any) func() error {
   725  
   726  	xdep, ok := db.dep[x]
   727  	if !ok {
   728  		panic(fmt.Sprintf("unpaired removeDep: no deps for %T", x))
   729  	}
   730  
   731  	l0 := len(xdep)
   732  	delete(xdep, dep)
   733  
   734  	switch len(xdep) {
   735  	case l0:
   736  		// Nothing removed. Shouldn't happen.
   737  		panic(fmt.Sprintf("unpaired removeDep: no %T dep on %T", dep, x))
   738  	case 0:
   739  		// No more dependencies.
   740  		delete(db.dep, x)
   741  		return x.finalClose
   742  	default:
   743  		// Dependencies remain.
   744  		return func() error { return nil }
   745  	}
   746  }
   747  
   748  // This is the size of the connectionOpener request chan (DB.openerCh).
   749  // This value should be larger than the maximum typical value
   750  // used for db.maxOpen. If maxOpen is significantly larger than
   751  // connectionRequestQueueSize then it is possible for ALL calls into the *DB
   752  // to block until the connectionOpener can satisfy the backlog of requests.
   753  var connectionRequestQueueSize = 1000000
   754  
   755  type dsnConnector struct {
   756  	dsn    string
   757  	driver driver.Driver
   758  }
   759  
   760  func (t dsnConnector) Connect(_ context.Context) (driver.Conn, error) {
   761  	return t.driver.Open(t.dsn)
   762  }
   763  
   764  func (t dsnConnector) Driver() driver.Driver {
   765  	return t.driver
   766  }
   767  
   768  // OpenDB opens a database using a Connector, allowing drivers to
   769  // bypass a string based data source name.
   770  //
   771  // Most users will open a database via a driver-specific connection
   772  // helper function that returns a *DB. No database drivers are included
   773  // in the Go standard library. See https://golang.org/s/sqldrivers for
   774  // a list of third-party drivers.
   775  //
   776  // OpenDB may just validate its arguments without creating a connection
   777  // to the database. To verify that the data source name is valid, call
   778  // Ping.
   779  //
   780  // The returned DB is safe for concurrent use by multiple goroutines
   781  // and maintains its own pool of idle connections. Thus, the OpenDB
   782  // function should be called just once. It is rarely necessary to
   783  // close a DB.
   784  func OpenDB(c driver.Connector) *DB {
   785  	ctx, cancel := context.WithCancel(context.Background())
   786  	db := &DB{
   787  		connector:    c,
   788  		openerCh:     make(chan struct{}, connectionRequestQueueSize),
   789  		lastPut:      make(map[*driverConn]string),
   790  		connRequests: make(map[uint64]chan connRequest),
   791  		stop:         cancel,
   792  	}
   793  
   794  	go db.connectionOpener(ctx)
   795  
   796  	return db
   797  }
   798  
   799  // Open opens a database specified by its database driver name and a
   800  // driver-specific data source name, usually consisting of at least a
   801  // database name and connection information.
   802  //
   803  // Most users will open a database via a driver-specific connection
   804  // helper function that returns a *DB. No database drivers are included
   805  // in the Go standard library. See https://golang.org/s/sqldrivers for
   806  // a list of third-party drivers.
   807  //
   808  // Open may just validate its arguments without creating a connection
   809  // to the database. To verify that the data source name is valid, call
   810  // Ping.
   811  //
   812  // The returned DB is safe for concurrent use by multiple goroutines
   813  // and maintains its own pool of idle connections. Thus, the Open
   814  // function should be called just once. It is rarely necessary to
   815  // close a DB.
   816  func Open(driverName, dataSourceName string) (*DB, error) {
   817  	driversMu.RLock()
   818  	driveri, ok := drivers[driverName]
   819  	driversMu.RUnlock()
   820  	if !ok {
   821  		return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName)
   822  	}
   823  
   824  	if driverCtx, ok := driveri.(driver.DriverContext); ok {
   825  		connector, err := driverCtx.OpenConnector(dataSourceName)
   826  		if err != nil {
   827  			return nil, err
   828  		}
   829  		return OpenDB(connector), nil
   830  	}
   831  
   832  	return OpenDB(dsnConnector{dsn: dataSourceName, driver: driveri}), nil
   833  }
   834  
   835  func (db *DB) pingDC(ctx context.Context, dc *driverConn, release func(error)) error {
   836  	var err error
   837  	if pinger, ok := dc.ci.(driver.Pinger); ok {
   838  		withLock(dc, func() {
   839  			err = pinger.Ping(ctx)
   840  		})
   841  	}
   842  	release(err)
   843  	return err
   844  }
   845  
   846  // PingContext verifies a connection to the database is still alive,
   847  // establishing a connection if necessary.
   848  func (db *DB) PingContext(ctx context.Context) error {
   849  	var dc *driverConn
   850  	var err error
   851  	var isBadConn bool
   852  	for i := 0; i < maxBadConnRetries; i++ {
   853  		dc, err = db.conn(ctx, cachedOrNewConn)
   854  		isBadConn = errors.Is(err, driver.ErrBadConn)
   855  		if !isBadConn {
   856  			break
   857  		}
   858  	}
   859  	if isBadConn {
   860  		dc, err = db.conn(ctx, alwaysNewConn)
   861  	}
   862  	if err != nil {
   863  		return err
   864  	}
   865  
   866  	return db.pingDC(ctx, dc, dc.releaseConn)
   867  }
   868  
   869  // Ping verifies a connection to the database is still alive,
   870  // establishing a connection if necessary.
   871  //
   872  // Ping uses context.Background internally; to specify the context, use
   873  // PingContext.
   874  func (db *DB) Ping() error {
   875  	return db.PingContext(context.Background())
   876  }
   877  
   878  // Close closes the database and prevents new queries from starting.
   879  // Close then waits for all queries that have started processing on the server
   880  // to finish.
   881  //
   882  // It is rare to Close a DB, as the DB handle is meant to be
   883  // long-lived and shared between many goroutines.
   884  func (db *DB) Close() error {
   885  	db.mu.Lock()
   886  	if db.closed { // Make DB.Close idempotent
   887  		db.mu.Unlock()
   888  		return nil
   889  	}
   890  	if db.cleanerCh != nil {
   891  		close(db.cleanerCh)
   892  	}
   893  	var err error
   894  	fns := make([]func() error, 0, len(db.freeConn))
   895  	for _, dc := range db.freeConn {
   896  		fns = append(fns, dc.closeDBLocked())
   897  	}
   898  	db.freeConn = nil
   899  	db.closed = true
   900  	for _, req := range db.connRequests {
   901  		close(req)
   902  	}
   903  	db.mu.Unlock()
   904  	for _, fn := range fns {
   905  		err1 := fn()
   906  		if err1 != nil {
   907  			err = err1
   908  		}
   909  	}
   910  	db.stop()
   911  	if c, ok := db.connector.(io.Closer); ok {
   912  		err1 := c.Close()
   913  		if err1 != nil {
   914  			err = err1
   915  		}
   916  	}
   917  	return err
   918  }
   919  
   920  const defaultMaxIdleConns = 2
   921  
   922  func (db *DB) maxIdleConnsLocked() int {
   923  	n := db.maxIdleCount
   924  	switch {
   925  	case n == 0:
   926  		// TODO(bradfitz): ask driver, if supported, for its default preference
   927  		return defaultMaxIdleConns
   928  	case n < 0:
   929  		return 0
   930  	default:
   931  		return n
   932  	}
   933  }
   934  
   935  func (db *DB) shortestIdleTimeLocked() time.Duration {
   936  	if db.maxIdleTime <= 0 {
   937  		return db.maxLifetime
   938  	}
   939  	if db.maxLifetime <= 0 {
   940  		return db.maxIdleTime
   941  	}
   942  
   943  	min := db.maxIdleTime
   944  	if min > db.maxLifetime {
   945  		min = db.maxLifetime
   946  	}
   947  	return min
   948  }
   949  
   950  // SetMaxIdleConns sets the maximum number of connections in the idle
   951  // connection pool.
   952  //
   953  // If MaxOpenConns is greater than 0 but less than the new MaxIdleConns,
   954  // then the new MaxIdleConns will be reduced to match the MaxOpenConns limit.
   955  //
   956  // If n <= 0, no idle connections are retained.
   957  //
   958  // The default max idle connections is currently 2. This may change in
   959  // a future release.
   960  func (db *DB) SetMaxIdleConns(n int) {
   961  	db.mu.Lock()
   962  	if n > 0 {
   963  		db.maxIdleCount = n
   964  	} else {
   965  		// No idle connections.
   966  		db.maxIdleCount = -1
   967  	}
   968  	// Make sure maxIdle doesn't exceed maxOpen
   969  	if db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen {
   970  		db.maxIdleCount = db.maxOpen
   971  	}
   972  	var closing []*driverConn
   973  	idleCount := len(db.freeConn)
   974  	maxIdle := db.maxIdleConnsLocked()
   975  	if idleCount > maxIdle {
   976  		closing = db.freeConn[maxIdle:]
   977  		db.freeConn = db.freeConn[:maxIdle]
   978  	}
   979  	db.maxIdleClosed += int64(len(closing))
   980  	db.mu.Unlock()
   981  	for _, c := range closing {
   982  		c.Close()
   983  	}
   984  }
   985  
   986  // SetMaxOpenConns sets the maximum number of open connections to the database.
   987  //
   988  // If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than
   989  // MaxIdleConns, then MaxIdleConns will be reduced to match the new
   990  // MaxOpenConns limit.
   991  //
   992  // If n <= 0, then there is no limit on the number of open connections.
   993  // The default is 0 (unlimited).
   994  func (db *DB) SetMaxOpenConns(n int) {
   995  	db.mu.Lock()
   996  	db.maxOpen = n
   997  	if n < 0 {
   998  		db.maxOpen = 0
   999  	}
  1000  	syncMaxIdle := db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen
  1001  	db.mu.Unlock()
  1002  	if syncMaxIdle {
  1003  		db.SetMaxIdleConns(n)
  1004  	}
  1005  }
  1006  
  1007  // SetConnMaxLifetime sets the maximum amount of time a connection may be reused.
  1008  //
  1009  // Expired connections may be closed lazily before reuse.
  1010  //
  1011  // If d <= 0, connections are not closed due to a connection's age.
  1012  func (db *DB) SetConnMaxLifetime(d time.Duration) {
  1013  	if d < 0 {
  1014  		d = 0
  1015  	}
  1016  	db.mu.Lock()
  1017  	// Wake cleaner up when lifetime is shortened.
  1018  	if d > 0 && d < db.maxLifetime && db.cleanerCh != nil {
  1019  		select {
  1020  		case db.cleanerCh <- struct{}{}:
  1021  		default:
  1022  		}
  1023  	}
  1024  	db.maxLifetime = d
  1025  	db.startCleanerLocked()
  1026  	db.mu.Unlock()
  1027  }
  1028  
  1029  // SetConnMaxIdleTime sets the maximum amount of time a connection may be idle.
  1030  //
  1031  // Expired connections may be closed lazily before reuse.
  1032  //
  1033  // If d <= 0, connections are not closed due to a connection's idle time.
  1034  func (db *DB) SetConnMaxIdleTime(d time.Duration) {
  1035  	if d < 0 {
  1036  		d = 0
  1037  	}
  1038  	db.mu.Lock()
  1039  	defer db.mu.Unlock()
  1040  
  1041  	// Wake cleaner up when idle time is shortened.
  1042  	if d > 0 && d < db.maxIdleTime && db.cleanerCh != nil {
  1043  		select {
  1044  		case db.cleanerCh <- struct{}{}:
  1045  		default:
  1046  		}
  1047  	}
  1048  	db.maxIdleTime = d
  1049  	db.startCleanerLocked()
  1050  }
  1051  
  1052  // startCleanerLocked starts connectionCleaner if needed.
  1053  func (db *DB) startCleanerLocked() {
  1054  	if (db.maxLifetime > 0 || db.maxIdleTime > 0) && db.numOpen > 0 && db.cleanerCh == nil {
  1055  		db.cleanerCh = make(chan struct{}, 1)
  1056  		go db.connectionCleaner(db.shortestIdleTimeLocked())
  1057  	}
  1058  }
  1059  
  1060  func (db *DB) connectionCleaner(d time.Duration) {
  1061  	const minInterval = time.Second
  1062  
  1063  	if d < minInterval {
  1064  		d = minInterval
  1065  	}
  1066  	t := time.NewTimer(d)
  1067  
  1068  	for {
  1069  		select {
  1070  		case <-t.C:
  1071  		case <-db.cleanerCh: // maxLifetime was changed or db was closed.
  1072  		}
  1073  
  1074  		db.mu.Lock()
  1075  
  1076  		d = db.shortestIdleTimeLocked()
  1077  		if db.closed || db.numOpen == 0 || d <= 0 {
  1078  			db.cleanerCh = nil
  1079  			db.mu.Unlock()
  1080  			return
  1081  		}
  1082  
  1083  		d, closing := db.connectionCleanerRunLocked(d)
  1084  		db.mu.Unlock()
  1085  		for _, c := range closing {
  1086  			c.Close()
  1087  		}
  1088  
  1089  		if d < minInterval {
  1090  			d = minInterval
  1091  		}
  1092  
  1093  		if !t.Stop() {
  1094  			select {
  1095  			case <-t.C:
  1096  			default:
  1097  			}
  1098  		}
  1099  		t.Reset(d)
  1100  	}
  1101  }
  1102  
  1103  // connectionCleanerRunLocked removes connections that should be closed from
  1104  // freeConn and returns them along side an updated duration to the next check
  1105  // if a quicker check is required to ensure connections are checked appropriately.
  1106  func (db *DB) connectionCleanerRunLocked(d time.Duration) (time.Duration, []*driverConn) {
  1107  	var idleClosing int64
  1108  	var closing []*driverConn
  1109  	if db.maxIdleTime > 0 {
  1110  		// As freeConn is ordered by returnedAt process
  1111  		// in reverse order to minimise the work needed.
  1112  		idleSince := nowFunc().Add(-db.maxIdleTime)
  1113  		last := len(db.freeConn) - 1
  1114  		for i := last; i >= 0; i-- {
  1115  			c := db.freeConn[i]
  1116  			if c.returnedAt.Before(idleSince) {
  1117  				i++
  1118  				closing = db.freeConn[:i:i]
  1119  				db.freeConn = db.freeConn[i:]
  1120  				idleClosing = int64(len(closing))
  1121  				db.maxIdleTimeClosed += idleClosing
  1122  				break
  1123  			}
  1124  		}
  1125  
  1126  		if len(db.freeConn) > 0 {
  1127  			c := db.freeConn[0]
  1128  			if d2 := c.returnedAt.Sub(idleSince); d2 < d {
  1129  				// Ensure idle connections are cleaned up as soon as
  1130  				// possible.
  1131  				d = d2
  1132  			}
  1133  		}
  1134  	}
  1135  
  1136  	if db.maxLifetime > 0 {
  1137  		expiredSince := nowFunc().Add(-db.maxLifetime)
  1138  		for i := 0; i < len(db.freeConn); i++ {
  1139  			c := db.freeConn[i]
  1140  			if c.createdAt.Before(expiredSince) {
  1141  				closing = append(closing, c)
  1142  
  1143  				last := len(db.freeConn) - 1
  1144  				// Use slow delete as order is required to ensure
  1145  				// connections are reused least idle time first.
  1146  				copy(db.freeConn[i:], db.freeConn[i+1:])
  1147  				db.freeConn[last] = nil
  1148  				db.freeConn = db.freeConn[:last]
  1149  				i--
  1150  			} else if d2 := c.createdAt.Sub(expiredSince); d2 < d {
  1151  				// Prevent connections sitting the freeConn when they
  1152  				// have expired by updating our next deadline d.
  1153  				d = d2
  1154  			}
  1155  		}
  1156  		db.maxLifetimeClosed += int64(len(closing)) - idleClosing
  1157  	}
  1158  
  1159  	return d, closing
  1160  }
  1161  
  1162  // DBStats contains database statistics.
  1163  type DBStats struct {
  1164  	MaxOpenConnections int // Maximum number of open connections to the database.
  1165  
  1166  	// Pool Status
  1167  	OpenConnections int // The number of established connections both in use and idle.
  1168  	InUse           int // The number of connections currently in use.
  1169  	Idle            int // The number of idle connections.
  1170  
  1171  	// Counters
  1172  	WaitCount         int64         // The total number of connections waited for.
  1173  	WaitDuration      time.Duration // The total time blocked waiting for a new connection.
  1174  	MaxIdleClosed     int64         // The total number of connections closed due to SetMaxIdleConns.
  1175  	MaxIdleTimeClosed int64         // The total number of connections closed due to SetConnMaxIdleTime.
  1176  	MaxLifetimeClosed int64         // The total number of connections closed due to SetConnMaxLifetime.
  1177  }
  1178  
  1179  // Stats returns database statistics.
  1180  func (db *DB) Stats() DBStats {
  1181  	wait := atomic.LoadInt64(&db.waitDuration)
  1182  
  1183  	db.mu.Lock()
  1184  	defer db.mu.Unlock()
  1185  
  1186  	stats := DBStats{
  1187  		MaxOpenConnections: db.maxOpen,
  1188  
  1189  		Idle:            len(db.freeConn),
  1190  		OpenConnections: db.numOpen,
  1191  		InUse:           db.numOpen - len(db.freeConn),
  1192  
  1193  		WaitCount:         db.waitCount,
  1194  		WaitDuration:      time.Duration(wait),
  1195  		MaxIdleClosed:     db.maxIdleClosed,
  1196  		MaxIdleTimeClosed: db.maxIdleTimeClosed,
  1197  		MaxLifetimeClosed: db.maxLifetimeClosed,
  1198  	}
  1199  	return stats
  1200  }
  1201  
  1202  // Assumes db.mu is locked.
  1203  // If there are connRequests and the connection limit hasn't been reached,
  1204  // then tell the connectionOpener to open new connections.
  1205  func (db *DB) maybeOpenNewConnections() {
  1206  	numRequests := len(db.connRequests)
  1207  	if db.maxOpen > 0 {
  1208  		numCanOpen := db.maxOpen - db.numOpen
  1209  		if numRequests > numCanOpen {
  1210  			numRequests = numCanOpen
  1211  		}
  1212  	}
  1213  	for numRequests > 0 {
  1214  		db.numOpen++ // optimistically
  1215  		numRequests--
  1216  		if db.closed {
  1217  			return
  1218  		}
  1219  		db.openerCh <- struct{}{}
  1220  	}
  1221  }
  1222  
  1223  // Runs in a separate goroutine, opens new connections when requested.
  1224  func (db *DB) connectionOpener(ctx context.Context) {
  1225  	for {
  1226  		select {
  1227  		case <-ctx.Done():
  1228  			return
  1229  		case <-db.openerCh:
  1230  			db.openNewConnection(ctx)
  1231  		}
  1232  	}
  1233  }
  1234  
  1235  // Open one new connection
  1236  func (db *DB) openNewConnection(ctx context.Context) {
  1237  	// maybeOpenNewConnections has already executed db.numOpen++ before it sent
  1238  	// on db.openerCh. This function must execute db.numOpen-- if the
  1239  	// connection fails or is closed before returning.
  1240  	ci, err := db.connector.Connect(ctx)
  1241  	db.mu.Lock()
  1242  	defer db.mu.Unlock()
  1243  	if db.closed {
  1244  		if err == nil {
  1245  			ci.Close()
  1246  		}
  1247  		db.numOpen--
  1248  		return
  1249  	}
  1250  	if err != nil {
  1251  		db.numOpen--
  1252  		db.putConnDBLocked(nil, err)
  1253  		db.maybeOpenNewConnections()
  1254  		return
  1255  	}
  1256  	dc := &driverConn{
  1257  		db:         db,
  1258  		createdAt:  nowFunc(),
  1259  		returnedAt: nowFunc(),
  1260  		ci:         ci,
  1261  	}
  1262  	if db.putConnDBLocked(dc, err) {
  1263  		db.addDepLocked(dc, dc)
  1264  	} else {
  1265  		db.numOpen--
  1266  		ci.Close()
  1267  	}
  1268  }
  1269  
  1270  // connRequest represents one request for a new connection
  1271  // When there are no idle connections available, DB.conn will create
  1272  // a new connRequest and put it on the db.connRequests list.
  1273  type connRequest struct {
  1274  	conn *driverConn
  1275  	err  error
  1276  }
  1277  
  1278  var errDBClosed = errors.New("sql: database is closed")
  1279  
  1280  // nextRequestKeyLocked returns the next connection request key.
  1281  // It is assumed that nextRequest will not overflow.
  1282  func (db *DB) nextRequestKeyLocked() uint64 {
  1283  	next := db.nextRequest
  1284  	db.nextRequest++
  1285  	return next
  1286  }
  1287  
  1288  // conn returns a newly-opened or cached *driverConn.
  1289  func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) {
  1290  	db.mu.Lock()
  1291  	if db.closed {
  1292  		db.mu.Unlock()
  1293  		return nil, errDBClosed
  1294  	}
  1295  	// Check if the context is expired.
  1296  	select {
  1297  	default:
  1298  	case <-ctx.Done():
  1299  		db.mu.Unlock()
  1300  		return nil, ctx.Err()
  1301  	}
  1302  	lifetime := db.maxLifetime
  1303  
  1304  	// Prefer a free connection, if possible.
  1305  	last := len(db.freeConn) - 1
  1306  	if strategy == cachedOrNewConn && last >= 0 {
  1307  		// Reuse the lowest idle time connection so we can close
  1308  		// connections which remain idle as soon as possible.
  1309  		conn := db.freeConn[last]
  1310  		db.freeConn = db.freeConn[:last]
  1311  		conn.inUse = true
  1312  		if conn.expired(lifetime) {
  1313  			db.maxLifetimeClosed++
  1314  			db.mu.Unlock()
  1315  			conn.Close()
  1316  			return nil, driver.ErrBadConn
  1317  		}
  1318  		db.mu.Unlock()
  1319  
  1320  		// Reset the session if required.
  1321  		if err := conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) {
  1322  			conn.Close()
  1323  			return nil, err
  1324  		}
  1325  
  1326  		return conn, nil
  1327  	}
  1328  
  1329  	// Out of free connections or we were asked not to use one. If we're not
  1330  	// allowed to open any more connections, make a request and wait.
  1331  	if db.maxOpen > 0 && db.numOpen >= db.maxOpen {
  1332  		// Make the connRequest channel. It's buffered so that the
  1333  		// connectionOpener doesn't block while waiting for the req to be read.
  1334  		req := make(chan connRequest, 1)
  1335  		reqKey := db.nextRequestKeyLocked()
  1336  		db.connRequests[reqKey] = req
  1337  		db.waitCount++
  1338  		db.mu.Unlock()
  1339  
  1340  		waitStart := nowFunc()
  1341  
  1342  		// Timeout the connection request with the context.
  1343  		select {
  1344  		case <-ctx.Done():
  1345  			// Remove the connection request and ensure no value has been sent
  1346  			// on it after removing.
  1347  			db.mu.Lock()
  1348  			delete(db.connRequests, reqKey)
  1349  			db.mu.Unlock()
  1350  
  1351  			atomic.AddInt64(&db.waitDuration, int64(time.Since(waitStart)))
  1352  
  1353  			select {
  1354  			default:
  1355  			case ret, ok := <-req:
  1356  				if ok && ret.conn != nil {
  1357  					db.putConn(ret.conn, ret.err, false)
  1358  				}
  1359  			}
  1360  			return nil, ctx.Err()
  1361  		case ret, ok := <-req:
  1362  			atomic.AddInt64(&db.waitDuration, int64(time.Since(waitStart)))
  1363  
  1364  			if !ok {
  1365  				return nil, errDBClosed
  1366  			}
  1367  			// Only check if the connection is expired if the strategy is cachedOrNewConns.
  1368  			// If we require a new connection, just re-use the connection without looking
  1369  			// at the expiry time. If it is expired, it will be checked when it is placed
  1370  			// back into the connection pool.
  1371  			// This prioritizes giving a valid connection to a client over the exact connection
  1372  			// lifetime, which could expire exactly after this point anyway.
  1373  			if strategy == cachedOrNewConn && ret.err == nil && ret.conn.expired(lifetime) {
  1374  				db.mu.Lock()
  1375  				db.maxLifetimeClosed++
  1376  				db.mu.Unlock()
  1377  				ret.conn.Close()
  1378  				return nil, driver.ErrBadConn
  1379  			}
  1380  			if ret.conn == nil {
  1381  				return nil, ret.err
  1382  			}
  1383  
  1384  			// Reset the session if required.
  1385  			if err := ret.conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) {
  1386  				ret.conn.Close()
  1387  				return nil, err
  1388  			}
  1389  			return ret.conn, ret.err
  1390  		}
  1391  	}
  1392  
  1393  	db.numOpen++ // optimistically
  1394  	db.mu.Unlock()
  1395  	ci, err := db.connector.Connect(ctx)
  1396  	if err != nil {
  1397  		db.mu.Lock()
  1398  		db.numOpen-- // correct for earlier optimism
  1399  		db.maybeOpenNewConnections()
  1400  		db.mu.Unlock()
  1401  		return nil, err
  1402  	}
  1403  	db.mu.Lock()
  1404  	dc := &driverConn{
  1405  		db:         db,
  1406  		createdAt:  nowFunc(),
  1407  		returnedAt: nowFunc(),
  1408  		ci:         ci,
  1409  		inUse:      true,
  1410  	}
  1411  	db.addDepLocked(dc, dc)
  1412  	db.mu.Unlock()
  1413  	return dc, nil
  1414  }
  1415  
  1416  // putConnHook is a hook for testing.
  1417  var putConnHook func(*DB, *driverConn)
  1418  
  1419  // noteUnusedDriverStatement notes that ds is no longer used and should
  1420  // be closed whenever possible (when c is next not in use), unless c is
  1421  // already closed.
  1422  func (db *DB) noteUnusedDriverStatement(c *driverConn, ds *driverStmt) {
  1423  	db.mu.Lock()
  1424  	defer db.mu.Unlock()
  1425  	if c.inUse {
  1426  		c.onPut = append(c.onPut, func() {
  1427  			ds.Close()
  1428  		})
  1429  	} else {
  1430  		c.Lock()
  1431  		fc := c.finalClosed
  1432  		c.Unlock()
  1433  		if !fc {
  1434  			ds.Close()
  1435  		}
  1436  	}
  1437  }
  1438  
  1439  // debugGetPut determines whether getConn & putConn calls' stack traces
  1440  // are returned for more verbose crashes.
  1441  const debugGetPut = false
  1442  
  1443  // putConn adds a connection to the db's free pool.
  1444  // err is optionally the last error that occurred on this connection.
  1445  func (db *DB) putConn(dc *driverConn, err error, resetSession bool) {
  1446  	if !errors.Is(err, driver.ErrBadConn) {
  1447  		if !dc.validateConnection(resetSession) {
  1448  			err = driver.ErrBadConn
  1449  		}
  1450  	}
  1451  	db.mu.Lock()
  1452  	if !dc.inUse {
  1453  		db.mu.Unlock()
  1454  		if debugGetPut {
  1455  			fmt.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc, stack(), db.lastPut[dc])
  1456  		}
  1457  		panic("sql: connection returned that was never out")
  1458  	}
  1459  
  1460  	if !errors.Is(err, driver.ErrBadConn) && dc.expired(db.maxLifetime) {
  1461  		db.maxLifetimeClosed++
  1462  		err = driver.ErrBadConn
  1463  	}
  1464  	if debugGetPut {
  1465  		db.lastPut[dc] = stack()
  1466  	}
  1467  	dc.inUse = false
  1468  	dc.returnedAt = nowFunc()
  1469  
  1470  	for _, fn := range dc.onPut {
  1471  		fn()
  1472  	}
  1473  	dc.onPut = nil
  1474  
  1475  	if errors.Is(err, driver.ErrBadConn) {
  1476  		// Don't reuse bad connections.
  1477  		// Since the conn is considered bad and is being discarded, treat it
  1478  		// as closed. Don't decrement the open count here, finalClose will
  1479  		// take care of that.
  1480  		db.maybeOpenNewConnections()
  1481  		db.mu.Unlock()
  1482  		dc.Close()
  1483  		return
  1484  	}
  1485  	if putConnHook != nil {
  1486  		putConnHook(db, dc)
  1487  	}
  1488  	added := db.putConnDBLocked(dc, nil)
  1489  	db.mu.Unlock()
  1490  
  1491  	if !added {
  1492  		dc.Close()
  1493  		return
  1494  	}
  1495  }
  1496  
  1497  // Satisfy a connRequest or put the driverConn in the idle pool and return true
  1498  // or return false.
  1499  // putConnDBLocked will satisfy a connRequest if there is one, or it will
  1500  // return the *driverConn to the freeConn list if err == nil and the idle
  1501  // connection limit will not be exceeded.
  1502  // If err != nil, the value of dc is ignored.
  1503  // If err == nil, then dc must not equal nil.
  1504  // If a connRequest was fulfilled or the *driverConn was placed in the
  1505  // freeConn list, then true is returned, otherwise false is returned.
  1506  func (db *DB) putConnDBLocked(dc *driverConn, err error) bool {
  1507  	if db.closed {
  1508  		return false
  1509  	}
  1510  	if db.maxOpen > 0 && db.numOpen > db.maxOpen {
  1511  		return false
  1512  	}
  1513  	if c := len(db.connRequests); c > 0 {
  1514  		var req chan connRequest
  1515  		var reqKey uint64
  1516  		for reqKey, req = range db.connRequests {
  1517  			break
  1518  		}
  1519  		delete(db.connRequests, reqKey) // Remove from pending requests.
  1520  		if err == nil {
  1521  			dc.inUse = true
  1522  		}
  1523  		req <- connRequest{
  1524  			conn: dc,
  1525  			err:  err,
  1526  		}
  1527  		return true
  1528  	} else if err == nil && !db.closed {
  1529  		if db.maxIdleConnsLocked() > len(db.freeConn) {
  1530  			db.freeConn = append(db.freeConn, dc)
  1531  			db.startCleanerLocked()
  1532  			return true
  1533  		}
  1534  		db.maxIdleClosed++
  1535  	}
  1536  	return false
  1537  }
  1538  
  1539  // maxBadConnRetries is the number of maximum retries if the driver returns
  1540  // driver.ErrBadConn to signal a broken connection before forcing a new
  1541  // connection to be opened.
  1542  const maxBadConnRetries = 2
  1543  
  1544  // PrepareContext creates a prepared statement for later queries or executions.
  1545  // Multiple queries or executions may be run concurrently from the
  1546  // returned statement.
  1547  // The caller must call the statement's Close method
  1548  // when the statement is no longer needed.
  1549  //
  1550  // The provided context is used for the preparation of the statement, not for the
  1551  // execution of the statement.
  1552  func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
  1553  	var stmt *Stmt
  1554  	var err error
  1555  	var isBadConn bool
  1556  	for i := 0; i < maxBadConnRetries; i++ {
  1557  		stmt, err = db.prepare(ctx, query, cachedOrNewConn)
  1558  		isBadConn = errors.Is(err, driver.ErrBadConn)
  1559  		if !isBadConn {
  1560  			break
  1561  		}
  1562  	}
  1563  	if isBadConn {
  1564  		return db.prepare(ctx, query, alwaysNewConn)
  1565  	}
  1566  	return stmt, err
  1567  }
  1568  
  1569  // Prepare creates a prepared statement for later queries or executions.
  1570  // Multiple queries or executions may be run concurrently from the
  1571  // returned statement.
  1572  // The caller must call the statement's Close method
  1573  // when the statement is no longer needed.
  1574  //
  1575  // Prepare uses context.Background internally; to specify the context, use
  1576  // PrepareContext.
  1577  func (db *DB) Prepare(query string) (*Stmt, error) {
  1578  	return db.PrepareContext(context.Background(), query)
  1579  }
  1580  
  1581  func (db *DB) prepare(ctx context.Context, query string, strategy connReuseStrategy) (*Stmt, error) {
  1582  	// TODO: check if db.driver supports an optional
  1583  	// driver.Preparer interface and call that instead, if so,
  1584  	// otherwise we make a prepared statement that's bound
  1585  	// to a connection, and to execute this prepared statement
  1586  	// we either need to use this connection (if it's free), else
  1587  	// get a new connection + re-prepare + execute on that one.
  1588  	dc, err := db.conn(ctx, strategy)
  1589  	if err != nil {
  1590  		return nil, err
  1591  	}
  1592  	return db.prepareDC(ctx, dc, dc.releaseConn, nil, query)
  1593  }
  1594  
  1595  // prepareDC prepares a query on the driverConn and calls release before
  1596  // returning. When cg == nil it implies that a connection pool is used, and
  1597  // when cg != nil only a single driver connection is used.
  1598  func (db *DB) prepareDC(ctx context.Context, dc *driverConn, release func(error), cg stmtConnGrabber, query string) (*Stmt, error) {
  1599  	var ds *driverStmt
  1600  	var err error
  1601  	defer func() {
  1602  		release(err)
  1603  	}()
  1604  	withLock(dc, func() {
  1605  		ds, err = dc.prepareLocked(ctx, cg, query)
  1606  	})
  1607  	if err != nil {
  1608  		return nil, err
  1609  	}
  1610  	stmt := &Stmt{
  1611  		db:    db,
  1612  		query: query,
  1613  		cg:    cg,
  1614  		cgds:  ds,
  1615  	}
  1616  
  1617  	// When cg == nil this statement will need to keep track of various
  1618  	// connections they are prepared on and record the stmt dependency on
  1619  	// the DB.
  1620  	if cg == nil {
  1621  		stmt.css = []connStmt{{dc, ds}}
  1622  		stmt.lastNumClosed = atomic.LoadUint64(&db.numClosed)
  1623  		db.addDep(stmt, stmt)
  1624  	}
  1625  	return stmt, nil
  1626  }
  1627  
  1628  // ExecContext executes a query without returning any rows.
  1629  // The args are for any placeholder parameters in the query.
  1630  func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error) {
  1631  	var res Result
  1632  	var err error
  1633  	var isBadConn bool
  1634  	for i := 0; i < maxBadConnRetries; i++ {
  1635  		res, err = db.exec(ctx, query, args, cachedOrNewConn)
  1636  		isBadConn = errors.Is(err, driver.ErrBadConn)
  1637  		if !isBadConn {
  1638  			break
  1639  		}
  1640  	}
  1641  	if isBadConn {
  1642  		return db.exec(ctx, query, args, alwaysNewConn)
  1643  	}
  1644  	return res, err
  1645  }
  1646  
  1647  // Exec executes a query without returning any rows.
  1648  // The args are for any placeholder parameters in the query.
  1649  //
  1650  // Exec uses context.Background internally; to specify the context, use
  1651  // ExecContext.
  1652  func (db *DB) Exec(query string, args ...any) (Result, error) {
  1653  	return db.ExecContext(context.Background(), query, args...)
  1654  }
  1655  
  1656  func (db *DB) exec(ctx context.Context, query string, args []any, strategy connReuseStrategy) (Result, error) {
  1657  	dc, err := db.conn(ctx, strategy)
  1658  	if err != nil {
  1659  		return nil, err
  1660  	}
  1661  	return db.execDC(ctx, dc, dc.releaseConn, query, args)
  1662  }
  1663  
  1664  func (db *DB) execDC(ctx context.Context, dc *driverConn, release func(error), query string, args []any) (res Result, err error) {
  1665  	defer func() {
  1666  		release(err)
  1667  	}()
  1668  	execerCtx, ok := dc.ci.(driver.ExecerContext)
  1669  	var execer driver.Execer
  1670  	if !ok {
  1671  		execer, ok = dc.ci.(driver.Execer)
  1672  	}
  1673  	if ok {
  1674  		var nvdargs []driver.NamedValue
  1675  		var resi driver.Result
  1676  		withLock(dc, func() {
  1677  			nvdargs, err = driverArgsConnLocked(dc.ci, nil, args)
  1678  			if err != nil {
  1679  				return
  1680  			}
  1681  			resi, err = ctxDriverExec(ctx, execerCtx, execer, query, nvdargs)
  1682  		})
  1683  		if err != driver.ErrSkip {
  1684  			if err != nil {
  1685  				return nil, err
  1686  			}
  1687  			return driverResult{dc, resi}, nil
  1688  		}
  1689  	}
  1690  
  1691  	var si driver.Stmt
  1692  	withLock(dc, func() {
  1693  		si, err = ctxDriverPrepare(ctx, dc.ci, query)
  1694  	})
  1695  	if err != nil {
  1696  		return nil, err
  1697  	}
  1698  	ds := &driverStmt{Locker: dc, si: si}
  1699  	defer ds.Close()
  1700  	return resultFromStatement(ctx, dc.ci, ds, args...)
  1701  }
  1702  
  1703  // QueryContext executes a query that returns rows, typically a SELECT.
  1704  // The args are for any placeholder parameters in the query.
  1705  func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
  1706  	var rows *Rows
  1707  	var err error
  1708  	var isBadConn bool
  1709  	for i := 0; i < maxBadConnRetries; i++ {
  1710  		rows, err = db.query(ctx, query, args, cachedOrNewConn)
  1711  		isBadConn = errors.Is(err, driver.ErrBadConn)
  1712  		if !isBadConn {
  1713  			break
  1714  		}
  1715  	}
  1716  	if isBadConn {
  1717  		return db.query(ctx, query, args, alwaysNewConn)
  1718  	}
  1719  	return rows, err
  1720  }
  1721  
  1722  // Query executes a query that returns rows, typically a SELECT.
  1723  // The args are for any placeholder parameters in the query.
  1724  //
  1725  // Query uses context.Background internally; to specify the context, use
  1726  // QueryContext.
  1727  func (db *DB) Query(query string, args ...any) (*Rows, error) {
  1728  	return db.QueryContext(context.Background(), query, args...)
  1729  }
  1730  
  1731  func (db *DB) query(ctx context.Context, query string, args []any, strategy connReuseStrategy) (*Rows, error) {
  1732  	dc, err := db.conn(ctx, strategy)
  1733  	if err != nil {
  1734  		return nil, err
  1735  	}
  1736  
  1737  	return db.queryDC(ctx, nil, dc, dc.releaseConn, query, args)
  1738  }
  1739  
  1740  // queryDC executes a query on the given connection.
  1741  // The connection gets released by the releaseConn function.
  1742  // The ctx context is from a query method and the txctx context is from an
  1743  // optional transaction context.
  1744  func (db *DB) queryDC(ctx, txctx context.Context, dc *driverConn, releaseConn func(error), query string, args []any) (*Rows, error) {
  1745  	queryerCtx, ok := dc.ci.(driver.QueryerContext)
  1746  	var queryer driver.Queryer
  1747  	if !ok {
  1748  		queryer, ok = dc.ci.(driver.Queryer)
  1749  	}
  1750  	if ok {
  1751  		var nvdargs []driver.NamedValue
  1752  		var rowsi driver.Rows
  1753  		var err error
  1754  		withLock(dc, func() {
  1755  			nvdargs, err = driverArgsConnLocked(dc.ci, nil, args)
  1756  			if err != nil {
  1757  				return
  1758  			}
  1759  			rowsi, err = ctxDriverQuery(ctx, queryerCtx, queryer, query, nvdargs)
  1760  		})
  1761  		if err != driver.ErrSkip {
  1762  			if err != nil {
  1763  				releaseConn(err)
  1764  				return nil, err
  1765  			}
  1766  			// Note: ownership of dc passes to the *Rows, to be freed
  1767  			// with releaseConn.
  1768  			rows := &Rows{
  1769  				dc:          dc,
  1770  				releaseConn: releaseConn,
  1771  				rowsi:       rowsi,
  1772  			}
  1773  			rows.initContextClose(ctx, txctx)
  1774  			return rows, nil
  1775  		}
  1776  	}
  1777  
  1778  	var si driver.Stmt
  1779  	var err error
  1780  	withLock(dc, func() {
  1781  		si, err = ctxDriverPrepare(ctx, dc.ci, query)
  1782  	})
  1783  	if err != nil {
  1784  		releaseConn(err)
  1785  		return nil, err
  1786  	}
  1787  
  1788  	ds := &driverStmt{Locker: dc, si: si}
  1789  	rowsi, err := rowsiFromStatement(ctx, dc.ci, ds, args...)
  1790  	if err != nil {
  1791  		ds.Close()
  1792  		releaseConn(err)
  1793  		return nil, err
  1794  	}
  1795  
  1796  	// Note: ownership of ci passes to the *Rows, to be freed
  1797  	// with releaseConn.
  1798  	rows := &Rows{
  1799  		dc:          dc,
  1800  		releaseConn: releaseConn,
  1801  		rowsi:       rowsi,
  1802  		closeStmt:   ds,
  1803  	}
  1804  	rows.initContextClose(ctx, txctx)
  1805  	return rows, nil
  1806  }
  1807  
  1808  // QueryRowContext executes a query that is expected to return at most one row.
  1809  // QueryRowContext always returns a non-nil value. Errors are deferred until
  1810  // Row's Scan method is called.
  1811  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  1812  // Otherwise, the *Row's Scan scans the first selected row and discards
  1813  // the rest.
  1814  func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
  1815  	rows, err := db.QueryContext(ctx, query, args...)
  1816  	return &Row{rows: rows, err: err}
  1817  }
  1818  
  1819  // QueryRow executes a query that is expected to return at most one row.
  1820  // QueryRow always returns a non-nil value. Errors are deferred until
  1821  // Row's Scan method is called.
  1822  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  1823  // Otherwise, the *Row's Scan scans the first selected row and discards
  1824  // the rest.
  1825  //
  1826  // QueryRow uses context.Background internally; to specify the context, use
  1827  // QueryRowContext.
  1828  func (db *DB) QueryRow(query string, args ...any) *Row {
  1829  	return db.QueryRowContext(context.Background(), query, args...)
  1830  }
  1831  
  1832  // BeginTx starts a transaction.
  1833  //
  1834  // The provided context is used until the transaction is committed or rolled back.
  1835  // If the context is canceled, the sql package will roll back
  1836  // the transaction. Tx.Commit will return an error if the context provided to
  1837  // BeginTx is canceled.
  1838  //
  1839  // The provided TxOptions is optional and may be nil if defaults should be used.
  1840  // If a non-default isolation level is used that the driver doesn't support,
  1841  // an error will be returned.
  1842  func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
  1843  	var tx *Tx
  1844  	var err error
  1845  	var isBadConn bool
  1846  	for i := 0; i < maxBadConnRetries; i++ {
  1847  		tx, err = db.begin(ctx, opts, cachedOrNewConn)
  1848  		isBadConn = errors.Is(err, driver.ErrBadConn)
  1849  		if !isBadConn {
  1850  			break
  1851  		}
  1852  	}
  1853  	if isBadConn {
  1854  		return db.begin(ctx, opts, alwaysNewConn)
  1855  	}
  1856  	return tx, err
  1857  }
  1858  
  1859  // Begin starts a transaction. The default isolation level is dependent on
  1860  // the driver.
  1861  //
  1862  // Begin uses context.Background internally; to specify the context, use
  1863  // BeginTx.
  1864  func (db *DB) Begin() (*Tx, error) {
  1865  	return db.BeginTx(context.Background(), nil)
  1866  }
  1867  
  1868  func (db *DB) begin(ctx context.Context, opts *TxOptions, strategy connReuseStrategy) (tx *Tx, err error) {
  1869  	dc, err := db.conn(ctx, strategy)
  1870  	if err != nil {
  1871  		return nil, err
  1872  	}
  1873  	return db.beginDC(ctx, dc, dc.releaseConn, opts)
  1874  }
  1875  
  1876  // beginDC starts a transaction. The provided dc must be valid and ready to use.
  1877  func (db *DB) beginDC(ctx context.Context, dc *driverConn, release func(error), opts *TxOptions) (tx *Tx, err error) {
  1878  	var txi driver.Tx
  1879  	keepConnOnRollback := false
  1880  	withLock(dc, func() {
  1881  		_, hasSessionResetter := dc.ci.(driver.SessionResetter)
  1882  		_, hasConnectionValidator := dc.ci.(driver.Validator)
  1883  		keepConnOnRollback = hasSessionResetter && hasConnectionValidator
  1884  		txi, err = ctxDriverBegin(ctx, opts, dc.ci)
  1885  	})
  1886  	if err != nil {
  1887  		release(err)
  1888  		return nil, err
  1889  	}
  1890  
  1891  	// Schedule the transaction to rollback when the context is canceled.
  1892  	// The cancel function in Tx will be called after done is set to true.
  1893  	ctx, cancel := context.WithCancel(ctx)
  1894  	tx = &Tx{
  1895  		db:                 db,
  1896  		dc:                 dc,
  1897  		releaseConn:        release,
  1898  		txi:                txi,
  1899  		cancel:             cancel,
  1900  		keepConnOnRollback: keepConnOnRollback,
  1901  		ctx:                ctx,
  1902  	}
  1903  	go tx.awaitDone()
  1904  	return tx, nil
  1905  }
  1906  
  1907  // Driver returns the database's underlying driver.
  1908  func (db *DB) Driver() driver.Driver {
  1909  	return db.connector.Driver()
  1910  }
  1911  
  1912  // ErrConnDone is returned by any operation that is performed on a connection
  1913  // that has already been returned to the connection pool.
  1914  var ErrConnDone = errors.New("sql: connection is already closed")
  1915  
  1916  // Conn returns a single connection by either opening a new connection
  1917  // or returning an existing connection from the connection pool. Conn will
  1918  // block until either a connection is returned or ctx is canceled.
  1919  // Queries run on the same Conn will be run in the same database session.
  1920  //
  1921  // Every Conn must be returned to the database pool after use by
  1922  // calling Conn.Close.
  1923  func (db *DB) Conn(ctx context.Context) (*Conn, error) {
  1924  	var dc *driverConn
  1925  	var err error
  1926  	var isBadConn bool
  1927  	for i := 0; i < maxBadConnRetries; i++ {
  1928  		dc, err = db.conn(ctx, cachedOrNewConn)
  1929  		isBadConn = errors.Is(err, driver.ErrBadConn)
  1930  		if !isBadConn {
  1931  			break
  1932  		}
  1933  	}
  1934  	if isBadConn {
  1935  		dc, err = db.conn(ctx, alwaysNewConn)
  1936  	}
  1937  	if err != nil {
  1938  		return nil, err
  1939  	}
  1940  
  1941  	conn := &Conn{
  1942  		db: db,
  1943  		dc: dc,
  1944  	}
  1945  	return conn, nil
  1946  }
  1947  
  1948  type releaseConn func(error)
  1949  
  1950  // Conn represents a single database connection rather than a pool of database
  1951  // connections. Prefer running queries from DB unless there is a specific
  1952  // need for a continuous single database connection.
  1953  //
  1954  // A Conn must call Close to return the connection to the database pool
  1955  // and may do so concurrently with a running query.
  1956  //
  1957  // After a call to Close, all operations on the
  1958  // connection fail with ErrConnDone.
  1959  type Conn struct {
  1960  	db *DB
  1961  
  1962  	// closemu prevents the connection from closing while there
  1963  	// is an active query. It is held for read during queries
  1964  	// and exclusively during close.
  1965  	closemu sync.RWMutex
  1966  
  1967  	// dc is owned until close, at which point
  1968  	// it's returned to the connection pool.
  1969  	dc *driverConn
  1970  
  1971  	// done transitions from 0 to 1 exactly once, on close.
  1972  	// Once done, all operations fail with ErrConnDone.
  1973  	// Use atomic operations on value when checking value.
  1974  	done int32
  1975  }
  1976  
  1977  // grabConn takes a context to implement stmtConnGrabber
  1978  // but the context is not used.
  1979  func (c *Conn) grabConn(context.Context) (*driverConn, releaseConn, error) {
  1980  	if atomic.LoadInt32(&c.done) != 0 {
  1981  		return nil, nil, ErrConnDone
  1982  	}
  1983  	c.closemu.RLock()
  1984  	return c.dc, c.closemuRUnlockCondReleaseConn, nil
  1985  }
  1986  
  1987  // PingContext verifies the connection to the database is still alive.
  1988  func (c *Conn) PingContext(ctx context.Context) error {
  1989  	dc, release, err := c.grabConn(ctx)
  1990  	if err != nil {
  1991  		return err
  1992  	}
  1993  	return c.db.pingDC(ctx, dc, release)
  1994  }
  1995  
  1996  // ExecContext executes a query without returning any rows.
  1997  // The args are for any placeholder parameters in the query.
  1998  func (c *Conn) ExecContext(ctx context.Context, query string, args ...any) (Result, error) {
  1999  	dc, release, err := c.grabConn(ctx)
  2000  	if err != nil {
  2001  		return nil, err
  2002  	}
  2003  	return c.db.execDC(ctx, dc, release, query, args)
  2004  }
  2005  
  2006  // QueryContext executes a query that returns rows, typically a SELECT.
  2007  // The args are for any placeholder parameters in the query.
  2008  func (c *Conn) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
  2009  	dc, release, err := c.grabConn(ctx)
  2010  	if err != nil {
  2011  		return nil, err
  2012  	}
  2013  	return c.db.queryDC(ctx, nil, dc, release, query, args)
  2014  }
  2015  
  2016  // QueryRowContext executes a query that is expected to return at most one row.
  2017  // QueryRowContext always returns a non-nil value. Errors are deferred until
  2018  // Row's Scan method is called.
  2019  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  2020  // Otherwise, the *Row's Scan scans the first selected row and discards
  2021  // the rest.
  2022  func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
  2023  	rows, err := c.QueryContext(ctx, query, args...)
  2024  	return &Row{rows: rows, err: err}
  2025  }
  2026  
  2027  // PrepareContext creates a prepared statement for later queries or executions.
  2028  // Multiple queries or executions may be run concurrently from the
  2029  // returned statement.
  2030  // The caller must call the statement's Close method
  2031  // when the statement is no longer needed.
  2032  //
  2033  // The provided context is used for the preparation of the statement, not for the
  2034  // execution of the statement.
  2035  func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
  2036  	dc, release, err := c.grabConn(ctx)
  2037  	if err != nil {
  2038  		return nil, err
  2039  	}
  2040  	return c.db.prepareDC(ctx, dc, release, c, query)
  2041  }
  2042  
  2043  // Raw executes f exposing the underlying driver connection for the
  2044  // duration of f. The driverConn must not be used outside of f.
  2045  //
  2046  // Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable
  2047  // until Conn.Close is called.
  2048  func (c *Conn) Raw(f func(driverConn any) error) (err error) {
  2049  	var dc *driverConn
  2050  	var release releaseConn
  2051  
  2052  	// grabConn takes a context to implement stmtConnGrabber, but the context is not used.
  2053  	dc, release, err = c.grabConn(nil)
  2054  	if err != nil {
  2055  		return
  2056  	}
  2057  	fPanic := true
  2058  	dc.Mutex.Lock()
  2059  	defer func() {
  2060  		dc.Mutex.Unlock()
  2061  
  2062  		// If f panics fPanic will remain true.
  2063  		// Ensure an error is passed to release so the connection
  2064  		// may be discarded.
  2065  		if fPanic {
  2066  			err = driver.ErrBadConn
  2067  		}
  2068  		release(err)
  2069  	}()
  2070  	err = f(dc.ci)
  2071  	fPanic = false
  2072  
  2073  	return
  2074  }
  2075  
  2076  // BeginTx starts a transaction.
  2077  //
  2078  // The provided context is used until the transaction is committed or rolled back.
  2079  // If the context is canceled, the sql package will roll back
  2080  // the transaction. Tx.Commit will return an error if the context provided to
  2081  // BeginTx is canceled.
  2082  //
  2083  // The provided TxOptions is optional and may be nil if defaults should be used.
  2084  // If a non-default isolation level is used that the driver doesn't support,
  2085  // an error will be returned.
  2086  func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
  2087  	dc, release, err := c.grabConn(ctx)
  2088  	if err != nil {
  2089  		return nil, err
  2090  	}
  2091  	return c.db.beginDC(ctx, dc, release, opts)
  2092  }
  2093  
  2094  // closemuRUnlockCondReleaseConn read unlocks closemu
  2095  // as the sql operation is done with the dc.
  2096  func (c *Conn) closemuRUnlockCondReleaseConn(err error) {
  2097  	c.closemu.RUnlock()
  2098  	if errors.Is(err, driver.ErrBadConn) {
  2099  		c.close(err)
  2100  	}
  2101  }
  2102  
  2103  func (c *Conn) txCtx() context.Context {
  2104  	return nil
  2105  }
  2106  
  2107  func (c *Conn) close(err error) error {
  2108  	if !atomic.CompareAndSwapInt32(&c.done, 0, 1) {
  2109  		return ErrConnDone
  2110  	}
  2111  
  2112  	// Lock around releasing the driver connection
  2113  	// to ensure all queries have been stopped before doing so.
  2114  	c.closemu.Lock()
  2115  	defer c.closemu.Unlock()
  2116  
  2117  	c.dc.releaseConn(err)
  2118  	c.dc = nil
  2119  	c.db = nil
  2120  	return err
  2121  }
  2122  
  2123  // Close returns the connection to the connection pool.
  2124  // All operations after a Close will return with ErrConnDone.
  2125  // Close is safe to call concurrently with other operations and will
  2126  // block until all other operations finish. It may be useful to first
  2127  // cancel any used context and then call close directly after.
  2128  func (c *Conn) Close() error {
  2129  	return c.close(nil)
  2130  }
  2131  
  2132  // Tx is an in-progress database transaction.
  2133  //
  2134  // A transaction must end with a call to Commit or Rollback.
  2135  //
  2136  // After a call to Commit or Rollback, all operations on the
  2137  // transaction fail with ErrTxDone.
  2138  //
  2139  // The statements prepared for a transaction by calling
  2140  // the transaction's Prepare or Stmt methods are closed
  2141  // by the call to Commit or Rollback.
  2142  type Tx struct {
  2143  	db *DB
  2144  
  2145  	// closemu prevents the transaction from closing while there
  2146  	// is an active query. It is held for read during queries
  2147  	// and exclusively during close.
  2148  	closemu sync.RWMutex
  2149  
  2150  	// dc is owned exclusively until Commit or Rollback, at which point
  2151  	// it's returned with putConn.
  2152  	dc  *driverConn
  2153  	txi driver.Tx
  2154  
  2155  	// releaseConn is called once the Tx is closed to release
  2156  	// any held driverConn back to the pool.
  2157  	releaseConn func(error)
  2158  
  2159  	// done transitions from 0 to 1 exactly once, on Commit
  2160  	// or Rollback. once done, all operations fail with
  2161  	// ErrTxDone.
  2162  	// Use atomic operations on value when checking value.
  2163  	done int32
  2164  
  2165  	// keepConnOnRollback is true if the driver knows
  2166  	// how to reset the connection's session and if need be discard
  2167  	// the connection.
  2168  	keepConnOnRollback bool
  2169  
  2170  	// All Stmts prepared for this transaction. These will be closed after the
  2171  	// transaction has been committed or rolled back.
  2172  	stmts struct {
  2173  		sync.Mutex
  2174  		v []*Stmt
  2175  	}
  2176  
  2177  	// cancel is called after done transitions from 0 to 1.
  2178  	cancel func()
  2179  
  2180  	// ctx lives for the life of the transaction.
  2181  	ctx context.Context
  2182  }
  2183  
  2184  // awaitDone blocks until the context in Tx is canceled and rolls back
  2185  // the transaction if it's not already done.
  2186  func (tx *Tx) awaitDone() {
  2187  	// Wait for either the transaction to be committed or rolled
  2188  	// back, or for the associated context to be closed.
  2189  	<-tx.ctx.Done()
  2190  
  2191  	// Discard and close the connection used to ensure the
  2192  	// transaction is closed and the resources are released.  This
  2193  	// rollback does nothing if the transaction has already been
  2194  	// committed or rolled back.
  2195  	// Do not discard the connection if the connection knows
  2196  	// how to reset the session.
  2197  	discardConnection := !tx.keepConnOnRollback
  2198  	tx.rollback(discardConnection)
  2199  }
  2200  
  2201  func (tx *Tx) isDone() bool {
  2202  	return atomic.LoadInt32(&tx.done) != 0
  2203  }
  2204  
  2205  // ErrTxDone is returned by any operation that is performed on a transaction
  2206  // that has already been committed or rolled back.
  2207  var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back")
  2208  
  2209  // close returns the connection to the pool and
  2210  // must only be called by Tx.rollback or Tx.Commit while
  2211  // tx is already canceled and won't be executed concurrently.
  2212  func (tx *Tx) close(err error) {
  2213  	tx.releaseConn(err)
  2214  	tx.dc = nil
  2215  	tx.txi = nil
  2216  }
  2217  
  2218  // hookTxGrabConn specifies an optional hook to be called on
  2219  // a successful call to (*Tx).grabConn. For tests.
  2220  var hookTxGrabConn func()
  2221  
  2222  func (tx *Tx) grabConn(ctx context.Context) (*driverConn, releaseConn, error) {
  2223  	select {
  2224  	default:
  2225  	case <-ctx.Done():
  2226  		return nil, nil, ctx.Err()
  2227  	}
  2228  
  2229  	// closemu.RLock must come before the check for isDone to prevent the Tx from
  2230  	// closing while a query is executing.
  2231  	tx.closemu.RLock()
  2232  	if tx.isDone() {
  2233  		tx.closemu.RUnlock()
  2234  		return nil, nil, ErrTxDone
  2235  	}
  2236  	if hookTxGrabConn != nil { // test hook
  2237  		hookTxGrabConn()
  2238  	}
  2239  	return tx.dc, tx.closemuRUnlockRelease, nil
  2240  }
  2241  
  2242  func (tx *Tx) txCtx() context.Context {
  2243  	return tx.ctx
  2244  }
  2245  
  2246  // closemuRUnlockRelease is used as a func(error) method value in
  2247  // ExecContext and QueryContext. Unlocking in the releaseConn keeps
  2248  // the driver conn from being returned to the connection pool until
  2249  // the Rows has been closed.
  2250  func (tx *Tx) closemuRUnlockRelease(error) {
  2251  	tx.closemu.RUnlock()
  2252  }
  2253  
  2254  // Closes all Stmts prepared for this transaction.
  2255  func (tx *Tx) closePrepared() {
  2256  	tx.stmts.Lock()
  2257  	defer tx.stmts.Unlock()
  2258  	for _, stmt := range tx.stmts.v {
  2259  		stmt.Close()
  2260  	}
  2261  }
  2262  
  2263  // Commit commits the transaction.
  2264  func (tx *Tx) Commit() error {
  2265  	// Check context first to avoid transaction leak.
  2266  	// If put it behind tx.done CompareAndSwap statement, we can't ensure
  2267  	// the consistency between tx.done and the real COMMIT operation.
  2268  	select {
  2269  	default:
  2270  	case <-tx.ctx.Done():
  2271  		if atomic.LoadInt32(&tx.done) == 1 {
  2272  			return ErrTxDone
  2273  		}
  2274  		return tx.ctx.Err()
  2275  	}
  2276  	if !atomic.CompareAndSwapInt32(&tx.done, 0, 1) {
  2277  		return ErrTxDone
  2278  	}
  2279  
  2280  	// Cancel the Tx to release any active R-closemu locks.
  2281  	// This is safe to do because tx.done has already transitioned
  2282  	// from 0 to 1. Hold the W-closemu lock prior to rollback
  2283  	// to ensure no other connection has an active query.
  2284  	tx.cancel()
  2285  	tx.closemu.Lock()
  2286  	tx.closemu.Unlock()
  2287  
  2288  	var err error
  2289  	withLock(tx.dc, func() {
  2290  		err = tx.txi.Commit()
  2291  	})
  2292  	if !errors.Is(err, driver.ErrBadConn) {
  2293  		tx.closePrepared()
  2294  	}
  2295  	tx.close(err)
  2296  	return err
  2297  }
  2298  
  2299  var rollbackHook func()
  2300  
  2301  // rollback aborts the transaction and optionally forces the pool to discard
  2302  // the connection.
  2303  func (tx *Tx) rollback(discardConn bool) error {
  2304  	if !atomic.CompareAndSwapInt32(&tx.done, 0, 1) {
  2305  		return ErrTxDone
  2306  	}
  2307  
  2308  	if rollbackHook != nil {
  2309  		rollbackHook()
  2310  	}
  2311  
  2312  	// Cancel the Tx to release any active R-closemu locks.
  2313  	// This is safe to do because tx.done has already transitioned
  2314  	// from 0 to 1. Hold the W-closemu lock prior to rollback
  2315  	// to ensure no other connection has an active query.
  2316  	tx.cancel()
  2317  	tx.closemu.Lock()
  2318  	tx.closemu.Unlock()
  2319  
  2320  	var err error
  2321  	withLock(tx.dc, func() {
  2322  		err = tx.txi.Rollback()
  2323  	})
  2324  	if !errors.Is(err, driver.ErrBadConn) {
  2325  		tx.closePrepared()
  2326  	}
  2327  	if discardConn {
  2328  		err = driver.ErrBadConn
  2329  	}
  2330  	tx.close(err)
  2331  	return err
  2332  }
  2333  
  2334  // Rollback aborts the transaction.
  2335  func (tx *Tx) Rollback() error {
  2336  	return tx.rollback(false)
  2337  }
  2338  
  2339  // PrepareContext creates a prepared statement for use within a transaction.
  2340  //
  2341  // The returned statement operates within the transaction and will be closed
  2342  // when the transaction has been committed or rolled back.
  2343  //
  2344  // To use an existing prepared statement on this transaction, see Tx.Stmt.
  2345  //
  2346  // The provided context will be used for the preparation of the context, not
  2347  // for the execution of the returned statement. The returned statement
  2348  // will run in the transaction context.
  2349  func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
  2350  	dc, release, err := tx.grabConn(ctx)
  2351  	if err != nil {
  2352  		return nil, err
  2353  	}
  2354  
  2355  	stmt, err := tx.db.prepareDC(ctx, dc, release, tx, query)
  2356  	if err != nil {
  2357  		return nil, err
  2358  	}
  2359  	tx.stmts.Lock()
  2360  	tx.stmts.v = append(tx.stmts.v, stmt)
  2361  	tx.stmts.Unlock()
  2362  	return stmt, nil
  2363  }
  2364  
  2365  // Prepare creates a prepared statement for use within a transaction.
  2366  //
  2367  // The returned statement operates within the transaction and will be closed
  2368  // when the transaction has been committed or rolled back.
  2369  //
  2370  // To use an existing prepared statement on this transaction, see Tx.Stmt.
  2371  //
  2372  // Prepare uses context.Background internally; to specify the context, use
  2373  // PrepareContext.
  2374  func (tx *Tx) Prepare(query string) (*Stmt, error) {
  2375  	return tx.PrepareContext(context.Background(), query)
  2376  }
  2377  
  2378  // StmtContext returns a transaction-specific prepared statement from
  2379  // an existing statement.
  2380  //
  2381  // Example:
  2382  //  updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
  2383  //  ...
  2384  //  tx, err := db.Begin()
  2385  //  ...
  2386  //  res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)
  2387  //
  2388  // The provided context is used for the preparation of the statement, not for the
  2389  // execution of the statement.
  2390  //
  2391  // The returned statement operates within the transaction and will be closed
  2392  // when the transaction has been committed or rolled back.
  2393  func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt {
  2394  	dc, release, err := tx.grabConn(ctx)
  2395  	if err != nil {
  2396  		return &Stmt{stickyErr: err}
  2397  	}
  2398  	defer release(nil)
  2399  
  2400  	if tx.db != stmt.db {
  2401  		return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")}
  2402  	}
  2403  	var si driver.Stmt
  2404  	var parentStmt *Stmt
  2405  	stmt.mu.Lock()
  2406  	if stmt.closed || stmt.cg != nil {
  2407  		// If the statement has been closed or already belongs to a
  2408  		// transaction, we can't reuse it in this connection.
  2409  		// Since tx.StmtContext should never need to be called with a
  2410  		// Stmt already belonging to tx, we ignore this edge case and
  2411  		// re-prepare the statement in this case. No need to add
  2412  		// code-complexity for this.
  2413  		stmt.mu.Unlock()
  2414  		withLock(dc, func() {
  2415  			si, err = ctxDriverPrepare(ctx, dc.ci, stmt.query)
  2416  		})
  2417  		if err != nil {
  2418  			return &Stmt{stickyErr: err}
  2419  		}
  2420  	} else {
  2421  		stmt.removeClosedStmtLocked()
  2422  		// See if the statement has already been prepared on this connection,
  2423  		// and reuse it if possible.
  2424  		for _, v := range stmt.css {
  2425  			if v.dc == dc {
  2426  				si = v.ds.si
  2427  				break
  2428  			}
  2429  		}
  2430  
  2431  		stmt.mu.Unlock()
  2432  
  2433  		if si == nil {
  2434  			var ds *driverStmt
  2435  			withLock(dc, func() {
  2436  				ds, err = stmt.prepareOnConnLocked(ctx, dc)
  2437  			})
  2438  			if err != nil {
  2439  				return &Stmt{stickyErr: err}
  2440  			}
  2441  			si = ds.si
  2442  		}
  2443  		parentStmt = stmt
  2444  	}
  2445  
  2446  	txs := &Stmt{
  2447  		db: tx.db,
  2448  		cg: tx,
  2449  		cgds: &driverStmt{
  2450  			Locker: dc,
  2451  			si:     si,
  2452  		},
  2453  		parentStmt: parentStmt,
  2454  		query:      stmt.query,
  2455  	}
  2456  	if parentStmt != nil {
  2457  		tx.db.addDep(parentStmt, txs)
  2458  	}
  2459  	tx.stmts.Lock()
  2460  	tx.stmts.v = append(tx.stmts.v, txs)
  2461  	tx.stmts.Unlock()
  2462  	return txs
  2463  }
  2464  
  2465  // Stmt returns a transaction-specific prepared statement from
  2466  // an existing statement.
  2467  //
  2468  // Example:
  2469  //  updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
  2470  //  ...
  2471  //  tx, err := db.Begin()
  2472  //  ...
  2473  //  res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
  2474  //
  2475  // The returned statement operates within the transaction and will be closed
  2476  // when the transaction has been committed or rolled back.
  2477  //
  2478  // Stmt uses context.Background internally; to specify the context, use
  2479  // StmtContext.
  2480  func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
  2481  	return tx.StmtContext(context.Background(), stmt)
  2482  }
  2483  
  2484  // ExecContext executes a query that doesn't return rows.
  2485  // For example: an INSERT and UPDATE.
  2486  func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (Result, error) {
  2487  	dc, release, err := tx.grabConn(ctx)
  2488  	if err != nil {
  2489  		return nil, err
  2490  	}
  2491  	return tx.db.execDC(ctx, dc, release, query, args)
  2492  }
  2493  
  2494  // Exec executes a query that doesn't return rows.
  2495  // For example: an INSERT and UPDATE.
  2496  //
  2497  // Exec uses context.Background internally; to specify the context, use
  2498  // ExecContext.
  2499  func (tx *Tx) Exec(query string, args ...any) (Result, error) {
  2500  	return tx.ExecContext(context.Background(), query, args...)
  2501  }
  2502  
  2503  // QueryContext executes a query that returns rows, typically a SELECT.
  2504  func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
  2505  	dc, release, err := tx.grabConn(ctx)
  2506  	if err != nil {
  2507  		return nil, err
  2508  	}
  2509  
  2510  	return tx.db.queryDC(ctx, tx.ctx, dc, release, query, args)
  2511  }
  2512  
  2513  // Query executes a query that returns rows, typically a SELECT.
  2514  //
  2515  // Query uses context.Background internally; to specify the context, use
  2516  // QueryContext.
  2517  func (tx *Tx) Query(query string, args ...any) (*Rows, error) {
  2518  	return tx.QueryContext(context.Background(), query, args...)
  2519  }
  2520  
  2521  // QueryRowContext executes a query that is expected to return at most one row.
  2522  // QueryRowContext always returns a non-nil value. Errors are deferred until
  2523  // Row's Scan method is called.
  2524  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  2525  // Otherwise, the *Row's Scan scans the first selected row and discards
  2526  // the rest.
  2527  func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row {
  2528  	rows, err := tx.QueryContext(ctx, query, args...)
  2529  	return &Row{rows: rows, err: err}
  2530  }
  2531  
  2532  // QueryRow executes a query that is expected to return at most one row.
  2533  // QueryRow always returns a non-nil value. Errors are deferred until
  2534  // Row's Scan method is called.
  2535  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  2536  // Otherwise, the *Row's Scan scans the first selected row and discards
  2537  // the rest.
  2538  //
  2539  // QueryRow uses context.Background internally; to specify the context, use
  2540  // QueryRowContext.
  2541  func (tx *Tx) QueryRow(query string, args ...any) *Row {
  2542  	return tx.QueryRowContext(context.Background(), query, args...)
  2543  }
  2544  
  2545  // connStmt is a prepared statement on a particular connection.
  2546  type connStmt struct {
  2547  	dc *driverConn
  2548  	ds *driverStmt
  2549  }
  2550  
  2551  // stmtConnGrabber represents a Tx or Conn that will return the underlying
  2552  // driverConn and release function.
  2553  type stmtConnGrabber interface {
  2554  	// grabConn returns the driverConn and the associated release function
  2555  	// that must be called when the operation completes.
  2556  	grabConn(context.Context) (*driverConn, releaseConn, error)
  2557  
  2558  	// txCtx returns the transaction context if available.
  2559  	// The returned context should be selected on along with
  2560  	// any query context when awaiting a cancel.
  2561  	txCtx() context.Context
  2562  }
  2563  
  2564  var (
  2565  	_ stmtConnGrabber = &Tx{}
  2566  	_ stmtConnGrabber = &Conn{}
  2567  )
  2568  
  2569  // Stmt is a prepared statement.
  2570  // A Stmt is safe for concurrent use by multiple goroutines.
  2571  //
  2572  // If a Stmt is prepared on a Tx or Conn, it will be bound to a single
  2573  // underlying connection forever. If the Tx or Conn closes, the Stmt will
  2574  // become unusable and all operations will return an error.
  2575  // If a Stmt is prepared on a DB, it will remain usable for the lifetime of the
  2576  // DB. When the Stmt needs to execute on a new underlying connection, it will
  2577  // prepare itself on the new connection automatically.
  2578  type Stmt struct {
  2579  	// Immutable:
  2580  	db        *DB    // where we came from
  2581  	query     string // that created the Stmt
  2582  	stickyErr error  // if non-nil, this error is returned for all operations
  2583  
  2584  	closemu sync.RWMutex // held exclusively during close, for read otherwise.
  2585  
  2586  	// If Stmt is prepared on a Tx or Conn then cg is present and will
  2587  	// only ever grab a connection from cg.
  2588  	// If cg is nil then the Stmt must grab an arbitrary connection
  2589  	// from db and determine if it must prepare the stmt again by
  2590  	// inspecting css.
  2591  	cg   stmtConnGrabber
  2592  	cgds *driverStmt
  2593  
  2594  	// parentStmt is set when a transaction-specific statement
  2595  	// is requested from an identical statement prepared on the same
  2596  	// conn. parentStmt is used to track the dependency of this statement
  2597  	// on its originating ("parent") statement so that parentStmt may
  2598  	// be closed by the user without them having to know whether or not
  2599  	// any transactions are still using it.
  2600  	parentStmt *Stmt
  2601  
  2602  	mu     sync.Mutex // protects the rest of the fields
  2603  	closed bool
  2604  
  2605  	// css is a list of underlying driver statement interfaces
  2606  	// that are valid on particular connections. This is only
  2607  	// used if cg == nil and one is found that has idle
  2608  	// connections. If cg != nil, cgds is always used.
  2609  	css []connStmt
  2610  
  2611  	// lastNumClosed is copied from db.numClosed when Stmt is created
  2612  	// without tx and closed connections in css are removed.
  2613  	lastNumClosed uint64
  2614  }
  2615  
  2616  // ExecContext executes a prepared statement with the given arguments and
  2617  // returns a Result summarizing the effect of the statement.
  2618  func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error) {
  2619  	s.closemu.RLock()
  2620  	defer s.closemu.RUnlock()
  2621  
  2622  	var res Result
  2623  	strategy := cachedOrNewConn
  2624  	for i := 0; i < maxBadConnRetries+1; i++ {
  2625  		if i == maxBadConnRetries {
  2626  			strategy = alwaysNewConn
  2627  		}
  2628  		dc, releaseConn, ds, err := s.connStmt(ctx, strategy)
  2629  		if err != nil {
  2630  			if errors.Is(err, driver.ErrBadConn) {
  2631  				continue
  2632  			}
  2633  			return nil, err
  2634  		}
  2635  
  2636  		res, err = resultFromStatement(ctx, dc.ci, ds, args...)
  2637  		releaseConn(err)
  2638  		if !errors.Is(err, driver.ErrBadConn) {
  2639  			return res, err
  2640  		}
  2641  	}
  2642  	return nil, driver.ErrBadConn
  2643  }
  2644  
  2645  // Exec executes a prepared statement with the given arguments and
  2646  // returns a Result summarizing the effect of the statement.
  2647  //
  2648  // Exec uses context.Background internally; to specify the context, use
  2649  // ExecContext.
  2650  func (s *Stmt) Exec(args ...any) (Result, error) {
  2651  	return s.ExecContext(context.Background(), args...)
  2652  }
  2653  
  2654  func resultFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...any) (Result, error) {
  2655  	ds.Lock()
  2656  	defer ds.Unlock()
  2657  
  2658  	dargs, err := driverArgsConnLocked(ci, ds, args)
  2659  	if err != nil {
  2660  		return nil, err
  2661  	}
  2662  
  2663  	resi, err := ctxDriverStmtExec(ctx, ds.si, dargs)
  2664  	if err != nil {
  2665  		return nil, err
  2666  	}
  2667  	return driverResult{ds.Locker, resi}, nil
  2668  }
  2669  
  2670  // removeClosedStmtLocked removes closed conns in s.css.
  2671  //
  2672  // To avoid lock contention on DB.mu, we do it only when
  2673  // s.db.numClosed - s.lastNum is large enough.
  2674  func (s *Stmt) removeClosedStmtLocked() {
  2675  	t := len(s.css)/2 + 1
  2676  	if t > 10 {
  2677  		t = 10
  2678  	}
  2679  	dbClosed := atomic.LoadUint64(&s.db.numClosed)
  2680  	if dbClosed-s.lastNumClosed < uint64(t) {
  2681  		return
  2682  	}
  2683  
  2684  	s.db.mu.Lock()
  2685  	for i := 0; i < len(s.css); i++ {
  2686  		if s.css[i].dc.dbmuClosed {
  2687  			s.css[i] = s.css[len(s.css)-1]
  2688  			s.css = s.css[:len(s.css)-1]
  2689  			i--
  2690  		}
  2691  	}
  2692  	s.db.mu.Unlock()
  2693  	s.lastNumClosed = dbClosed
  2694  }
  2695  
  2696  // connStmt returns a free driver connection on which to execute the
  2697  // statement, a function to call to release the connection, and a
  2698  // statement bound to that connection.
  2699  func (s *Stmt) connStmt(ctx context.Context, strategy connReuseStrategy) (dc *driverConn, releaseConn func(error), ds *driverStmt, err error) {
  2700  	if err = s.stickyErr; err != nil {
  2701  		return
  2702  	}
  2703  	s.mu.Lock()
  2704  	if s.closed {
  2705  		s.mu.Unlock()
  2706  		err = errors.New("sql: statement is closed")
  2707  		return
  2708  	}
  2709  
  2710  	// In a transaction or connection, we always use the connection that the
  2711  	// stmt was created on.
  2712  	if s.cg != nil {
  2713  		s.mu.Unlock()
  2714  		dc, releaseConn, err = s.cg.grabConn(ctx) // blocks, waiting for the connection.
  2715  		if err != nil {
  2716  			return
  2717  		}
  2718  		return dc, releaseConn, s.cgds, nil
  2719  	}
  2720  
  2721  	s.removeClosedStmtLocked()
  2722  	s.mu.Unlock()
  2723  
  2724  	dc, err = s.db.conn(ctx, strategy)
  2725  	if err != nil {
  2726  		return nil, nil, nil, err
  2727  	}
  2728  
  2729  	s.mu.Lock()
  2730  	for _, v := range s.css {
  2731  		if v.dc == dc {
  2732  			s.mu.Unlock()
  2733  			return dc, dc.releaseConn, v.ds, nil
  2734  		}
  2735  	}
  2736  	s.mu.Unlock()
  2737  
  2738  	// No luck; we need to prepare the statement on this connection
  2739  	withLock(dc, func() {
  2740  		ds, err = s.prepareOnConnLocked(ctx, dc)
  2741  	})
  2742  	if err != nil {
  2743  		dc.releaseConn(err)
  2744  		return nil, nil, nil, err
  2745  	}
  2746  
  2747  	return dc, dc.releaseConn, ds, nil
  2748  }
  2749  
  2750  // prepareOnConnLocked prepares the query in Stmt s on dc and adds it to the list of
  2751  // open connStmt on the statement. It assumes the caller is holding the lock on dc.
  2752  func (s *Stmt) prepareOnConnLocked(ctx context.Context, dc *driverConn) (*driverStmt, error) {
  2753  	si, err := dc.prepareLocked(ctx, s.cg, s.query)
  2754  	if err != nil {
  2755  		return nil, err
  2756  	}
  2757  	cs := connStmt{dc, si}
  2758  	s.mu.Lock()
  2759  	s.css = append(s.css, cs)
  2760  	s.mu.Unlock()
  2761  	return cs.ds, nil
  2762  }
  2763  
  2764  // QueryContext executes a prepared query statement with the given arguments
  2765  // and returns the query results as a *Rows.
  2766  func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error) {
  2767  	s.closemu.RLock()
  2768  	defer s.closemu.RUnlock()
  2769  
  2770  	var rowsi driver.Rows
  2771  	strategy := cachedOrNewConn
  2772  	for i := 0; i < maxBadConnRetries+1; i++ {
  2773  		if i == maxBadConnRetries {
  2774  			strategy = alwaysNewConn
  2775  		}
  2776  		dc, releaseConn, ds, err := s.connStmt(ctx, strategy)
  2777  		if err != nil {
  2778  			if errors.Is(err, driver.ErrBadConn) {
  2779  				continue
  2780  			}
  2781  			return nil, err
  2782  		}
  2783  
  2784  		rowsi, err = rowsiFromStatement(ctx, dc.ci, ds, args...)
  2785  		if err == nil {
  2786  			// Note: ownership of ci passes to the *Rows, to be freed
  2787  			// with releaseConn.
  2788  			rows := &Rows{
  2789  				dc:    dc,
  2790  				rowsi: rowsi,
  2791  				// releaseConn set below
  2792  			}
  2793  			// addDep must be added before initContextClose or it could attempt
  2794  			// to removeDep before it has been added.
  2795  			s.db.addDep(s, rows)
  2796  
  2797  			// releaseConn must be set before initContextClose or it could
  2798  			// release the connection before it is set.
  2799  			rows.releaseConn = func(err error) {
  2800  				releaseConn(err)
  2801  				s.db.removeDep(s, rows)
  2802  			}
  2803  			var txctx context.Context
  2804  			if s.cg != nil {
  2805  				txctx = s.cg.txCtx()
  2806  			}
  2807  			rows.initContextClose(ctx, txctx)
  2808  			return rows, nil
  2809  		}
  2810  
  2811  		releaseConn(err)
  2812  		if !errors.Is(err, driver.ErrBadConn) {
  2813  			return nil, err
  2814  		}
  2815  	}
  2816  	return nil, driver.ErrBadConn
  2817  }
  2818  
  2819  // Query executes a prepared query statement with the given arguments
  2820  // and returns the query results as a *Rows.
  2821  //
  2822  // Query uses context.Background internally; to specify the context, use
  2823  // QueryContext.
  2824  func (s *Stmt) Query(args ...any) (*Rows, error) {
  2825  	return s.QueryContext(context.Background(), args...)
  2826  }
  2827  
  2828  func rowsiFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...any) (driver.Rows, error) {
  2829  	ds.Lock()
  2830  	defer ds.Unlock()
  2831  	dargs, err := driverArgsConnLocked(ci, ds, args)
  2832  	if err != nil {
  2833  		return nil, err
  2834  	}
  2835  	return ctxDriverStmtQuery(ctx, ds.si, dargs)
  2836  }
  2837  
  2838  // QueryRowContext executes a prepared query statement with the given arguments.
  2839  // If an error occurs during the execution of the statement, that error will
  2840  // be returned by a call to Scan on the returned *Row, which is always non-nil.
  2841  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  2842  // Otherwise, the *Row's Scan scans the first selected row and discards
  2843  // the rest.
  2844  func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row {
  2845  	rows, err := s.QueryContext(ctx, args...)
  2846  	if err != nil {
  2847  		return &Row{err: err}
  2848  	}
  2849  	return &Row{rows: rows}
  2850  }
  2851  
  2852  // QueryRow executes a prepared query statement with the given arguments.
  2853  // If an error occurs during the execution of the statement, that error will
  2854  // be returned by a call to Scan on the returned *Row, which is always non-nil.
  2855  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  2856  // Otherwise, the *Row's Scan scans the first selected row and discards
  2857  // the rest.
  2858  //
  2859  // Example usage:
  2860  //
  2861  //  var name string
  2862  //  err := nameByUseridStmt.QueryRow(id).Scan(&name)
  2863  //
  2864  // QueryRow uses context.Background internally; to specify the context, use
  2865  // QueryRowContext.
  2866  func (s *Stmt) QueryRow(args ...any) *Row {
  2867  	return s.QueryRowContext(context.Background(), args...)
  2868  }
  2869  
  2870  // Close closes the statement.
  2871  func (s *Stmt) Close() error {
  2872  	s.closemu.Lock()
  2873  	defer s.closemu.Unlock()
  2874  
  2875  	if s.stickyErr != nil {
  2876  		return s.stickyErr
  2877  	}
  2878  	s.mu.Lock()
  2879  	if s.closed {
  2880  		s.mu.Unlock()
  2881  		return nil
  2882  	}
  2883  	s.closed = true
  2884  	txds := s.cgds
  2885  	s.cgds = nil
  2886  
  2887  	s.mu.Unlock()
  2888  
  2889  	if s.cg == nil {
  2890  		return s.db.removeDep(s, s)
  2891  	}
  2892  
  2893  	if s.parentStmt != nil {
  2894  		// If parentStmt is set, we must not close s.txds since it's stored
  2895  		// in the css array of the parentStmt.
  2896  		return s.db.removeDep(s.parentStmt, s)
  2897  	}
  2898  	return txds.Close()
  2899  }
  2900  
  2901  func (s *Stmt) finalClose() error {
  2902  	s.mu.Lock()
  2903  	defer s.mu.Unlock()
  2904  	if s.css != nil {
  2905  		for _, v := range s.css {
  2906  			s.db.noteUnusedDriverStatement(v.dc, v.ds)
  2907  			v.dc.removeOpenStmt(v.ds)
  2908  		}
  2909  		s.css = nil
  2910  	}
  2911  	return nil
  2912  }
  2913  
  2914  // Rows is the result of a query. Its cursor starts before the first row
  2915  // of the result set. Use Next to advance from row to row.
  2916  type Rows struct {
  2917  	dc          *driverConn // owned; must call releaseConn when closed to release
  2918  	releaseConn func(error)
  2919  	rowsi       driver.Rows
  2920  	cancel      func()      // called when Rows is closed, may be nil.
  2921  	closeStmt   *driverStmt // if non-nil, statement to Close on close
  2922  
  2923  	// closemu prevents Rows from closing while there
  2924  	// is an active streaming result. It is held for read during non-close operations
  2925  	// and exclusively during close.
  2926  	//
  2927  	// closemu guards lasterr and closed.
  2928  	closemu sync.RWMutex
  2929  	closed  bool
  2930  	lasterr error // non-nil only if closed is true
  2931  
  2932  	// lastcols is only used in Scan, Next, and NextResultSet which are expected
  2933  	// not to be called concurrently.
  2934  	lastcols []driver.Value
  2935  }
  2936  
  2937  // lasterrOrErrLocked returns either lasterr or the provided err.
  2938  // rs.closemu must be read-locked.
  2939  func (rs *Rows) lasterrOrErrLocked(err error) error {
  2940  	if rs.lasterr != nil && rs.lasterr != io.EOF {
  2941  		return rs.lasterr
  2942  	}
  2943  	return err
  2944  }
  2945  
  2946  // bypassRowsAwaitDone is only used for testing.
  2947  // If true, it will not close the Rows automatically from the context.
  2948  var bypassRowsAwaitDone = false
  2949  
  2950  func (rs *Rows) initContextClose(ctx, txctx context.Context) {
  2951  	if ctx.Done() == nil && (txctx == nil || txctx.Done() == nil) {
  2952  		return
  2953  	}
  2954  	if bypassRowsAwaitDone {
  2955  		return
  2956  	}
  2957  	ctx, rs.cancel = context.WithCancel(ctx)
  2958  	go rs.awaitDone(ctx, txctx)
  2959  }
  2960  
  2961  // awaitDone blocks until either ctx or txctx is canceled. The ctx is provided
  2962  // from the query context and is canceled when the query Rows is closed.
  2963  // If the query was issued in a transaction, the transaction's context
  2964  // is also provided in txctx to ensure Rows is closed if the Tx is closed.
  2965  func (rs *Rows) awaitDone(ctx, txctx context.Context) {
  2966  	var txctxDone <-chan struct{}
  2967  	if txctx != nil {
  2968  		txctxDone = txctx.Done()
  2969  	}
  2970  	select {
  2971  	case <-ctx.Done():
  2972  	case <-txctxDone:
  2973  	}
  2974  	rs.close(ctx.Err())
  2975  }
  2976  
  2977  // Next prepares the next result row for reading with the Scan method. It
  2978  // returns true on success, or false if there is no next result row or an error
  2979  // happened while preparing it. Err should be consulted to distinguish between
  2980  // the two cases.
  2981  //
  2982  // Every call to Scan, even the first one, must be preceded by a call to Next.
  2983  func (rs *Rows) Next() bool {
  2984  	var doClose, ok bool
  2985  	withLock(rs.closemu.RLocker(), func() {
  2986  		doClose, ok = rs.nextLocked()
  2987  	})
  2988  	if doClose {
  2989  		rs.Close()
  2990  	}
  2991  	return ok
  2992  }
  2993  
  2994  func (rs *Rows) nextLocked() (doClose, ok bool) {
  2995  	if rs.closed {
  2996  		return false, false
  2997  	}
  2998  
  2999  	// Lock the driver connection before calling the driver interface
  3000  	// rowsi to prevent a Tx from rolling back the connection at the same time.
  3001  	rs.dc.Lock()
  3002  	defer rs.dc.Unlock()
  3003  
  3004  	if rs.lastcols == nil {
  3005  		rs.lastcols = make([]driver.Value, len(rs.rowsi.Columns()))
  3006  	}
  3007  
  3008  	rs.lasterr = rs.rowsi.Next(rs.lastcols)
  3009  	if rs.lasterr != nil {
  3010  		// Close the connection if there is a driver error.
  3011  		if rs.lasterr != io.EOF {
  3012  			return true, false
  3013  		}
  3014  		nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
  3015  		if !ok {
  3016  			return true, false
  3017  		}
  3018  		// The driver is at the end of the current result set.
  3019  		// Test to see if there is another result set after the current one.
  3020  		// Only close Rows if there is no further result sets to read.
  3021  		if !nextResultSet.HasNextResultSet() {
  3022  			doClose = true
  3023  		}
  3024  		return doClose, false
  3025  	}
  3026  	return false, true
  3027  }
  3028  
  3029  // NextResultSet prepares the next result set for reading. It reports whether
  3030  // there is further result sets, or false if there is no further result set
  3031  // or if there is an error advancing to it. The Err method should be consulted
  3032  // to distinguish between the two cases.
  3033  //
  3034  // After calling NextResultSet, the Next method should always be called before
  3035  // scanning. If there are further result sets they may not have rows in the result
  3036  // set.
  3037  func (rs *Rows) NextResultSet() bool {
  3038  	var doClose bool
  3039  	defer func() {
  3040  		if doClose {
  3041  			rs.Close()
  3042  		}
  3043  	}()
  3044  	rs.closemu.RLock()
  3045  	defer rs.closemu.RUnlock()
  3046  
  3047  	if rs.closed {
  3048  		return false
  3049  	}
  3050  
  3051  	rs.lastcols = nil
  3052  	nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
  3053  	if !ok {
  3054  		doClose = true
  3055  		return false
  3056  	}
  3057  
  3058  	// Lock the driver connection before calling the driver interface
  3059  	// rowsi to prevent a Tx from rolling back the connection at the same time.
  3060  	rs.dc.Lock()
  3061  	defer rs.dc.Unlock()
  3062  
  3063  	rs.lasterr = nextResultSet.NextResultSet()
  3064  	if rs.lasterr != nil {
  3065  		doClose = true
  3066  		return false
  3067  	}
  3068  	return true
  3069  }
  3070  
  3071  // Err returns the error, if any, that was encountered during iteration.
  3072  // Err may be called after an explicit or implicit Close.
  3073  func (rs *Rows) Err() error {
  3074  	rs.closemu.RLock()
  3075  	defer rs.closemu.RUnlock()
  3076  	return rs.lasterrOrErrLocked(nil)
  3077  }
  3078  
  3079  var errRowsClosed = errors.New("sql: Rows are closed")
  3080  var errNoRows = errors.New("sql: no Rows available")
  3081  
  3082  // Columns returns the column names.
  3083  // Columns returns an error if the rows are closed.
  3084  func (rs *Rows) Columns() ([]string, error) {
  3085  	rs.closemu.RLock()
  3086  	defer rs.closemu.RUnlock()
  3087  	if rs.closed {
  3088  		return nil, rs.lasterrOrErrLocked(errRowsClosed)
  3089  	}
  3090  	if rs.rowsi == nil {
  3091  		return nil, rs.lasterrOrErrLocked(errNoRows)
  3092  	}
  3093  	rs.dc.Lock()
  3094  	defer rs.dc.Unlock()
  3095  
  3096  	return rs.rowsi.Columns(), nil
  3097  }
  3098  
  3099  // ColumnTypes returns column information such as column type, length,
  3100  // and nullable. Some information may not be available from some drivers.
  3101  func (rs *Rows) ColumnTypes() ([]*ColumnType, error) {
  3102  	rs.closemu.RLock()
  3103  	defer rs.closemu.RUnlock()
  3104  	if rs.closed {
  3105  		return nil, rs.lasterrOrErrLocked(errRowsClosed)
  3106  	}
  3107  	if rs.rowsi == nil {
  3108  		return nil, rs.lasterrOrErrLocked(errNoRows)
  3109  	}
  3110  	rs.dc.Lock()
  3111  	defer rs.dc.Unlock()
  3112  
  3113  	return rowsColumnInfoSetupConnLocked(rs.rowsi), nil
  3114  }
  3115  
  3116  // ColumnType contains the name and type of a column.
  3117  type ColumnType struct {
  3118  	name string
  3119  
  3120  	hasNullable       bool
  3121  	hasLength         bool
  3122  	hasPrecisionScale bool
  3123  
  3124  	nullable     bool
  3125  	length       int64
  3126  	databaseType string
  3127  	precision    int64
  3128  	scale        int64
  3129  	scanType     reflect.Type
  3130  }
  3131  
  3132  // Name returns the name or alias of the column.
  3133  func (ci *ColumnType) Name() string {
  3134  	return ci.name
  3135  }
  3136  
  3137  // Length returns the column type length for variable length column types such
  3138  // as text and binary field types. If the type length is unbounded the value will
  3139  // be math.MaxInt64 (any database limits will still apply).
  3140  // If the column type is not variable length, such as an int, or if not supported
  3141  // by the driver ok is false.
  3142  func (ci *ColumnType) Length() (length int64, ok bool) {
  3143  	return ci.length, ci.hasLength
  3144  }
  3145  
  3146  // DecimalSize returns the scale and precision of a decimal type.
  3147  // If not applicable or if not supported ok is false.
  3148  func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool) {
  3149  	return ci.precision, ci.scale, ci.hasPrecisionScale
  3150  }
  3151  
  3152  // ScanType returns a Go type suitable for scanning into using Rows.Scan.
  3153  // If a driver does not support this property ScanType will return
  3154  // the type of an empty interface.
  3155  func (ci *ColumnType) ScanType() reflect.Type {
  3156  	return ci.scanType
  3157  }
  3158  
  3159  // Nullable reports whether the column may be null.
  3160  // If a driver does not support this property ok will be false.
  3161  func (ci *ColumnType) Nullable() (nullable, ok bool) {
  3162  	return ci.nullable, ci.hasNullable
  3163  }
  3164  
  3165  // DatabaseTypeName returns the database system name of the column type. If an empty
  3166  // string is returned, then the driver type name is not supported.
  3167  // Consult your driver documentation for a list of driver data types. Length specifiers
  3168  // are not included.
  3169  // Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL",
  3170  // "INT", and "BIGINT".
  3171  func (ci *ColumnType) DatabaseTypeName() string {
  3172  	return ci.databaseType
  3173  }
  3174  
  3175  func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
  3176  	names := rowsi.Columns()
  3177  
  3178  	list := make([]*ColumnType, len(names))
  3179  	for i := range list {
  3180  		ci := &ColumnType{
  3181  			name: names[i],
  3182  		}
  3183  		list[i] = ci
  3184  
  3185  		if prop, ok := rowsi.(driver.RowsColumnTypeScanType); ok {
  3186  			ci.scanType = prop.ColumnTypeScanType(i)
  3187  		} else {
  3188  			ci.scanType = reflect.TypeOf(new(any)).Elem()
  3189  		}
  3190  		if prop, ok := rowsi.(driver.RowsColumnTypeDatabaseTypeName); ok {
  3191  			ci.databaseType = prop.ColumnTypeDatabaseTypeName(i)
  3192  		}
  3193  		if prop, ok := rowsi.(driver.RowsColumnTypeLength); ok {
  3194  			ci.length, ci.hasLength = prop.ColumnTypeLength(i)
  3195  		}
  3196  		if prop, ok := rowsi.(driver.RowsColumnTypeNullable); ok {
  3197  			ci.nullable, ci.hasNullable = prop.ColumnTypeNullable(i)
  3198  		}
  3199  		if prop, ok := rowsi.(driver.RowsColumnTypePrecisionScale); ok {
  3200  			ci.precision, ci.scale, ci.hasPrecisionScale = prop.ColumnTypePrecisionScale(i)
  3201  		}
  3202  	}
  3203  	return list
  3204  }
  3205  
  3206  // Scan copies the columns in the current row into the values pointed
  3207  // at by dest. The number of values in dest must be the same as the
  3208  // number of columns in Rows.
  3209  //
  3210  // Scan converts columns read from the database into the following
  3211  // common Go types and special types provided by the sql package:
  3212  //
  3213  //    *string
  3214  //    *[]byte
  3215  //    *int, *int8, *int16, *int32, *int64
  3216  //    *uint, *uint8, *uint16, *uint32, *uint64
  3217  //    *bool
  3218  //    *float32, *float64
  3219  //    *interface{}
  3220  //    *RawBytes
  3221  //    *Rows (cursor value)
  3222  //    any type implementing Scanner (see Scanner docs)
  3223  //
  3224  // In the most simple case, if the type of the value from the source
  3225  // column is an integer, bool or string type T and dest is of type *T,
  3226  // Scan simply assigns the value through the pointer.
  3227  //
  3228  // Scan also converts between string and numeric types, as long as no
  3229  // information would be lost. While Scan stringifies all numbers
  3230  // scanned from numeric database columns into *string, scans into
  3231  // numeric types are checked for overflow. For example, a float64 with
  3232  // value 300 or a string with value "300" can scan into a uint16, but
  3233  // not into a uint8, though float64(255) or "255" can scan into a
  3234  // uint8. One exception is that scans of some float64 numbers to
  3235  // strings may lose information when stringifying. In general, scan
  3236  // floating point columns into *float64.
  3237  //
  3238  // If a dest argument has type *[]byte, Scan saves in that argument a
  3239  // copy of the corresponding data. The copy is owned by the caller and
  3240  // can be modified and held indefinitely. The copy can be avoided by
  3241  // using an argument of type *RawBytes instead; see the documentation
  3242  // for RawBytes for restrictions on its use.
  3243  //
  3244  // If an argument has type *interface{}, Scan copies the value
  3245  // provided by the underlying driver without conversion. When scanning
  3246  // from a source value of type []byte to *interface{}, a copy of the
  3247  // slice is made and the caller owns the result.
  3248  //
  3249  // Source values of type time.Time may be scanned into values of type
  3250  // *time.Time, *interface{}, *string, or *[]byte. When converting to
  3251  // the latter two, time.RFC3339Nano is used.
  3252  //
  3253  // Source values of type bool may be scanned into types *bool,
  3254  // *interface{}, *string, *[]byte, or *RawBytes.
  3255  //
  3256  // For scanning into *bool, the source may be true, false, 1, 0, or
  3257  // string inputs parseable by strconv.ParseBool.
  3258  //
  3259  // Scan can also convert a cursor returned from a query, such as
  3260  // "select cursor(select * from my_table) from dual", into a
  3261  // *Rows value that can itself be scanned from. The parent
  3262  // select query will close any cursor *Rows if the parent *Rows is closed.
  3263  //
  3264  // If any of the first arguments implementing Scanner returns an error,
  3265  // that error will be wrapped in the returned error
  3266  func (rs *Rows) Scan(dest ...any) error {
  3267  	rs.closemu.RLock()
  3268  
  3269  	if rs.lasterr != nil && rs.lasterr != io.EOF {
  3270  		rs.closemu.RUnlock()
  3271  		return rs.lasterr
  3272  	}
  3273  	if rs.closed {
  3274  		err := rs.lasterrOrErrLocked(errRowsClosed)
  3275  		rs.closemu.RUnlock()
  3276  		return err
  3277  	}
  3278  	rs.closemu.RUnlock()
  3279  
  3280  	if rs.lastcols == nil {
  3281  		return errors.New("sql: Scan called without calling Next")
  3282  	}
  3283  	if len(dest) != len(rs.lastcols) {
  3284  		return fmt.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest))
  3285  	}
  3286  	for i, sv := range rs.lastcols {
  3287  		err := convertAssignRows(dest[i], sv, rs)
  3288  		if err != nil {
  3289  			return fmt.Errorf(`sql: Scan error on column index %d, name %q: %w`, i, rs.rowsi.Columns()[i], err)
  3290  		}
  3291  	}
  3292  	return nil
  3293  }
  3294  
  3295  // rowsCloseHook returns a function so tests may install the
  3296  // hook through a test only mutex.
  3297  var rowsCloseHook = func() func(*Rows, *error) { return nil }
  3298  
  3299  // Close closes the Rows, preventing further enumeration. If Next is called
  3300  // and returns false and there are no further result sets,
  3301  // the Rows are closed automatically and it will suffice to check the
  3302  // result of Err. Close is idempotent and does not affect the result of Err.
  3303  func (rs *Rows) Close() error {
  3304  	return rs.close(nil)
  3305  }
  3306  
  3307  func (rs *Rows) close(err error) error {
  3308  	rs.closemu.Lock()
  3309  	defer rs.closemu.Unlock()
  3310  
  3311  	if rs.closed {
  3312  		return nil
  3313  	}
  3314  	rs.closed = true
  3315  
  3316  	if rs.lasterr == nil {
  3317  		rs.lasterr = err
  3318  	}
  3319  
  3320  	withLock(rs.dc, func() {
  3321  		err = rs.rowsi.Close()
  3322  	})
  3323  	if fn := rowsCloseHook(); fn != nil {
  3324  		fn(rs, &err)
  3325  	}
  3326  	if rs.cancel != nil {
  3327  		rs.cancel()
  3328  	}
  3329  
  3330  	if rs.closeStmt != nil {
  3331  		rs.closeStmt.Close()
  3332  	}
  3333  	rs.releaseConn(err)
  3334  	return err
  3335  }
  3336  
  3337  // Row is the result of calling QueryRow to select a single row.
  3338  type Row struct {
  3339  	// One of these two will be non-nil:
  3340  	err  error // deferred error for easy chaining
  3341  	rows *Rows
  3342  }
  3343  
  3344  // Scan copies the columns from the matched row into the values
  3345  // pointed at by dest. See the documentation on Rows.Scan for details.
  3346  // If more than one row matches the query,
  3347  // Scan uses the first row and discards the rest. If no row matches
  3348  // the query, Scan returns ErrNoRows.
  3349  func (r *Row) Scan(dest ...any) error {
  3350  	if r.err != nil {
  3351  		return r.err
  3352  	}
  3353  
  3354  	// TODO(bradfitz): for now we need to defensively clone all
  3355  	// []byte that the driver returned (not permitting
  3356  	// *RawBytes in Rows.Scan), since we're about to close
  3357  	// the Rows in our defer, when we return from this function.
  3358  	// the contract with the driver.Next(...) interface is that it
  3359  	// can return slices into read-only temporary memory that's
  3360  	// only valid until the next Scan/Close. But the TODO is that
  3361  	// for a lot of drivers, this copy will be unnecessary. We
  3362  	// should provide an optional interface for drivers to
  3363  	// implement to say, "don't worry, the []bytes that I return
  3364  	// from Next will not be modified again." (for instance, if
  3365  	// they were obtained from the network anyway) But for now we
  3366  	// don't care.
  3367  	defer r.rows.Close()
  3368  	for _, dp := range dest {
  3369  		if _, ok := dp.(*RawBytes); ok {
  3370  			return errors.New("sql: RawBytes isn't allowed on Row.Scan")
  3371  		}
  3372  	}
  3373  
  3374  	if !r.rows.Next() {
  3375  		if err := r.rows.Err(); err != nil {
  3376  			return err
  3377  		}
  3378  		return ErrNoRows
  3379  	}
  3380  	err := r.rows.Scan(dest...)
  3381  	if err != nil {
  3382  		return err
  3383  	}
  3384  	// Make sure the query can be processed to completion with no errors.
  3385  	return r.rows.Close()
  3386  }
  3387  
  3388  // Err provides a way for wrapping packages to check for
  3389  // query errors without calling Scan.
  3390  // Err returns the error, if any, that was encountered while running the query.
  3391  // If this error is not nil, this error will also be returned from Scan.
  3392  func (r *Row) Err() error {
  3393  	return r.err
  3394  }
  3395  
  3396  // A Result summarizes an executed SQL command.
  3397  type Result interface {
  3398  	// LastInsertId returns the integer generated by the database
  3399  	// in response to a command. Typically this will be from an
  3400  	// "auto increment" column when inserting a new row. Not all
  3401  	// databases support this feature, and the syntax of such
  3402  	// statements varies.
  3403  	LastInsertId() (int64, error)
  3404  
  3405  	// RowsAffected returns the number of rows affected by an
  3406  	// update, insert, or delete. Not every database or database
  3407  	// driver may support this.
  3408  	RowsAffected() (int64, error)
  3409  }
  3410  
  3411  type driverResult struct {
  3412  	sync.Locker // the *driverConn
  3413  	resi        driver.Result
  3414  }
  3415  
  3416  func (dr driverResult) LastInsertId() (int64, error) {
  3417  	dr.Lock()
  3418  	defer dr.Unlock()
  3419  	return dr.resi.LastInsertId()
  3420  }
  3421  
  3422  func (dr driverResult) RowsAffected() (int64, error) {
  3423  	dr.Lock()
  3424  	defer dr.Unlock()
  3425  	return dr.resi.RowsAffected()
  3426  }
  3427  
  3428  func stack() string {
  3429  	var buf [2 << 10]byte
  3430  	return string(buf[:runtime.Stack(buf[:], false)])
  3431  }
  3432  
  3433  // withLock runs while holding lk.
  3434  func withLock(lk sync.Locker, fn func()) {
  3435  	lk.Lock()
  3436  	defer lk.Unlock() // in case fn panics
  3437  	fn()
  3438  }
  3439  

View as plain text