...
Run Format

Source file src/database/sql/sql.go

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

View as plain text