Black Lives Matter. Support the Equal Justice Initiative.

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

View as plain text