...
Run Format

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

View as plain text