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

View as plain text