...

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

View as plain text