Run Format

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

View as plain text