github.com/dannin/go@v0.0.0-20161031215817-d35dfd405eaa/src/database/sql/sql.go (about)

     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  // For more usage examples, see the wiki page at
    12  // https://golang.org/s/sqlwiki.
    13  package sql
    14  
    15  import (
    16  	"context"
    17  	"database/sql/driver"
    18  	"database/sql/internal"
    19  	"errors"
    20  	"fmt"
    21  	"io"
    22  	"reflect"
    23  	"runtime"
    24  	"sort"
    25  	"sync"
    26  	"sync/atomic"
    27  	"time"
    28  )
    29  
    30  var (
    31  	driversMu sync.RWMutex
    32  	drivers   = make(map[string]driver.Driver)
    33  )
    34  
    35  // nowFunc returns the current time; it's overridden in tests.
    36  var nowFunc = time.Now
    37  
    38  // Register makes a database driver available by the provided name.
    39  // If Register is called twice with the same name or if driver is nil,
    40  // it panics.
    41  func Register(name string, driver driver.Driver) {
    42  	driversMu.Lock()
    43  	defer driversMu.Unlock()
    44  	if driver == nil {
    45  		panic("sql: Register driver is nil")
    46  	}
    47  	if _, dup := drivers[name]; dup {
    48  		panic("sql: Register called twice for driver " + name)
    49  	}
    50  	drivers[name] = driver
    51  }
    52  
    53  func unregisterAllDrivers() {
    54  	driversMu.Lock()
    55  	defer driversMu.Unlock()
    56  	// For tests.
    57  	drivers = make(map[string]driver.Driver)
    58  }
    59  
    60  // Drivers returns a sorted list of the names of the registered drivers.
    61  func Drivers() []string {
    62  	driversMu.RLock()
    63  	defer driversMu.RUnlock()
    64  	var list []string
    65  	for name := range drivers {
    66  		list = append(list, name)
    67  	}
    68  	sort.Strings(list)
    69  	return list
    70  }
    71  
    72  // NamedParam may be passed into query parameter arguments to associate
    73  // a named placeholder with a value.
    74  type NamedParam struct {
    75  	// Name of the parameter placeholder. If empty the ordinal position in the
    76  	// argument list will be used.
    77  	Name string
    78  
    79  	// Value of the parameter. It may be assigned the same value types as
    80  	// the query arguments.
    81  	Value interface{}
    82  }
    83  
    84  // Param provides a more concise way to create NamedParam values.
    85  func Param(name string, value interface{}) NamedParam {
    86  	// This method exists because the go1compat promise
    87  	// doesn't guarantee that structs don't grow more fields,
    88  	// so unkeyed struct literals are a vet error. Thus, we don't
    89  	// want to encourage sql.NamedParam{name, value}.
    90  	return NamedParam{Name: name, Value: value}
    91  }
    92  
    93  // IsolationLevel is the transaction isolation level stored in Context.
    94  // The IsolationLevel is set with IsolationContext and the context
    95  // should be passed to BeginContext.
    96  type IsolationLevel int
    97  
    98  // Various isolation levels that drivers may support in BeginContext.
    99  // If a driver does not support a given isolation level an error may be returned.
   100  //
   101  // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.
   102  const (
   103  	LevelDefault IsolationLevel = iota
   104  	LevelReadUncommitted
   105  	LevelReadCommitted
   106  	LevelWriteCommitted
   107  	LevelRepeatableRead
   108  	LevelSnapshot
   109  	LevelSerializable
   110  	LevelLinearizable
   111  )
   112  
   113  // IsolationContext returns a new Context that carries the provided isolation level.
   114  // The context must contain the isolation level before beginning the transaction
   115  // with BeginContext.
   116  func IsolationContext(ctx context.Context, level IsolationLevel) context.Context {
   117  	return context.WithValue(ctx, internal.IsolationLevelKey{}, driver.IsolationLevel(level))
   118  }
   119  
   120  // ReadOnlyWithContext returns a new Context that carries the provided
   121  // read-only transaction property. The context must contain the read-only property
   122  // before beginning the transaction with BeginContext.
   123  func ReadOnlyContext(ctx context.Context) context.Context {
   124  	return context.WithValue(ctx, internal.ReadOnlyKey{}, true)
   125  }
   126  
   127  // RawBytes is a byte slice that holds a reference to memory owned by
   128  // the database itself. After a Scan into a RawBytes, the slice is only
   129  // valid until the next call to Next, Scan, or Close.
   130  type RawBytes []byte
   131  
   132  // NullString represents a string that may be null.
   133  // NullString implements the Scanner interface so
   134  // it can be used as a scan destination:
   135  //
   136  //  var s NullString
   137  //  err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
   138  //  ...
   139  //  if s.Valid {
   140  //     // use s.String
   141  //  } else {
   142  //     // NULL value
   143  //  }
   144  //
   145  type NullString struct {
   146  	String string
   147  	Valid  bool // Valid is true if String is not NULL
   148  }
   149  
   150  // Scan implements the Scanner interface.
   151  func (ns *NullString) Scan(value interface{}) error {
   152  	if value == nil {
   153  		ns.String, ns.Valid = "", false
   154  		return nil
   155  	}
   156  	ns.Valid = true
   157  	return convertAssign(&ns.String, value)
   158  }
   159  
   160  // Value implements the driver Valuer interface.
   161  func (ns NullString) Value() (driver.Value, error) {
   162  	if !ns.Valid {
   163  		return nil, nil
   164  	}
   165  	return ns.String, nil
   166  }
   167  
   168  // NullInt64 represents an int64 that may be null.
   169  // NullInt64 implements the Scanner interface so
   170  // it can be used as a scan destination, similar to NullString.
   171  type NullInt64 struct {
   172  	Int64 int64
   173  	Valid bool // Valid is true if Int64 is not NULL
   174  }
   175  
   176  // Scan implements the Scanner interface.
   177  func (n *NullInt64) Scan(value interface{}) error {
   178  	if value == nil {
   179  		n.Int64, n.Valid = 0, false
   180  		return nil
   181  	}
   182  	n.Valid = true
   183  	return convertAssign(&n.Int64, value)
   184  }
   185  
   186  // Value implements the driver Valuer interface.
   187  func (n NullInt64) Value() (driver.Value, error) {
   188  	if !n.Valid {
   189  		return nil, nil
   190  	}
   191  	return n.Int64, nil
   192  }
   193  
   194  // NullFloat64 represents a float64 that may be null.
   195  // NullFloat64 implements the Scanner interface so
   196  // it can be used as a scan destination, similar to NullString.
   197  type NullFloat64 struct {
   198  	Float64 float64
   199  	Valid   bool // Valid is true if Float64 is not NULL
   200  }
   201  
   202  // Scan implements the Scanner interface.
   203  func (n *NullFloat64) Scan(value interface{}) error {
   204  	if value == nil {
   205  		n.Float64, n.Valid = 0, false
   206  		return nil
   207  	}
   208  	n.Valid = true
   209  	return convertAssign(&n.Float64, value)
   210  }
   211  
   212  // Value implements the driver Valuer interface.
   213  func (n NullFloat64) Value() (driver.Value, error) {
   214  	if !n.Valid {
   215  		return nil, nil
   216  	}
   217  	return n.Float64, nil
   218  }
   219  
   220  // NullBool represents a bool that may be null.
   221  // NullBool implements the Scanner interface so
   222  // it can be used as a scan destination, similar to NullString.
   223  type NullBool struct {
   224  	Bool  bool
   225  	Valid bool // Valid is true if Bool is not NULL
   226  }
   227  
   228  // Scan implements the Scanner interface.
   229  func (n *NullBool) Scan(value interface{}) error {
   230  	if value == nil {
   231  		n.Bool, n.Valid = false, false
   232  		return nil
   233  	}
   234  	n.Valid = true
   235  	return convertAssign(&n.Bool, value)
   236  }
   237  
   238  // Value implements the driver Valuer interface.
   239  func (n NullBool) Value() (driver.Value, error) {
   240  	if !n.Valid {
   241  		return nil, nil
   242  	}
   243  	return n.Bool, nil
   244  }
   245  
   246  // Scanner is an interface used by Scan.
   247  type Scanner interface {
   248  	// Scan assigns a value from a database driver.
   249  	//
   250  	// The src value will be of one of the following types:
   251  	//
   252  	//    int64
   253  	//    float64
   254  	//    bool
   255  	//    []byte
   256  	//    string
   257  	//    time.Time
   258  	//    nil - for NULL values
   259  	//
   260  	// An error should be returned if the value cannot be stored
   261  	// without loss of information.
   262  	Scan(src interface{}) error
   263  }
   264  
   265  // ErrNoRows is returned by Scan when QueryRow doesn't return a
   266  // row. In such a case, QueryRow returns a placeholder *Row value that
   267  // defers this error until a Scan.
   268  var ErrNoRows = errors.New("sql: no rows in result set")
   269  
   270  // DB is a database handle representing a pool of zero or more
   271  // underlying connections. It's safe for concurrent use by multiple
   272  // goroutines.
   273  //
   274  // The sql package creates and frees connections automatically; it
   275  // also maintains a free pool of idle connections. If the database has
   276  // a concept of per-connection state, such state can only be reliably
   277  // observed within a transaction. Once DB.Begin is called, the
   278  // returned Tx is bound to a single connection. Once Commit or
   279  // Rollback is called on the transaction, that transaction's
   280  // connection is returned to DB's idle connection pool. The pool size
   281  // can be controlled with SetMaxIdleConns.
   282  type DB struct {
   283  	driver driver.Driver
   284  	dsn    string
   285  	// numClosed is an atomic counter which represents a total number of
   286  	// closed connections. Stmt.openStmt checks it before cleaning closed
   287  	// connections in Stmt.css.
   288  	numClosed uint64
   289  
   290  	mu           sync.Mutex // protects following fields
   291  	freeConn     []*driverConn
   292  	connRequests []chan connRequest
   293  	numOpen      int // number of opened and pending open connections
   294  	// Used to signal the need for new connections
   295  	// a goroutine running connectionOpener() reads on this chan and
   296  	// maybeOpenNewConnections sends on the chan (one send per needed connection)
   297  	// It is closed during db.Close(). The close tells the connectionOpener
   298  	// goroutine to exit.
   299  	openerCh    chan struct{}
   300  	closed      bool
   301  	dep         map[finalCloser]depSet
   302  	lastPut     map[*driverConn]string // stacktrace of last conn's put; debug only
   303  	maxIdle     int                    // zero means defaultMaxIdleConns; negative means 0
   304  	maxOpen     int                    // <= 0 means unlimited
   305  	maxLifetime time.Duration          // maximum amount of time a connection may be reused
   306  	cleanerCh   chan struct{}
   307  }
   308  
   309  // connReuseStrategy determines how (*DB).conn returns database connections.
   310  type connReuseStrategy uint8
   311  
   312  const (
   313  	// alwaysNewConn forces a new connection to the database.
   314  	alwaysNewConn connReuseStrategy = iota
   315  	// cachedOrNewConn returns a cached connection, if available, else waits
   316  	// for one to become available (if MaxOpenConns has been reached) or
   317  	// creates a new database connection.
   318  	cachedOrNewConn
   319  )
   320  
   321  // driverConn wraps a driver.Conn with a mutex, to
   322  // be held during all calls into the Conn. (including any calls onto
   323  // interfaces returned via that Conn, such as calls on Tx, Stmt,
   324  // Result, Rows)
   325  type driverConn struct {
   326  	db        *DB
   327  	createdAt time.Time
   328  
   329  	sync.Mutex  // guards following
   330  	ci          driver.Conn
   331  	closed      bool
   332  	finalClosed bool // ci.Close has been called
   333  	openStmt    map[driver.Stmt]bool
   334  
   335  	// guarded by db.mu
   336  	inUse      bool
   337  	onPut      []func() // code (with db.mu held) run when conn is next returned
   338  	dbmuClosed bool     // same as closed, but guarded by db.mu, for removeClosedStmtLocked
   339  }
   340  
   341  func (dc *driverConn) releaseConn(err error) {
   342  	dc.db.putConn(dc, err)
   343  }
   344  
   345  func (dc *driverConn) removeOpenStmt(si driver.Stmt) {
   346  	dc.Lock()
   347  	defer dc.Unlock()
   348  	delete(dc.openStmt, si)
   349  }
   350  
   351  func (dc *driverConn) expired(timeout time.Duration) bool {
   352  	if timeout <= 0 {
   353  		return false
   354  	}
   355  	return dc.createdAt.Add(timeout).Before(nowFunc())
   356  }
   357  
   358  func (dc *driverConn) prepareLocked(ctx context.Context, query string) (driver.Stmt, error) {
   359  	si, err := ctxDriverPrepare(ctx, dc.ci, query)
   360  	if err == nil {
   361  		// Track each driverConn's open statements, so we can close them
   362  		// before closing the conn.
   363  		//
   364  		// TODO(bradfitz): let drivers opt out of caring about
   365  		// stmt closes if the conn is about to close anyway? For now
   366  		// do the safe thing, in case stmts need to be closed.
   367  		//
   368  		// TODO(bradfitz): after Go 1.2, closing driver.Stmts
   369  		// should be moved to driverStmt, using unique
   370  		// *driverStmts everywhere (including from
   371  		// *Stmt.connStmt, instead of returning a
   372  		// driver.Stmt), using driverStmt as a pointer
   373  		// everywhere, and making it a finalCloser.
   374  		if dc.openStmt == nil {
   375  			dc.openStmt = make(map[driver.Stmt]bool)
   376  		}
   377  		dc.openStmt[si] = true
   378  	}
   379  	return si, err
   380  }
   381  
   382  // the dc.db's Mutex is held.
   383  func (dc *driverConn) closeDBLocked() func() error {
   384  	dc.Lock()
   385  	defer dc.Unlock()
   386  	if dc.closed {
   387  		return func() error { return errors.New("sql: duplicate driverConn close") }
   388  	}
   389  	dc.closed = true
   390  	return dc.db.removeDepLocked(dc, dc)
   391  }
   392  
   393  func (dc *driverConn) Close() error {
   394  	dc.Lock()
   395  	if dc.closed {
   396  		dc.Unlock()
   397  		return errors.New("sql: duplicate driverConn close")
   398  	}
   399  	dc.closed = true
   400  	dc.Unlock() // not defer; removeDep finalClose calls may need to lock
   401  
   402  	// And now updates that require holding dc.mu.Lock.
   403  	dc.db.mu.Lock()
   404  	dc.dbmuClosed = true
   405  	fn := dc.db.removeDepLocked(dc, dc)
   406  	dc.db.mu.Unlock()
   407  	return fn()
   408  }
   409  
   410  func (dc *driverConn) finalClose() error {
   411  	dc.Lock()
   412  
   413  	for si := range dc.openStmt {
   414  		si.Close()
   415  	}
   416  	dc.openStmt = nil
   417  
   418  	err := dc.ci.Close()
   419  	dc.ci = nil
   420  	dc.finalClosed = true
   421  	dc.Unlock()
   422  
   423  	dc.db.mu.Lock()
   424  	dc.db.numOpen--
   425  	dc.db.maybeOpenNewConnections()
   426  	dc.db.mu.Unlock()
   427  
   428  	atomic.AddUint64(&dc.db.numClosed, 1)
   429  	return err
   430  }
   431  
   432  // driverStmt associates a driver.Stmt with the
   433  // *driverConn from which it came, so the driverConn's lock can be
   434  // held during calls.
   435  type driverStmt struct {
   436  	sync.Locker // the *driverConn
   437  	si          driver.Stmt
   438  }
   439  
   440  func (ds *driverStmt) Close() error {
   441  	ds.Lock()
   442  	defer ds.Unlock()
   443  	return ds.si.Close()
   444  }
   445  
   446  // depSet is a finalCloser's outstanding dependencies
   447  type depSet map[interface{}]bool // set of true bools
   448  
   449  // The finalCloser interface is used by (*DB).addDep and related
   450  // dependency reference counting.
   451  type finalCloser interface {
   452  	// finalClose is called when the reference count of an object
   453  	// goes to zero. (*DB).mu is not held while calling it.
   454  	finalClose() error
   455  }
   456  
   457  // addDep notes that x now depends on dep, and x's finalClose won't be
   458  // called until all of x's dependencies are removed with removeDep.
   459  func (db *DB) addDep(x finalCloser, dep interface{}) {
   460  	//println(fmt.Sprintf("addDep(%T %p, %T %p)", x, x, dep, dep))
   461  	db.mu.Lock()
   462  	defer db.mu.Unlock()
   463  	db.addDepLocked(x, dep)
   464  }
   465  
   466  func (db *DB) addDepLocked(x finalCloser, dep interface{}) {
   467  	if db.dep == nil {
   468  		db.dep = make(map[finalCloser]depSet)
   469  	}
   470  	xdep := db.dep[x]
   471  	if xdep == nil {
   472  		xdep = make(depSet)
   473  		db.dep[x] = xdep
   474  	}
   475  	xdep[dep] = true
   476  }
   477  
   478  // removeDep notes that x no longer depends on dep.
   479  // If x still has dependencies, nil is returned.
   480  // If x no longer has any dependencies, its finalClose method will be
   481  // called and its error value will be returned.
   482  func (db *DB) removeDep(x finalCloser, dep interface{}) error {
   483  	db.mu.Lock()
   484  	fn := db.removeDepLocked(x, dep)
   485  	db.mu.Unlock()
   486  	return fn()
   487  }
   488  
   489  func (db *DB) removeDepLocked(x finalCloser, dep interface{}) func() error {
   490  	//println(fmt.Sprintf("removeDep(%T %p, %T %p)", x, x, dep, dep))
   491  
   492  	xdep, ok := db.dep[x]
   493  	if !ok {
   494  		panic(fmt.Sprintf("unpaired removeDep: no deps for %T", x))
   495  	}
   496  
   497  	l0 := len(xdep)
   498  	delete(xdep, dep)
   499  
   500  	switch len(xdep) {
   501  	case l0:
   502  		// Nothing removed. Shouldn't happen.
   503  		panic(fmt.Sprintf("unpaired removeDep: no %T dep on %T", dep, x))
   504  	case 0:
   505  		// No more dependencies.
   506  		delete(db.dep, x)
   507  		return x.finalClose
   508  	default:
   509  		// Dependencies remain.
   510  		return func() error { return nil }
   511  	}
   512  }
   513  
   514  // This is the size of the connectionOpener request chan (DB.openerCh).
   515  // This value should be larger than the maximum typical value
   516  // used for db.maxOpen. If maxOpen is significantly larger than
   517  // connectionRequestQueueSize then it is possible for ALL calls into the *DB
   518  // to block until the connectionOpener can satisfy the backlog of requests.
   519  var connectionRequestQueueSize = 1000000
   520  
   521  // Open opens a database specified by its database driver name and a
   522  // driver-specific data source name, usually consisting of at least a
   523  // database name and connection information.
   524  //
   525  // Most users will open a database via a driver-specific connection
   526  // helper function that returns a *DB. No database drivers are included
   527  // in the Go standard library. See https://golang.org/s/sqldrivers for
   528  // a list of third-party drivers.
   529  //
   530  // Open may just validate its arguments without creating a connection
   531  // to the database. To verify that the data source name is valid, call
   532  // Ping.
   533  //
   534  // The returned DB is safe for concurrent use by multiple goroutines
   535  // and maintains its own pool of idle connections. Thus, the Open
   536  // function should be called just once. It is rarely necessary to
   537  // close a DB.
   538  func Open(driverName, dataSourceName string) (*DB, error) {
   539  	driversMu.RLock()
   540  	driveri, ok := drivers[driverName]
   541  	driversMu.RUnlock()
   542  	if !ok {
   543  		return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName)
   544  	}
   545  	db := &DB{
   546  		driver:   driveri,
   547  		dsn:      dataSourceName,
   548  		openerCh: make(chan struct{}, connectionRequestQueueSize),
   549  		lastPut:  make(map[*driverConn]string),
   550  	}
   551  	go db.connectionOpener()
   552  	return db, nil
   553  }
   554  
   555  // PingContext verifies a connection to the database is still alive,
   556  // establishing a connection if necessary.
   557  func (db *DB) PingContext(ctx context.Context) error {
   558  	var dc *driverConn
   559  	var err error
   560  
   561  	for i := 0; i < maxBadConnRetries; i++ {
   562  		dc, err = db.conn(ctx, cachedOrNewConn)
   563  		if err != driver.ErrBadConn {
   564  			break
   565  		}
   566  	}
   567  	if err == driver.ErrBadConn {
   568  		dc, err = db.conn(ctx, alwaysNewConn)
   569  	}
   570  	if err != nil {
   571  		return err
   572  	}
   573  
   574  	if pinger, ok := dc.ci.(driver.Pinger); ok {
   575  		err = pinger.Ping(ctx)
   576  	}
   577  	db.putConn(dc, err)
   578  	return err
   579  }
   580  
   581  // Ping verifies a connection to the database is still alive,
   582  // establishing a connection if necessary.
   583  func (db *DB) Ping() error {
   584  	return db.PingContext(context.Background())
   585  }
   586  
   587  // Close closes the database, releasing any open resources.
   588  //
   589  // It is rare to Close a DB, as the DB handle is meant to be
   590  // long-lived and shared between many goroutines.
   591  func (db *DB) Close() error {
   592  	db.mu.Lock()
   593  	if db.closed { // Make DB.Close idempotent
   594  		db.mu.Unlock()
   595  		return nil
   596  	}
   597  	close(db.openerCh)
   598  	if db.cleanerCh != nil {
   599  		close(db.cleanerCh)
   600  	}
   601  	var err error
   602  	fns := make([]func() error, 0, len(db.freeConn))
   603  	for _, dc := range db.freeConn {
   604  		fns = append(fns, dc.closeDBLocked())
   605  	}
   606  	db.freeConn = nil
   607  	db.closed = true
   608  	for _, req := range db.connRequests {
   609  		close(req)
   610  	}
   611  	db.mu.Unlock()
   612  	for _, fn := range fns {
   613  		err1 := fn()
   614  		if err1 != nil {
   615  			err = err1
   616  		}
   617  	}
   618  	return err
   619  }
   620  
   621  const defaultMaxIdleConns = 2
   622  
   623  func (db *DB) maxIdleConnsLocked() int {
   624  	n := db.maxIdle
   625  	switch {
   626  	case n == 0:
   627  		// TODO(bradfitz): ask driver, if supported, for its default preference
   628  		return defaultMaxIdleConns
   629  	case n < 0:
   630  		return 0
   631  	default:
   632  		return n
   633  	}
   634  }
   635  
   636  // SetMaxIdleConns sets the maximum number of connections in the idle
   637  // connection pool.
   638  //
   639  // If MaxOpenConns is greater than 0 but less than the new MaxIdleConns
   640  // then the new MaxIdleConns will be reduced to match the MaxOpenConns limit
   641  //
   642  // If n <= 0, no idle connections are retained.
   643  func (db *DB) SetMaxIdleConns(n int) {
   644  	db.mu.Lock()
   645  	if n > 0 {
   646  		db.maxIdle = n
   647  	} else {
   648  		// No idle connections.
   649  		db.maxIdle = -1
   650  	}
   651  	// Make sure maxIdle doesn't exceed maxOpen
   652  	if db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen {
   653  		db.maxIdle = db.maxOpen
   654  	}
   655  	var closing []*driverConn
   656  	idleCount := len(db.freeConn)
   657  	maxIdle := db.maxIdleConnsLocked()
   658  	if idleCount > maxIdle {
   659  		closing = db.freeConn[maxIdle:]
   660  		db.freeConn = db.freeConn[:maxIdle]
   661  	}
   662  	db.mu.Unlock()
   663  	for _, c := range closing {
   664  		c.Close()
   665  	}
   666  }
   667  
   668  // SetMaxOpenConns sets the maximum number of open connections to the database.
   669  //
   670  // If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than
   671  // MaxIdleConns, then MaxIdleConns will be reduced to match the new
   672  // MaxOpenConns limit
   673  //
   674  // If n <= 0, then there is no limit on the number of open connections.
   675  // The default is 0 (unlimited).
   676  func (db *DB) SetMaxOpenConns(n int) {
   677  	db.mu.Lock()
   678  	db.maxOpen = n
   679  	if n < 0 {
   680  		db.maxOpen = 0
   681  	}
   682  	syncMaxIdle := db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen
   683  	db.mu.Unlock()
   684  	if syncMaxIdle {
   685  		db.SetMaxIdleConns(n)
   686  	}
   687  }
   688  
   689  // SetConnMaxLifetime sets the maximum amount of time a connection may be reused.
   690  //
   691  // Expired connections may be closed lazily before reuse.
   692  //
   693  // If d <= 0, connections are reused forever.
   694  func (db *DB) SetConnMaxLifetime(d time.Duration) {
   695  	if d < 0 {
   696  		d = 0
   697  	}
   698  	db.mu.Lock()
   699  	// wake cleaner up when lifetime is shortened.
   700  	if d > 0 && d < db.maxLifetime && db.cleanerCh != nil {
   701  		select {
   702  		case db.cleanerCh <- struct{}{}:
   703  		default:
   704  		}
   705  	}
   706  	db.maxLifetime = d
   707  	db.startCleanerLocked()
   708  	db.mu.Unlock()
   709  }
   710  
   711  // startCleanerLocked starts connectionCleaner if needed.
   712  func (db *DB) startCleanerLocked() {
   713  	if db.maxLifetime > 0 && db.numOpen > 0 && db.cleanerCh == nil {
   714  		db.cleanerCh = make(chan struct{}, 1)
   715  		go db.connectionCleaner(db.maxLifetime)
   716  	}
   717  }
   718  
   719  func (db *DB) connectionCleaner(d time.Duration) {
   720  	const minInterval = time.Second
   721  
   722  	if d < minInterval {
   723  		d = minInterval
   724  	}
   725  	t := time.NewTimer(d)
   726  
   727  	for {
   728  		select {
   729  		case <-t.C:
   730  		case <-db.cleanerCh: // maxLifetime was changed or db was closed.
   731  		}
   732  
   733  		db.mu.Lock()
   734  		d = db.maxLifetime
   735  		if db.closed || db.numOpen == 0 || d <= 0 {
   736  			db.cleanerCh = nil
   737  			db.mu.Unlock()
   738  			return
   739  		}
   740  
   741  		expiredSince := nowFunc().Add(-d)
   742  		var closing []*driverConn
   743  		for i := 0; i < len(db.freeConn); i++ {
   744  			c := db.freeConn[i]
   745  			if c.createdAt.Before(expiredSince) {
   746  				closing = append(closing, c)
   747  				last := len(db.freeConn) - 1
   748  				db.freeConn[i] = db.freeConn[last]
   749  				db.freeConn[last] = nil
   750  				db.freeConn = db.freeConn[:last]
   751  				i--
   752  			}
   753  		}
   754  		db.mu.Unlock()
   755  
   756  		for _, c := range closing {
   757  			c.Close()
   758  		}
   759  
   760  		if d < minInterval {
   761  			d = minInterval
   762  		}
   763  		t.Reset(d)
   764  	}
   765  }
   766  
   767  // DBStats contains database statistics.
   768  type DBStats struct {
   769  	// OpenConnections is the number of open connections to the database.
   770  	OpenConnections int
   771  }
   772  
   773  // Stats returns database statistics.
   774  func (db *DB) Stats() DBStats {
   775  	db.mu.Lock()
   776  	stats := DBStats{
   777  		OpenConnections: db.numOpen,
   778  	}
   779  	db.mu.Unlock()
   780  	return stats
   781  }
   782  
   783  // Assumes db.mu is locked.
   784  // If there are connRequests and the connection limit hasn't been reached,
   785  // then tell the connectionOpener to open new connections.
   786  func (db *DB) maybeOpenNewConnections() {
   787  	numRequests := len(db.connRequests)
   788  	if db.maxOpen > 0 {
   789  		numCanOpen := db.maxOpen - db.numOpen
   790  		if numRequests > numCanOpen {
   791  			numRequests = numCanOpen
   792  		}
   793  	}
   794  	for numRequests > 0 {
   795  		db.numOpen++ // optimistically
   796  		numRequests--
   797  		if db.closed {
   798  			return
   799  		}
   800  		db.openerCh <- struct{}{}
   801  	}
   802  }
   803  
   804  // Runs in a separate goroutine, opens new connections when requested.
   805  func (db *DB) connectionOpener() {
   806  	for range db.openerCh {
   807  		db.openNewConnection()
   808  	}
   809  }
   810  
   811  // Open one new connection
   812  func (db *DB) openNewConnection() {
   813  	// maybeOpenNewConnctions has already executed db.numOpen++ before it sent
   814  	// on db.openerCh. This function must execute db.numOpen-- if the
   815  	// connection fails or is closed before returning.
   816  	ci, err := db.driver.Open(db.dsn)
   817  	db.mu.Lock()
   818  	defer db.mu.Unlock()
   819  	if db.closed {
   820  		if err == nil {
   821  			ci.Close()
   822  		}
   823  		db.numOpen--
   824  		return
   825  	}
   826  	if err != nil {
   827  		db.numOpen--
   828  		db.putConnDBLocked(nil, err)
   829  		db.maybeOpenNewConnections()
   830  		return
   831  	}
   832  	dc := &driverConn{
   833  		db:        db,
   834  		createdAt: nowFunc(),
   835  		ci:        ci,
   836  	}
   837  	if db.putConnDBLocked(dc, err) {
   838  		db.addDepLocked(dc, dc)
   839  	} else {
   840  		db.numOpen--
   841  		ci.Close()
   842  	}
   843  }
   844  
   845  // connRequest represents one request for a new connection
   846  // When there are no idle connections available, DB.conn will create
   847  // a new connRequest and put it on the db.connRequests list.
   848  type connRequest struct {
   849  	conn *driverConn
   850  	err  error
   851  }
   852  
   853  var errDBClosed = errors.New("sql: database is closed")
   854  
   855  // conn returns a newly-opened or cached *driverConn.
   856  func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) {
   857  	db.mu.Lock()
   858  	if db.closed {
   859  		db.mu.Unlock()
   860  		return nil, errDBClosed
   861  	}
   862  	// Check if the context is expired.
   863  	if err := ctx.Err(); err != nil {
   864  		db.mu.Unlock()
   865  		return nil, err
   866  	}
   867  	lifetime := db.maxLifetime
   868  
   869  	// Prefer a free connection, if possible.
   870  	numFree := len(db.freeConn)
   871  	if strategy == cachedOrNewConn && numFree > 0 {
   872  		conn := db.freeConn[0]
   873  		copy(db.freeConn, db.freeConn[1:])
   874  		db.freeConn = db.freeConn[:numFree-1]
   875  		conn.inUse = true
   876  		db.mu.Unlock()
   877  		if conn.expired(lifetime) {
   878  			conn.Close()
   879  			return nil, driver.ErrBadConn
   880  		}
   881  		return conn, nil
   882  	}
   883  
   884  	// Out of free connections or we were asked not to use one. If we're not
   885  	// allowed to open any more connections, make a request and wait.
   886  	if db.maxOpen > 0 && db.numOpen >= db.maxOpen {
   887  		// Make the connRequest channel. It's buffered so that the
   888  		// connectionOpener doesn't block while waiting for the req to be read.
   889  		req := make(chan connRequest, 1)
   890  		db.connRequests = append(db.connRequests, req)
   891  		db.mu.Unlock()
   892  
   893  		// Timeout the connection request with the context.
   894  		select {
   895  		case <-ctx.Done():
   896  			return nil, ctx.Err()
   897  		case ret, ok := <-req:
   898  			if !ok {
   899  				return nil, errDBClosed
   900  			}
   901  			if ret.err == nil && ret.conn.expired(lifetime) {
   902  				ret.conn.Close()
   903  				return nil, driver.ErrBadConn
   904  			}
   905  			return ret.conn, ret.err
   906  		}
   907  	}
   908  
   909  	db.numOpen++ // optimistically
   910  	db.mu.Unlock()
   911  	ci, err := db.driver.Open(db.dsn)
   912  	if err != nil {
   913  		db.mu.Lock()
   914  		db.numOpen-- // correct for earlier optimism
   915  		db.maybeOpenNewConnections()
   916  		db.mu.Unlock()
   917  		return nil, err
   918  	}
   919  	db.mu.Lock()
   920  	dc := &driverConn{
   921  		db:        db,
   922  		createdAt: nowFunc(),
   923  		ci:        ci,
   924  	}
   925  	db.addDepLocked(dc, dc)
   926  	dc.inUse = true
   927  	db.mu.Unlock()
   928  	return dc, nil
   929  }
   930  
   931  // putConnHook is a hook for testing.
   932  var putConnHook func(*DB, *driverConn)
   933  
   934  // noteUnusedDriverStatement notes that si is no longer used and should
   935  // be closed whenever possible (when c is next not in use), unless c is
   936  // already closed.
   937  func (db *DB) noteUnusedDriverStatement(c *driverConn, si driver.Stmt) {
   938  	db.mu.Lock()
   939  	defer db.mu.Unlock()
   940  	if c.inUse {
   941  		c.onPut = append(c.onPut, func() {
   942  			si.Close()
   943  		})
   944  	} else {
   945  		c.Lock()
   946  		defer c.Unlock()
   947  		if !c.finalClosed {
   948  			si.Close()
   949  		}
   950  	}
   951  }
   952  
   953  // debugGetPut determines whether getConn & putConn calls' stack traces
   954  // are returned for more verbose crashes.
   955  const debugGetPut = false
   956  
   957  // putConn adds a connection to the db's free pool.
   958  // err is optionally the last error that occurred on this connection.
   959  func (db *DB) putConn(dc *driverConn, err error) {
   960  	db.mu.Lock()
   961  	if !dc.inUse {
   962  		if debugGetPut {
   963  			fmt.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc, stack(), db.lastPut[dc])
   964  		}
   965  		panic("sql: connection returned that was never out")
   966  	}
   967  	if debugGetPut {
   968  		db.lastPut[dc] = stack()
   969  	}
   970  	dc.inUse = false
   971  
   972  	for _, fn := range dc.onPut {
   973  		fn()
   974  	}
   975  	dc.onPut = nil
   976  
   977  	if err == driver.ErrBadConn {
   978  		// Don't reuse bad connections.
   979  		// Since the conn is considered bad and is being discarded, treat it
   980  		// as closed. Don't decrement the open count here, finalClose will
   981  		// take care of that.
   982  		db.maybeOpenNewConnections()
   983  		db.mu.Unlock()
   984  		dc.Close()
   985  		return
   986  	}
   987  	if putConnHook != nil {
   988  		putConnHook(db, dc)
   989  	}
   990  	added := db.putConnDBLocked(dc, nil)
   991  	db.mu.Unlock()
   992  
   993  	if !added {
   994  		dc.Close()
   995  	}
   996  }
   997  
   998  // Satisfy a connRequest or put the driverConn in the idle pool and return true
   999  // or return false.
  1000  // putConnDBLocked will satisfy a connRequest if there is one, or it will
  1001  // return the *driverConn to the freeConn list if err == nil and the idle
  1002  // connection limit will not be exceeded.
  1003  // If err != nil, the value of dc is ignored.
  1004  // If err == nil, then dc must not equal nil.
  1005  // If a connRequest was fulfilled or the *driverConn was placed in the
  1006  // freeConn list, then true is returned, otherwise false is returned.
  1007  func (db *DB) putConnDBLocked(dc *driverConn, err error) bool {
  1008  	if db.closed {
  1009  		return false
  1010  	}
  1011  	if db.maxOpen > 0 && db.numOpen > db.maxOpen {
  1012  		return false
  1013  	}
  1014  	if c := len(db.connRequests); c > 0 {
  1015  		req := db.connRequests[0]
  1016  		// This copy is O(n) but in practice faster than a linked list.
  1017  		// TODO: consider compacting it down less often and
  1018  		// moving the base instead?
  1019  		copy(db.connRequests, db.connRequests[1:])
  1020  		db.connRequests = db.connRequests[:c-1]
  1021  		if err == nil {
  1022  			dc.inUse = true
  1023  		}
  1024  		req <- connRequest{
  1025  			conn: dc,
  1026  			err:  err,
  1027  		}
  1028  		return true
  1029  	} else if err == nil && !db.closed && db.maxIdleConnsLocked() > len(db.freeConn) {
  1030  		db.freeConn = append(db.freeConn, dc)
  1031  		db.startCleanerLocked()
  1032  		return true
  1033  	}
  1034  	return false
  1035  }
  1036  
  1037  // maxBadConnRetries is the number of maximum retries if the driver returns
  1038  // driver.ErrBadConn to signal a broken connection before forcing a new
  1039  // connection to be opened.
  1040  const maxBadConnRetries = 2
  1041  
  1042  // PrepareContext creates a prepared statement for later queries or executions.
  1043  // Multiple queries or executions may be run concurrently from the
  1044  // returned statement.
  1045  // The caller must call the statement's Close method
  1046  // when the statement is no longer needed.
  1047  //
  1048  // The provided context is used for the preparation of the statement, not for the
  1049  // execution of the statement.
  1050  func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
  1051  	var stmt *Stmt
  1052  	var err error
  1053  	for i := 0; i < maxBadConnRetries; i++ {
  1054  		stmt, err = db.prepare(ctx, query, cachedOrNewConn)
  1055  		if err != driver.ErrBadConn {
  1056  			break
  1057  		}
  1058  	}
  1059  	if err == driver.ErrBadConn {
  1060  		return db.prepare(ctx, query, alwaysNewConn)
  1061  	}
  1062  	return stmt, err
  1063  }
  1064  
  1065  // Prepare creates a prepared statement for later queries or executions.
  1066  // Multiple queries or executions may be run concurrently from the
  1067  // returned statement.
  1068  // The caller must call the statement's Close method
  1069  // when the statement is no longer needed.
  1070  func (db *DB) Prepare(query string) (*Stmt, error) {
  1071  	return db.PrepareContext(context.Background(), query)
  1072  }
  1073  
  1074  func (db *DB) prepare(ctx context.Context, query string, strategy connReuseStrategy) (*Stmt, error) {
  1075  	// TODO: check if db.driver supports an optional
  1076  	// driver.Preparer interface and call that instead, if so,
  1077  	// otherwise we make a prepared statement that's bound
  1078  	// to a connection, and to execute this prepared statement
  1079  	// we either need to use this connection (if it's free), else
  1080  	// get a new connection + re-prepare + execute on that one.
  1081  	dc, err := db.conn(ctx, strategy)
  1082  	if err != nil {
  1083  		return nil, err
  1084  	}
  1085  	var si driver.Stmt
  1086  	withLock(dc, func() {
  1087  		si, err = dc.prepareLocked(ctx, query)
  1088  	})
  1089  	if err != nil {
  1090  		db.putConn(dc, err)
  1091  		return nil, err
  1092  	}
  1093  	stmt := &Stmt{
  1094  		db:            db,
  1095  		query:         query,
  1096  		css:           []connStmt{{dc, si}},
  1097  		lastNumClosed: atomic.LoadUint64(&db.numClosed),
  1098  	}
  1099  	db.addDep(stmt, stmt)
  1100  	db.putConn(dc, nil)
  1101  	return stmt, nil
  1102  }
  1103  
  1104  // ExecContext executes a query without returning any rows.
  1105  // The args are for any placeholder parameters in the query.
  1106  func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error) {
  1107  	var res Result
  1108  	var err error
  1109  	for i := 0; i < maxBadConnRetries; i++ {
  1110  		res, err = db.exec(ctx, query, args, cachedOrNewConn)
  1111  		if err != driver.ErrBadConn {
  1112  			break
  1113  		}
  1114  	}
  1115  	if err == driver.ErrBadConn {
  1116  		return db.exec(ctx, query, args, alwaysNewConn)
  1117  	}
  1118  	return res, err
  1119  }
  1120  
  1121  // Exec executes a query without returning any rows.
  1122  // The args are for any placeholder parameters in the query.
  1123  func (db *DB) Exec(query string, args ...interface{}) (Result, error) {
  1124  	return db.ExecContext(context.Background(), query, args...)
  1125  }
  1126  
  1127  func (db *DB) exec(ctx context.Context, query string, args []interface{}, strategy connReuseStrategy) (res Result, err error) {
  1128  	dc, err := db.conn(ctx, strategy)
  1129  	if err != nil {
  1130  		return nil, err
  1131  	}
  1132  	defer func() {
  1133  		db.putConn(dc, err)
  1134  	}()
  1135  
  1136  	if execer, ok := dc.ci.(driver.Execer); ok {
  1137  		var dargs []driver.NamedValue
  1138  		dargs, err = driverArgs(nil, args)
  1139  		if err != nil {
  1140  			return nil, err
  1141  		}
  1142  		var resi driver.Result
  1143  		withLock(dc, func() {
  1144  			resi, err = ctxDriverExec(ctx, execer, query, dargs)
  1145  		})
  1146  		if err != driver.ErrSkip {
  1147  			if err != nil {
  1148  				return nil, err
  1149  			}
  1150  			return driverResult{dc, resi}, nil
  1151  		}
  1152  	}
  1153  
  1154  	var si driver.Stmt
  1155  	withLock(dc, func() {
  1156  		si, err = ctxDriverPrepare(ctx, dc.ci, query)
  1157  	})
  1158  	if err != nil {
  1159  		return nil, err
  1160  	}
  1161  	defer withLock(dc, func() { si.Close() })
  1162  	return resultFromStatement(ctx, driverStmt{dc, si}, args...)
  1163  }
  1164  
  1165  // QueryContext executes a query that returns rows, typically a SELECT.
  1166  // The args are for any placeholder parameters in the query.
  1167  func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
  1168  	var rows *Rows
  1169  	var err error
  1170  	for i := 0; i < maxBadConnRetries; i++ {
  1171  		rows, err = db.query(ctx, query, args, cachedOrNewConn)
  1172  		if err != driver.ErrBadConn {
  1173  			break
  1174  		}
  1175  	}
  1176  	if err == driver.ErrBadConn {
  1177  		return db.query(ctx, query, args, alwaysNewConn)
  1178  	}
  1179  	return rows, err
  1180  }
  1181  
  1182  // Query executes a query that returns rows, typically a SELECT.
  1183  // The args are for any placeholder parameters in the query.
  1184  func (db *DB) Query(query string, args ...interface{}) (*Rows, error) {
  1185  	return db.QueryContext(context.Background(), query, args...)
  1186  }
  1187  
  1188  func (db *DB) query(ctx context.Context, query string, args []interface{}, strategy connReuseStrategy) (*Rows, error) {
  1189  	ci, err := db.conn(ctx, strategy)
  1190  	if err != nil {
  1191  		return nil, err
  1192  	}
  1193  
  1194  	return db.queryConn(ctx, ci, ci.releaseConn, query, args)
  1195  }
  1196  
  1197  // queryConn executes a query on the given connection.
  1198  // The connection gets released by the releaseConn function.
  1199  func (db *DB) queryConn(ctx context.Context, dc *driverConn, releaseConn func(error), query string, args []interface{}) (*Rows, error) {
  1200  	if queryer, ok := dc.ci.(driver.Queryer); ok {
  1201  		dargs, err := driverArgs(nil, args)
  1202  		if err != nil {
  1203  			releaseConn(err)
  1204  			return nil, err
  1205  		}
  1206  		var rowsi driver.Rows
  1207  		withLock(dc, func() {
  1208  			rowsi, err = ctxDriverQuery(ctx, queryer, query, dargs)
  1209  		})
  1210  		if err != driver.ErrSkip {
  1211  			if err != nil {
  1212  				releaseConn(err)
  1213  				return nil, err
  1214  			}
  1215  			// Note: ownership of dc passes to the *Rows, to be freed
  1216  			// with releaseConn.
  1217  			rows := &Rows{
  1218  				dc:          dc,
  1219  				releaseConn: releaseConn,
  1220  				rowsi:       rowsi,
  1221  			}
  1222  			rows.initContextClose(ctx)
  1223  			return rows, nil
  1224  		}
  1225  	}
  1226  
  1227  	var si driver.Stmt
  1228  	var err error
  1229  	withLock(dc, func() {
  1230  		si, err = ctxDriverPrepare(ctx, dc.ci, query)
  1231  	})
  1232  	if err != nil {
  1233  		releaseConn(err)
  1234  		return nil, err
  1235  	}
  1236  
  1237  	ds := driverStmt{dc, si}
  1238  	rowsi, err := rowsiFromStatement(ctx, ds, args...)
  1239  	if err != nil {
  1240  		withLock(dc, func() {
  1241  			si.Close()
  1242  		})
  1243  		releaseConn(err)
  1244  		return nil, err
  1245  	}
  1246  
  1247  	// Note: ownership of ci passes to the *Rows, to be freed
  1248  	// with releaseConn.
  1249  	rows := &Rows{
  1250  		dc:          dc,
  1251  		releaseConn: releaseConn,
  1252  		rowsi:       rowsi,
  1253  		closeStmt:   si,
  1254  	}
  1255  	rows.initContextClose(ctx)
  1256  	return rows, nil
  1257  }
  1258  
  1259  // QueryRowContext executes a query that is expected to return at most one row.
  1260  // QueryRowContext always returns a non-nil value. Errors are deferred until
  1261  // Row's Scan method is called.
  1262  func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
  1263  	rows, err := db.QueryContext(ctx, query, args...)
  1264  	return &Row{rows: rows, err: err}
  1265  }
  1266  
  1267  // QueryRow executes a query that is expected to return at most one row.
  1268  // QueryRow always returns a non-nil value. Errors are deferred until
  1269  // Row's Scan method is called.
  1270  func (db *DB) QueryRow(query string, args ...interface{}) *Row {
  1271  	return db.QueryRowContext(context.Background(), query, args...)
  1272  }
  1273  
  1274  // BeginContext starts a transaction.
  1275  //
  1276  // An isolation level may be set by setting the value in the context
  1277  // before calling this. If a non-default isolation level is used
  1278  // that the driver doesn't support an error will be returned. Different drivers
  1279  // may have slightly different meanings for the same isolation level.
  1280  func (db *DB) BeginContext(ctx context.Context) (*Tx, error) {
  1281  	var tx *Tx
  1282  	var err error
  1283  	for i := 0; i < maxBadConnRetries; i++ {
  1284  		tx, err = db.begin(ctx, cachedOrNewConn)
  1285  		if err != driver.ErrBadConn {
  1286  			break
  1287  		}
  1288  	}
  1289  	if err == driver.ErrBadConn {
  1290  		return db.begin(ctx, alwaysNewConn)
  1291  	}
  1292  	return tx, err
  1293  }
  1294  
  1295  // Begin starts a transaction. The default isolation level is dependent on
  1296  // the driver.
  1297  func (db *DB) Begin() (*Tx, error) {
  1298  	return db.BeginContext(context.Background())
  1299  }
  1300  
  1301  func (db *DB) begin(ctx context.Context, strategy connReuseStrategy) (tx *Tx, err error) {
  1302  	dc, err := db.conn(ctx, strategy)
  1303  	if err != nil {
  1304  		return nil, err
  1305  	}
  1306  	var txi driver.Tx
  1307  	withLock(dc, func() {
  1308  		txi, err = ctxDriverBegin(ctx, dc.ci)
  1309  	})
  1310  	if err != nil {
  1311  		db.putConn(dc, err)
  1312  		return nil, err
  1313  	}
  1314  
  1315  	// Schedule the transaction to rollback when the context is cancelled.
  1316  	// The cancel function in Tx will be called after done is set to true.
  1317  	ctx, cancel := context.WithCancel(ctx)
  1318  	tx = &Tx{
  1319  		db:     db,
  1320  		dc:     dc,
  1321  		txi:    txi,
  1322  		cancel: cancel,
  1323  	}
  1324  	go func() {
  1325  		select {
  1326  		case <-ctx.Done():
  1327  			if !tx.done {
  1328  				tx.Rollback()
  1329  			}
  1330  		}
  1331  	}()
  1332  	return tx, nil
  1333  }
  1334  
  1335  // Driver returns the database's underlying driver.
  1336  func (db *DB) Driver() driver.Driver {
  1337  	return db.driver
  1338  }
  1339  
  1340  // Tx is an in-progress database transaction.
  1341  //
  1342  // A transaction must end with a call to Commit or Rollback.
  1343  //
  1344  // After a call to Commit or Rollback, all operations on the
  1345  // transaction fail with ErrTxDone.
  1346  //
  1347  // The statements prepared for a transaction by calling
  1348  // the transaction's Prepare or Stmt methods are closed
  1349  // by the call to Commit or Rollback.
  1350  type Tx struct {
  1351  	db *DB
  1352  
  1353  	// dc is owned exclusively until Commit or Rollback, at which point
  1354  	// it's returned with putConn.
  1355  	dc  *driverConn
  1356  	txi driver.Tx
  1357  
  1358  	// done transitions from false to true exactly once, on Commit
  1359  	// or Rollback. once done, all operations fail with
  1360  	// ErrTxDone.
  1361  	done bool
  1362  
  1363  	// All Stmts prepared for this transaction. These will be closed after the
  1364  	// transaction has been committed or rolled back.
  1365  	stmts struct {
  1366  		sync.Mutex
  1367  		v []*Stmt
  1368  	}
  1369  
  1370  	// cancel is called after done transitions from false to true.
  1371  	cancel func()
  1372  }
  1373  
  1374  // ErrTxDone is returned by any operation that is performed on a transaction
  1375  // that has already been committed or rolled back.
  1376  var ErrTxDone = errors.New("sql: Transaction has already been committed or rolled back")
  1377  
  1378  func (tx *Tx) close(err error) {
  1379  	if tx.done {
  1380  		panic("double close") // internal error
  1381  	}
  1382  	tx.done = true
  1383  	tx.db.putConn(tx.dc, err)
  1384  	tx.cancel()
  1385  	tx.dc = nil
  1386  	tx.txi = nil
  1387  }
  1388  
  1389  func (tx *Tx) grabConn(ctx context.Context) (*driverConn, error) {
  1390  	if tx.done {
  1391  		return nil, ErrTxDone
  1392  	}
  1393  	return tx.dc, nil
  1394  }
  1395  
  1396  // Closes all Stmts prepared for this transaction.
  1397  func (tx *Tx) closePrepared() {
  1398  	tx.stmts.Lock()
  1399  	defer tx.stmts.Unlock()
  1400  	for _, stmt := range tx.stmts.v {
  1401  		stmt.Close()
  1402  	}
  1403  }
  1404  
  1405  // Commit commits the transaction.
  1406  func (tx *Tx) Commit() error {
  1407  	if tx.done {
  1408  		return ErrTxDone
  1409  	}
  1410  	var err error
  1411  	withLock(tx.dc, func() {
  1412  		err = tx.txi.Commit()
  1413  	})
  1414  	if err != driver.ErrBadConn {
  1415  		tx.closePrepared()
  1416  	}
  1417  	tx.close(err)
  1418  	return err
  1419  }
  1420  
  1421  // Rollback aborts the transaction.
  1422  func (tx *Tx) Rollback() error {
  1423  	if tx.done {
  1424  		return ErrTxDone
  1425  	}
  1426  	var err error
  1427  	withLock(tx.dc, func() {
  1428  		err = tx.txi.Rollback()
  1429  	})
  1430  	if err != driver.ErrBadConn {
  1431  		tx.closePrepared()
  1432  	}
  1433  	tx.close(err)
  1434  	return err
  1435  }
  1436  
  1437  // Prepare creates a prepared statement for use within a transaction.
  1438  //
  1439  // The returned statement operates within the transaction and can no longer
  1440  // be used once the transaction has been committed or rolled back.
  1441  //
  1442  // To use an existing prepared statement on this transaction, see Tx.Stmt.
  1443  //
  1444  // The provided context will be used for the preparation of the context, not
  1445  // for the execution of the returned statement. The returned statement
  1446  // will run in the transaction context.
  1447  func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
  1448  	// TODO(bradfitz): We could be more efficient here and either
  1449  	// provide a method to take an existing Stmt (created on
  1450  	// perhaps a different Conn), and re-create it on this Conn if
  1451  	// necessary. Or, better: keep a map in DB of query string to
  1452  	// Stmts, and have Stmt.Execute do the right thing and
  1453  	// re-prepare if the Conn in use doesn't have that prepared
  1454  	// statement. But we'll want to avoid caching the statement
  1455  	// in the case where we only call conn.Prepare implicitly
  1456  	// (such as in db.Exec or tx.Exec), but the caller package
  1457  	// can't be holding a reference to the returned statement.
  1458  	// Perhaps just looking at the reference count (by noting
  1459  	// Stmt.Close) would be enough. We might also want a finalizer
  1460  	// on Stmt to drop the reference count.
  1461  	dc, err := tx.grabConn(ctx)
  1462  	if err != nil {
  1463  		return nil, err
  1464  	}
  1465  
  1466  	var si driver.Stmt
  1467  	withLock(dc, func() {
  1468  		si, err = dc.ci.Prepare(query)
  1469  	})
  1470  	if err != nil {
  1471  		return nil, err
  1472  	}
  1473  
  1474  	stmt := &Stmt{
  1475  		db: tx.db,
  1476  		tx: tx,
  1477  		txsi: &driverStmt{
  1478  			Locker: dc,
  1479  			si:     si,
  1480  		},
  1481  		query: query,
  1482  	}
  1483  	tx.stmts.Lock()
  1484  	tx.stmts.v = append(tx.stmts.v, stmt)
  1485  	tx.stmts.Unlock()
  1486  	return stmt, nil
  1487  }
  1488  
  1489  // Prepare creates a prepared statement for use within a transaction.
  1490  //
  1491  // The returned statement operates within the transaction and can no longer
  1492  // be used once the transaction has been committed or rolled back.
  1493  //
  1494  // To use an existing prepared statement on this transaction, see Tx.Stmt.
  1495  func (tx *Tx) Prepare(query string) (*Stmt, error) {
  1496  	return tx.PrepareContext(context.Background(), query)
  1497  }
  1498  
  1499  // StmtContext returns a transaction-specific prepared statement from
  1500  // an existing statement.
  1501  //
  1502  // Example:
  1503  //  updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
  1504  //  ...
  1505  //  tx, err := db.Begin()
  1506  //  ...
  1507  //  res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)
  1508  //
  1509  // The returned statement operates within the transaction and can no longer
  1510  // be used once the transaction has been committed or rolled back.
  1511  func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt {
  1512  	// TODO(bradfitz): optimize this. Currently this re-prepares
  1513  	// each time. This is fine for now to illustrate the API but
  1514  	// we should really cache already-prepared statements
  1515  	// per-Conn. See also the big comment in Tx.Prepare.
  1516  
  1517  	if tx.db != stmt.db {
  1518  		return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")}
  1519  	}
  1520  	dc, err := tx.grabConn(ctx)
  1521  	if err != nil {
  1522  		return &Stmt{stickyErr: err}
  1523  	}
  1524  	var si driver.Stmt
  1525  	withLock(dc, func() {
  1526  		si, err = dc.ci.Prepare(stmt.query)
  1527  	})
  1528  	txs := &Stmt{
  1529  		db: tx.db,
  1530  		tx: tx,
  1531  		txsi: &driverStmt{
  1532  			Locker: dc,
  1533  			si:     si,
  1534  		},
  1535  		query:     stmt.query,
  1536  		stickyErr: err,
  1537  	}
  1538  	tx.stmts.Lock()
  1539  	tx.stmts.v = append(tx.stmts.v, txs)
  1540  	tx.stmts.Unlock()
  1541  	return txs
  1542  }
  1543  
  1544  // Stmt returns a transaction-specific prepared statement from
  1545  // an existing statement.
  1546  //
  1547  // Example:
  1548  //  updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
  1549  //  ...
  1550  //  tx, err := db.Begin()
  1551  //  ...
  1552  //  res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
  1553  //
  1554  // The returned statement operates within the transaction and can no longer
  1555  // be used once the transaction has been committed or rolled back.
  1556  func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
  1557  	return tx.StmtContext(context.Background(), stmt)
  1558  }
  1559  
  1560  // ExecContext executes a query that doesn't return rows.
  1561  // For example: an INSERT and UPDATE.
  1562  func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error) {
  1563  	dc, err := tx.grabConn(ctx)
  1564  	if err != nil {
  1565  		return nil, err
  1566  	}
  1567  
  1568  	if execer, ok := dc.ci.(driver.Execer); ok {
  1569  		dargs, err := driverArgs(nil, args)
  1570  		if err != nil {
  1571  			return nil, err
  1572  		}
  1573  		var resi driver.Result
  1574  		withLock(dc, func() {
  1575  			resi, err = ctxDriverExec(ctx, execer, query, dargs)
  1576  		})
  1577  		if err == nil {
  1578  			return driverResult{dc, resi}, nil
  1579  		}
  1580  		if err != driver.ErrSkip {
  1581  			return nil, err
  1582  		}
  1583  	}
  1584  
  1585  	var si driver.Stmt
  1586  	withLock(dc, func() {
  1587  		si, err = ctxDriverPrepare(ctx, dc.ci, query)
  1588  	})
  1589  	if err != nil {
  1590  		return nil, err
  1591  	}
  1592  	defer withLock(dc, func() { si.Close() })
  1593  
  1594  	return resultFromStatement(ctx, driverStmt{dc, si}, args...)
  1595  }
  1596  
  1597  // Exec executes a query that doesn't return rows.
  1598  // For example: an INSERT and UPDATE.
  1599  func (tx *Tx) Exec(query string, args ...interface{}) (Result, error) {
  1600  	return tx.ExecContext(context.Background(), query, args...)
  1601  }
  1602  
  1603  // QueryContext executes a query that returns rows, typically a SELECT.
  1604  func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
  1605  	dc, err := tx.grabConn(ctx)
  1606  	if err != nil {
  1607  		return nil, err
  1608  	}
  1609  	releaseConn := func(error) {}
  1610  	return tx.db.queryConn(ctx, dc, releaseConn, query, args)
  1611  }
  1612  
  1613  // Query executes a query that returns rows, typically a SELECT.
  1614  func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) {
  1615  	return tx.QueryContext(context.Background(), query, args...)
  1616  }
  1617  
  1618  // QueryRowContext executes a query that is expected to return at most one row.
  1619  // QueryRowContext always returns a non-nil value. Errors are deferred until
  1620  // Row's Scan method is called.
  1621  func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
  1622  	rows, err := tx.QueryContext(ctx, query, args...)
  1623  	return &Row{rows: rows, err: err}
  1624  }
  1625  
  1626  // QueryRow executes a query that is expected to return at most one row.
  1627  // QueryRow always returns a non-nil value. Errors are deferred until
  1628  // Row's Scan method is called.
  1629  func (tx *Tx) QueryRow(query string, args ...interface{}) *Row {
  1630  	return tx.QueryRowContext(context.Background(), query, args...)
  1631  }
  1632  
  1633  // connStmt is a prepared statement on a particular connection.
  1634  type connStmt struct {
  1635  	dc *driverConn
  1636  	si driver.Stmt
  1637  }
  1638  
  1639  // Stmt is a prepared statement.
  1640  // A Stmt is safe for concurrent use by multiple goroutines.
  1641  type Stmt struct {
  1642  	// Immutable:
  1643  	db        *DB    // where we came from
  1644  	query     string // that created the Stmt
  1645  	stickyErr error  // if non-nil, this error is returned for all operations
  1646  
  1647  	closemu sync.RWMutex // held exclusively during close, for read otherwise.
  1648  
  1649  	// If in a transaction, else both nil:
  1650  	tx   *Tx
  1651  	txsi *driverStmt
  1652  
  1653  	mu     sync.Mutex // protects the rest of the fields
  1654  	closed bool
  1655  
  1656  	// css is a list of underlying driver statement interfaces
  1657  	// that are valid on particular connections. This is only
  1658  	// used if tx == nil and one is found that has idle
  1659  	// connections. If tx != nil, txsi is always used.
  1660  	css []connStmt
  1661  
  1662  	// lastNumClosed is copied from db.numClosed when Stmt is created
  1663  	// without tx and closed connections in css are removed.
  1664  	lastNumClosed uint64
  1665  }
  1666  
  1667  // ExecContext executes a prepared statement with the given arguments and
  1668  // returns a Result summarizing the effect of the statement.
  1669  func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error) {
  1670  	s.closemu.RLock()
  1671  	defer s.closemu.RUnlock()
  1672  
  1673  	var res Result
  1674  	for i := 0; i < maxBadConnRetries; i++ {
  1675  		dc, releaseConn, si, err := s.connStmt(ctx)
  1676  		if err != nil {
  1677  			if err == driver.ErrBadConn {
  1678  				continue
  1679  			}
  1680  			return nil, err
  1681  		}
  1682  
  1683  		res, err = resultFromStatement(ctx, driverStmt{dc, si}, args...)
  1684  		releaseConn(err)
  1685  		if err != driver.ErrBadConn {
  1686  			return res, err
  1687  		}
  1688  	}
  1689  	return nil, driver.ErrBadConn
  1690  }
  1691  
  1692  // Exec executes a prepared statement with the given arguments and
  1693  // returns a Result summarizing the effect of the statement.
  1694  func (s *Stmt) Exec(args ...interface{}) (Result, error) {
  1695  	return s.ExecContext(context.Background(), args...)
  1696  }
  1697  
  1698  func driverNumInput(ds driverStmt) int {
  1699  	ds.Lock()
  1700  	defer ds.Unlock() // in case NumInput panics
  1701  	return ds.si.NumInput()
  1702  }
  1703  
  1704  func resultFromStatement(ctx context.Context, ds driverStmt, args ...interface{}) (Result, error) {
  1705  	want := driverNumInput(ds)
  1706  
  1707  	// -1 means the driver doesn't know how to count the number of
  1708  	// placeholders, so we won't sanity check input here and instead let the
  1709  	// driver deal with errors.
  1710  	if want != -1 && len(args) != want {
  1711  		return nil, fmt.Errorf("sql: expected %d arguments, got %d", want, len(args))
  1712  	}
  1713  
  1714  	dargs, err := driverArgs(&ds, args)
  1715  	if err != nil {
  1716  		return nil, err
  1717  	}
  1718  
  1719  	ds.Lock()
  1720  	defer ds.Unlock()
  1721  
  1722  	resi, err := ctxDriverStmtExec(ctx, ds.si, dargs)
  1723  	if err != nil {
  1724  		return nil, err
  1725  	}
  1726  	return driverResult{ds.Locker, resi}, nil
  1727  }
  1728  
  1729  // removeClosedStmtLocked removes closed conns in s.css.
  1730  //
  1731  // To avoid lock contention on DB.mu, we do it only when
  1732  // s.db.numClosed - s.lastNum is large enough.
  1733  func (s *Stmt) removeClosedStmtLocked() {
  1734  	t := len(s.css)/2 + 1
  1735  	if t > 10 {
  1736  		t = 10
  1737  	}
  1738  	dbClosed := atomic.LoadUint64(&s.db.numClosed)
  1739  	if dbClosed-s.lastNumClosed < uint64(t) {
  1740  		return
  1741  	}
  1742  
  1743  	s.db.mu.Lock()
  1744  	for i := 0; i < len(s.css); i++ {
  1745  		if s.css[i].dc.dbmuClosed {
  1746  			s.css[i] = s.css[len(s.css)-1]
  1747  			s.css = s.css[:len(s.css)-1]
  1748  			i--
  1749  		}
  1750  	}
  1751  	s.db.mu.Unlock()
  1752  	s.lastNumClosed = dbClosed
  1753  }
  1754  
  1755  // connStmt returns a free driver connection on which to execute the
  1756  // statement, a function to call to release the connection, and a
  1757  // statement bound to that connection.
  1758  func (s *Stmt) connStmt(ctx context.Context) (ci *driverConn, releaseConn func(error), si driver.Stmt, err error) {
  1759  	if err = s.stickyErr; err != nil {
  1760  		return
  1761  	}
  1762  	s.mu.Lock()
  1763  	if s.closed {
  1764  		s.mu.Unlock()
  1765  		err = errors.New("sql: statement is closed")
  1766  		return
  1767  	}
  1768  
  1769  	// In a transaction, we always use the connection that the
  1770  	// transaction was created on.
  1771  	if s.tx != nil {
  1772  		s.mu.Unlock()
  1773  		ci, err = s.tx.grabConn(ctx) // blocks, waiting for the connection.
  1774  		if err != nil {
  1775  			return
  1776  		}
  1777  		releaseConn = func(error) {}
  1778  		return ci, releaseConn, s.txsi.si, nil
  1779  	}
  1780  
  1781  	s.removeClosedStmtLocked()
  1782  	s.mu.Unlock()
  1783  
  1784  	dc, err := s.db.conn(ctx, cachedOrNewConn)
  1785  	if err != nil {
  1786  		return nil, nil, nil, err
  1787  	}
  1788  
  1789  	s.mu.Lock()
  1790  	for _, v := range s.css {
  1791  		if v.dc == dc {
  1792  			s.mu.Unlock()
  1793  			return dc, dc.releaseConn, v.si, nil
  1794  		}
  1795  	}
  1796  	s.mu.Unlock()
  1797  
  1798  	// No luck; we need to prepare the statement on this connection
  1799  	withLock(dc, func() {
  1800  		si, err = dc.prepareLocked(ctx, s.query)
  1801  	})
  1802  	if err != nil {
  1803  		s.db.putConn(dc, err)
  1804  		return nil, nil, nil, err
  1805  	}
  1806  	s.mu.Lock()
  1807  	cs := connStmt{dc, si}
  1808  	s.css = append(s.css, cs)
  1809  	s.mu.Unlock()
  1810  
  1811  	return dc, dc.releaseConn, si, nil
  1812  }
  1813  
  1814  // QueryContext executes a prepared query statement with the given arguments
  1815  // and returns the query results as a *Rows.
  1816  func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error) {
  1817  	s.closemu.RLock()
  1818  	defer s.closemu.RUnlock()
  1819  
  1820  	var rowsi driver.Rows
  1821  	for i := 0; i < maxBadConnRetries; i++ {
  1822  		dc, releaseConn, si, err := s.connStmt(ctx)
  1823  		if err != nil {
  1824  			if err == driver.ErrBadConn {
  1825  				continue
  1826  			}
  1827  			return nil, err
  1828  		}
  1829  
  1830  		rowsi, err = rowsiFromStatement(ctx, driverStmt{dc, si}, args...)
  1831  		if err == nil {
  1832  			// Note: ownership of ci passes to the *Rows, to be freed
  1833  			// with releaseConn.
  1834  			rows := &Rows{
  1835  				dc:    dc,
  1836  				rowsi: rowsi,
  1837  				// releaseConn set below
  1838  			}
  1839  			rows.initContextClose(ctx)
  1840  			s.db.addDep(s, rows)
  1841  			rows.releaseConn = func(err error) {
  1842  				releaseConn(err)
  1843  				s.db.removeDep(s, rows)
  1844  			}
  1845  			return rows, nil
  1846  		}
  1847  
  1848  		releaseConn(err)
  1849  		if err != driver.ErrBadConn {
  1850  			return nil, err
  1851  		}
  1852  	}
  1853  	return nil, driver.ErrBadConn
  1854  }
  1855  
  1856  // Query executes a prepared query statement with the given arguments
  1857  // and returns the query results as a *Rows.
  1858  func (s *Stmt) Query(args ...interface{}) (*Rows, error) {
  1859  	return s.QueryContext(context.Background(), args...)
  1860  }
  1861  
  1862  func rowsiFromStatement(ctx context.Context, ds driverStmt, args ...interface{}) (driver.Rows, error) {
  1863  	var want int
  1864  	withLock(ds, func() {
  1865  		want = ds.si.NumInput()
  1866  	})
  1867  
  1868  	// -1 means the driver doesn't know how to count the number of
  1869  	// placeholders, so we won't sanity check input here and instead let the
  1870  	// driver deal with errors.
  1871  	if want != -1 && len(args) != want {
  1872  		return nil, fmt.Errorf("sql: statement expects %d inputs; got %d", want, len(args))
  1873  	}
  1874  
  1875  	dargs, err := driverArgs(&ds, args)
  1876  	if err != nil {
  1877  		return nil, err
  1878  	}
  1879  
  1880  	ds.Lock()
  1881  	defer ds.Unlock()
  1882  
  1883  	rowsi, err := ctxDriverStmtQuery(ctx, ds.si, dargs)
  1884  	if err != nil {
  1885  		return nil, err
  1886  	}
  1887  	return rowsi, nil
  1888  }
  1889  
  1890  // QueryRowContext executes a prepared query statement with the given arguments.
  1891  // If an error occurs during the execution of the statement, that error will
  1892  // be returned by a call to Scan on the returned *Row, which is always non-nil.
  1893  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  1894  // Otherwise, the *Row's Scan scans the first selected row and discards
  1895  // the rest.
  1896  //
  1897  // Example usage:
  1898  //
  1899  //  var name string
  1900  //  err := nameByUseridStmt.QueryRowContext(ctx, id).Scan(&name)
  1901  func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *Row {
  1902  	rows, err := s.QueryContext(ctx, args...)
  1903  	if err != nil {
  1904  		return &Row{err: err}
  1905  	}
  1906  	return &Row{rows: rows}
  1907  }
  1908  
  1909  // QueryRow executes a prepared query statement with the given arguments.
  1910  // If an error occurs during the execution of the statement, that error will
  1911  // be returned by a call to Scan on the returned *Row, which is always non-nil.
  1912  // If the query selects no rows, the *Row's Scan will return ErrNoRows.
  1913  // Otherwise, the *Row's Scan scans the first selected row and discards
  1914  // the rest.
  1915  //
  1916  // Example usage:
  1917  //
  1918  //  var name string
  1919  //  err := nameByUseridStmt.QueryRow(id).Scan(&name)
  1920  func (s *Stmt) QueryRow(args ...interface{}) *Row {
  1921  	return s.QueryRowContext(context.Background(), args...)
  1922  }
  1923  
  1924  // Close closes the statement.
  1925  func (s *Stmt) Close() error {
  1926  	s.closemu.Lock()
  1927  	defer s.closemu.Unlock()
  1928  
  1929  	if s.stickyErr != nil {
  1930  		return s.stickyErr
  1931  	}
  1932  	s.mu.Lock()
  1933  	if s.closed {
  1934  		s.mu.Unlock()
  1935  		return nil
  1936  	}
  1937  	s.closed = true
  1938  
  1939  	if s.tx != nil {
  1940  		defer s.mu.Unlock()
  1941  		return s.txsi.Close()
  1942  	}
  1943  	s.mu.Unlock()
  1944  
  1945  	return s.db.removeDep(s, s)
  1946  }
  1947  
  1948  func (s *Stmt) finalClose() error {
  1949  	s.mu.Lock()
  1950  	defer s.mu.Unlock()
  1951  	if s.css != nil {
  1952  		for _, v := range s.css {
  1953  			s.db.noteUnusedDriverStatement(v.dc, v.si)
  1954  			v.dc.removeOpenStmt(v.si)
  1955  		}
  1956  		s.css = nil
  1957  	}
  1958  	return nil
  1959  }
  1960  
  1961  // Rows is the result of a query. Its cursor starts before the first row
  1962  // of the result set. Use Next to advance through the rows:
  1963  //
  1964  //     rows, err := db.Query("SELECT ...")
  1965  //     ...
  1966  //     defer rows.Close()
  1967  //     for rows.Next() {
  1968  //         var id int
  1969  //         var name string
  1970  //         err = rows.Scan(&id, &name)
  1971  //         ...
  1972  //     }
  1973  //     err = rows.Err() // get any error encountered during iteration
  1974  //     ...
  1975  type Rows struct {
  1976  	dc          *driverConn // owned; must call releaseConn when closed to release
  1977  	releaseConn func(error)
  1978  	rowsi       driver.Rows
  1979  
  1980  	// closed value is 1 when the Rows is closed.
  1981  	// Use atomic operations on value when checking value.
  1982  	closed    int32
  1983  	ctxClose  chan struct{} // closed when Rows is closed, may be null.
  1984  	lastcols  []driver.Value
  1985  	lasterr   error       // non-nil only if closed is true
  1986  	closeStmt driver.Stmt // if non-nil, statement to Close on close
  1987  }
  1988  
  1989  func (rs *Rows) initContextClose(ctx context.Context) {
  1990  	if ctx.Done() == context.Background().Done() {
  1991  		return
  1992  	}
  1993  
  1994  	rs.ctxClose = make(chan struct{})
  1995  	go func() {
  1996  		select {
  1997  		case <-ctx.Done():
  1998  			rs.Close()
  1999  		case <-rs.ctxClose:
  2000  		}
  2001  	}()
  2002  }
  2003  
  2004  // Next prepares the next result row for reading with the Scan method. It
  2005  // returns true on success, or false if there is no next result row or an error
  2006  // happened while preparing it. Err should be consulted to distinguish between
  2007  // the two cases.
  2008  //
  2009  // Every call to Scan, even the first one, must be preceded by a call to Next.
  2010  func (rs *Rows) Next() bool {
  2011  	if rs.isClosed() {
  2012  		return false
  2013  	}
  2014  	if rs.lastcols == nil {
  2015  		rs.lastcols = make([]driver.Value, len(rs.rowsi.Columns()))
  2016  	}
  2017  	rs.lasterr = rs.rowsi.Next(rs.lastcols)
  2018  	if rs.lasterr != nil {
  2019  		// Close the connection if there is a driver error.
  2020  		if rs.lasterr != io.EOF {
  2021  			rs.Close()
  2022  			return false
  2023  		}
  2024  		nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
  2025  		if !ok {
  2026  			rs.Close()
  2027  			return false
  2028  		}
  2029  		// The driver is at the end of the current result set.
  2030  		// Test to see if there is another result set after the current one.
  2031  		// Only close Rows if there is no futher result sets to read.
  2032  		if !nextResultSet.HasNextResultSet() {
  2033  			rs.Close()
  2034  		}
  2035  		return false
  2036  	}
  2037  	return true
  2038  }
  2039  
  2040  // NextResultSet prepares the next result set for reading. It returns true if
  2041  // there is further result sets, or false if there is no further result set
  2042  // or if there is an error advancing to it. The Err method should be consulted
  2043  // to distinguish between the two cases.
  2044  //
  2045  // After calling NextResultSet, the Next method should always be called before
  2046  // scanning. If there are further result sets they may not have rows in the result
  2047  // set.
  2048  func (rs *Rows) NextResultSet() bool {
  2049  	if rs.isClosed() {
  2050  		return false
  2051  	}
  2052  	rs.lastcols = nil
  2053  	nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
  2054  	if !ok {
  2055  		rs.Close()
  2056  		return false
  2057  	}
  2058  	rs.lasterr = nextResultSet.NextResultSet()
  2059  	if rs.lasterr != nil {
  2060  		rs.Close()
  2061  		return false
  2062  	}
  2063  	return true
  2064  }
  2065  
  2066  // Err returns the error, if any, that was encountered during iteration.
  2067  // Err may be called after an explicit or implicit Close.
  2068  func (rs *Rows) Err() error {
  2069  	if rs.lasterr == io.EOF {
  2070  		return nil
  2071  	}
  2072  	return rs.lasterr
  2073  }
  2074  
  2075  // Columns returns the column names.
  2076  // Columns returns an error if the rows are closed, or if the rows
  2077  // are from QueryRow and there was a deferred error.
  2078  func (rs *Rows) Columns() ([]string, error) {
  2079  	if rs.isClosed() {
  2080  		return nil, errors.New("sql: Rows are closed")
  2081  	}
  2082  	if rs.rowsi == nil {
  2083  		return nil, errors.New("sql: no Rows available")
  2084  	}
  2085  	return rs.rowsi.Columns(), nil
  2086  }
  2087  
  2088  // ColumnTypes returns column information such as column type, length,
  2089  // and nullable. Some information may not be available from some drivers.
  2090  func (rs *Rows) ColumnTypes() ([]*ColumnType, error) {
  2091  	if rs.isClosed() {
  2092  		return nil, errors.New("sql: Rows are closed")
  2093  	}
  2094  	if rs.rowsi == nil {
  2095  		return nil, errors.New("sql: no Rows available")
  2096  	}
  2097  	return rowsColumnInfoSetup(rs.rowsi), nil
  2098  }
  2099  
  2100  // ColumnType contains the name and type of a column.
  2101  type ColumnType struct {
  2102  	name string
  2103  
  2104  	hasNullable       bool
  2105  	hasLength         bool
  2106  	hasPrecisionScale bool
  2107  
  2108  	nullable     bool
  2109  	length       int64
  2110  	databaseType string
  2111  	precision    int64
  2112  	scale        int64
  2113  	scanType     reflect.Type
  2114  }
  2115  
  2116  // Name returns the name or alias of the column.
  2117  func (ci *ColumnType) Name() string {
  2118  	return ci.name
  2119  }
  2120  
  2121  // Length returns the column type length for variable length column types such
  2122  // as text and binary field types. If the type length is unbounded the value will
  2123  // be math.MaxInt64 (any database limits will still apply).
  2124  // If the column type is not variable length, such as an int, or if not supported
  2125  // by the driver ok is false.
  2126  func (ci *ColumnType) Length() (length int64, ok bool) {
  2127  	return ci.length, ci.hasLength
  2128  }
  2129  
  2130  // DecimalSize returns the scale and precision of a decimal type.
  2131  // If not applicable or if not supported ok is false.
  2132  func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool) {
  2133  	return ci.precision, ci.scale, ci.hasPrecisionScale
  2134  }
  2135  
  2136  // ScanType returns a Go type suitable for scanning into using Rows.Scan.
  2137  // If a driver does not support this property ScanType will return
  2138  // the type of an empty interface.
  2139  func (ci *ColumnType) ScanType() reflect.Type {
  2140  	return ci.scanType
  2141  }
  2142  
  2143  // Nullable returns whether the column may be null.
  2144  // If a driver does not support this property ok will be false.
  2145  func (ci *ColumnType) Nullable() (nullable, ok bool) {
  2146  	return ci.nullable, ci.hasNullable
  2147  }
  2148  
  2149  // DatabaseTypeName returns the database system name of the column type. If an empty
  2150  // string is returned the driver type name is not supported.
  2151  // Consult your driver documentation for a list of driver data types. Length specifiers
  2152  // are not included.
  2153  // Common type include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL", "INT", "BIGINT".
  2154  func (ci *ColumnType) DatabaseTypeName() string {
  2155  	return ci.databaseType
  2156  }
  2157  
  2158  func rowsColumnInfoSetup(rowsi driver.Rows) []*ColumnType {
  2159  	names := rowsi.Columns()
  2160  
  2161  	list := make([]*ColumnType, len(names))
  2162  	for i := range list {
  2163  		ci := &ColumnType{
  2164  			name: names[i],
  2165  		}
  2166  		list[i] = ci
  2167  
  2168  		if prop, ok := rowsi.(driver.RowsColumnTypeScanType); ok {
  2169  			ci.scanType = prop.ColumnTypeScanType(i)
  2170  		} else {
  2171  			ci.scanType = reflect.TypeOf(new(interface{})).Elem()
  2172  		}
  2173  		if prop, ok := rowsi.(driver.RowsColumnTypeDatabaseTypeName); ok {
  2174  			ci.databaseType = prop.ColumnTypeDatabaseTypeName(i)
  2175  		}
  2176  		if prop, ok := rowsi.(driver.RowsColumnTypeLength); ok {
  2177  			ci.length, ci.hasLength = prop.ColumnTypeLength(i)
  2178  		}
  2179  		if prop, ok := rowsi.(driver.RowsColumnTypeNullable); ok {
  2180  			ci.nullable, ci.hasNullable = prop.ColumnTypeNullable(i)
  2181  		}
  2182  		if prop, ok := rowsi.(driver.RowsColumnTypePrecisionScale); ok {
  2183  			ci.precision, ci.scale, ci.hasPrecisionScale = prop.ColumnTypePrecisionScale(i)
  2184  		}
  2185  	}
  2186  	return list
  2187  }
  2188  
  2189  // Scan copies the columns in the current row into the values pointed
  2190  // at by dest. The number of values in dest must be the same as the
  2191  // number of columns in Rows.
  2192  //
  2193  // Scan converts columns read from the database into the following
  2194  // common Go types and special types provided by the sql package:
  2195  //
  2196  //    *string
  2197  //    *[]byte
  2198  //    *int, *int8, *int16, *int32, *int64
  2199  //    *uint, *uint8, *uint16, *uint32, *uint64
  2200  //    *bool
  2201  //    *float32, *float64
  2202  //    *interface{}
  2203  //    *RawBytes
  2204  //    any type implementing Scanner (see Scanner docs)
  2205  //
  2206  // In the most simple case, if the type of the value from the source
  2207  // column is an integer, bool or string type T and dest is of type *T,
  2208  // Scan simply assigns the value through the pointer.
  2209  //
  2210  // Scan also converts between string and numeric types, as long as no
  2211  // information would be lost. While Scan stringifies all numbers
  2212  // scanned from numeric database columns into *string, scans into
  2213  // numeric types are checked for overflow. For example, a float64 with
  2214  // value 300 or a string with value "300" can scan into a uint16, but
  2215  // not into a uint8, though float64(255) or "255" can scan into a
  2216  // uint8. One exception is that scans of some float64 numbers to
  2217  // strings may lose information when stringifying. In general, scan
  2218  // floating point columns into *float64.
  2219  //
  2220  // If a dest argument has type *[]byte, Scan saves in that argument a
  2221  // copy of the corresponding data. The copy is owned by the caller and
  2222  // can be modified and held indefinitely. The copy can be avoided by
  2223  // using an argument of type *RawBytes instead; see the documentation
  2224  // for RawBytes for restrictions on its use.
  2225  //
  2226  // If an argument has type *interface{}, Scan copies the value
  2227  // provided by the underlying driver without conversion. When scanning
  2228  // from a source value of type []byte to *interface{}, a copy of the
  2229  // slice is made and the caller owns the result.
  2230  //
  2231  // Source values of type time.Time may be scanned into values of type
  2232  // *time.Time, *interface{}, *string, or *[]byte. When converting to
  2233  // the latter two, time.Format3339Nano is used.
  2234  //
  2235  // Source values of type bool may be scanned into types *bool,
  2236  // *interface{}, *string, *[]byte, or *RawBytes.
  2237  //
  2238  // For scanning into *bool, the source may be true, false, 1, 0, or
  2239  // string inputs parseable by strconv.ParseBool.
  2240  func (rs *Rows) Scan(dest ...interface{}) error {
  2241  	if rs.isClosed() {
  2242  		return errors.New("sql: Rows are closed")
  2243  	}
  2244  	if rs.lastcols == nil {
  2245  		return errors.New("sql: Scan called without calling Next")
  2246  	}
  2247  	if len(dest) != len(rs.lastcols) {
  2248  		return fmt.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest))
  2249  	}
  2250  	for i, sv := range rs.lastcols {
  2251  		err := convertAssign(dest[i], sv)
  2252  		if err != nil {
  2253  			return fmt.Errorf("sql: Scan error on column index %d: %v", i, err)
  2254  		}
  2255  	}
  2256  	return nil
  2257  }
  2258  
  2259  var rowsCloseHook func(*Rows, *error)
  2260  
  2261  func (rs *Rows) isClosed() bool {
  2262  	return atomic.LoadInt32(&rs.closed) != 0
  2263  }
  2264  
  2265  // Close closes the Rows, preventing further enumeration. If Next is called
  2266  // and returns false and there are no further result sets,
  2267  // the Rows are closed automatically and it will suffice to check the
  2268  // result of Err. Close is idempotent and does not affect the result of Err.
  2269  func (rs *Rows) Close() error {
  2270  	if !atomic.CompareAndSwapInt32(&rs.closed, 0, 1) {
  2271  		return nil
  2272  	}
  2273  	if rs.ctxClose != nil {
  2274  		close(rs.ctxClose)
  2275  	}
  2276  	err := rs.rowsi.Close()
  2277  	if fn := rowsCloseHook; fn != nil {
  2278  		fn(rs, &err)
  2279  	}
  2280  	if rs.closeStmt != nil {
  2281  		rs.closeStmt.Close()
  2282  	}
  2283  	rs.releaseConn(err)
  2284  	return err
  2285  }
  2286  
  2287  // Row is the result of calling QueryRow to select a single row.
  2288  type Row struct {
  2289  	// One of these two will be non-nil:
  2290  	err  error // deferred error for easy chaining
  2291  	rows *Rows
  2292  }
  2293  
  2294  // Scan copies the columns from the matched row into the values
  2295  // pointed at by dest. See the documentation on Rows.Scan for details.
  2296  // If more than one row matches the query,
  2297  // Scan uses the first row and discards the rest. If no row matches
  2298  // the query, Scan returns ErrNoRows.
  2299  func (r *Row) Scan(dest ...interface{}) error {
  2300  	if r.err != nil {
  2301  		return r.err
  2302  	}
  2303  
  2304  	// TODO(bradfitz): for now we need to defensively clone all
  2305  	// []byte that the driver returned (not permitting
  2306  	// *RawBytes in Rows.Scan), since we're about to close
  2307  	// the Rows in our defer, when we return from this function.
  2308  	// the contract with the driver.Next(...) interface is that it
  2309  	// can return slices into read-only temporary memory that's
  2310  	// only valid until the next Scan/Close. But the TODO is that
  2311  	// for a lot of drivers, this copy will be unnecessary. We
  2312  	// should provide an optional interface for drivers to
  2313  	// implement to say, "don't worry, the []bytes that I return
  2314  	// from Next will not be modified again." (for instance, if
  2315  	// they were obtained from the network anyway) But for now we
  2316  	// don't care.
  2317  	defer r.rows.Close()
  2318  	for _, dp := range dest {
  2319  		if _, ok := dp.(*RawBytes); ok {
  2320  			return errors.New("sql: RawBytes isn't allowed on Row.Scan")
  2321  		}
  2322  	}
  2323  
  2324  	if !r.rows.Next() {
  2325  		if err := r.rows.Err(); err != nil {
  2326  			return err
  2327  		}
  2328  		return ErrNoRows
  2329  	}
  2330  	err := r.rows.Scan(dest...)
  2331  	if err != nil {
  2332  		return err
  2333  	}
  2334  	// Make sure the query can be processed to completion with no errors.
  2335  	if err := r.rows.Close(); err != nil {
  2336  		return err
  2337  	}
  2338  
  2339  	return nil
  2340  }
  2341  
  2342  // A Result summarizes an executed SQL command.
  2343  type Result interface {
  2344  	// LastInsertId returns the integer generated by the database
  2345  	// in response to a command. Typically this will be from an
  2346  	// "auto increment" column when inserting a new row. Not all
  2347  	// databases support this feature, and the syntax of such
  2348  	// statements varies.
  2349  	LastInsertId() (int64, error)
  2350  
  2351  	// RowsAffected returns the number of rows affected by an
  2352  	// update, insert, or delete. Not every database or database
  2353  	// driver may support this.
  2354  	RowsAffected() (int64, error)
  2355  }
  2356  
  2357  type driverResult struct {
  2358  	sync.Locker // the *driverConn
  2359  	resi        driver.Result
  2360  }
  2361  
  2362  func (dr driverResult) LastInsertId() (int64, error) {
  2363  	dr.Lock()
  2364  	defer dr.Unlock()
  2365  	return dr.resi.LastInsertId()
  2366  }
  2367  
  2368  func (dr driverResult) RowsAffected() (int64, error) {
  2369  	dr.Lock()
  2370  	defer dr.Unlock()
  2371  	return dr.resi.RowsAffected()
  2372  }
  2373  
  2374  func stack() string {
  2375  	var buf [2 << 10]byte
  2376  	return string(buf[:runtime.Stack(buf[:], false)])
  2377  }
  2378  
  2379  // withLock runs while holding lk.
  2380  func withLock(lk sync.Locker, fn func()) {
  2381  	lk.Lock()
  2382  	defer lk.Unlock() // in case fn panics
  2383  	fn()
  2384  }