Source file src/database/sql/sql.go

Documentation: database/sql

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

View as plain text