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

View as plain text