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

View as plain text