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

View as plain text