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

View as plain text