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.
5 // Package sql provides a generic interface around SQL (or SQL-like)
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.
11 // For more usage examples, see the wiki page at
12 // http://golang.org/s/sqlwiki.
25 var drivers
= make(map[string]driver
.Driver
)
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,
30 func Register(name
string, driver driver
.Driver
) {
32 panic("sql: Register driver is nil")
34 if _
, dup
:= drivers
[name
]; dup
{
35 panic("sql: Register called twice for driver " + name
)
37 drivers
[name
] = driver
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.
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:
50 // err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
58 type NullString
struct {
60 Valid
bool // Valid is true if String is not NULL
63 // Scan implements the Scanner interface.
64 func (ns
*NullString
) Scan(value
interface{}) error
{
66 ns
.String
, ns
.Valid
= "", false
70 return convertAssign(&ns
.String
, value
)
73 // Value implements the driver Valuer interface.
74 func (ns NullString
) Value() (driver
.Value
, error
) {
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 {
86 Valid
bool // Valid is true if Int64 is not NULL
89 // Scan implements the Scanner interface.
90 func (n
*NullInt64
) Scan(value
interface{}) error
{
92 n
.Int64
, n
.Valid
= 0, false
96 return convertAssign(&n
.Int64
, value
)
99 // Value implements the driver Valuer interface.
100 func (n NullInt64
) Value() (driver
.Value
, error
) {
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 {
112 Valid
bool // Valid is true if Float64 is not NULL
115 // Scan implements the Scanner interface.
116 func (n
*NullFloat64
) Scan(value
interface{}) error
{
118 n
.Float64
, n
.Valid
= 0, false
122 return convertAssign(&n
.Float64
, value
)
125 // Value implements the driver Valuer interface.
126 func (n NullFloat64
) Value() (driver
.Value
, error
) {
130 return n
.Float64
, nil
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 {
138 Valid
bool // Valid is true if Bool is not NULL
141 // Scan implements the Scanner interface.
142 func (n
*NullBool
) Scan(value
interface{}) error
{
144 n
.Bool
, n
.Valid
= false, false
148 return convertAssign(&n
.Bool
, value
)
151 // Value implements the driver Valuer interface.
152 func (n NullBool
) Value() (driver
.Value
, error
) {
159 // Scanner is an interface used by Scan.
160 type Scanner
interface {
161 // Scan assigns a value from a database driver.
163 // The src value will be of one of the following restricted
172 // nil - for NULL values
174 // An error should be returned if the value can not be stored
175 // without loss of information.
176 Scan(src
interface{}) error
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")
184 // DB is a database handle. It's safe for concurrent use by multiple
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.
199 mu sync
.Mutex
// protects following fields
200 freeConn
*list
.List
// of *driverConn
201 connRequests
*list
.List
// of connRequest
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{}
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
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,
221 type driverConn
struct {
224 sync
.Mutex
// guards following
227 finalClosed
bool // ci.Close has been called
228 openStmt
map[driver
.Stmt
]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
239 func (dc
*driverConn
) releaseConn(err error
) {
240 dc
.db
.putConn(dc
, err
)
243 func (dc
*driverConn
) removeOpenStmt(si driver
.Stmt
) {
246 delete(dc
.openStmt
, si
)
249 func (dc
*driverConn
) prepareLocked(query
string) (driver
.Stmt
, error
) {
250 si
, err
:= dc
.ci
.Prepare(query
)
252 // Track each driverConn's open statements, so we can close them
253 // before closing the conn.
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.
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)
268 dc
.openStmt
[si
] = true
273 // the dc.db's Mutex is held.
274 func (dc
*driverConn
) closeDBLocked() func() error
{
278 return func() error
{ return errors
.New("sql: duplicate driverConn close") }
281 return dc
.db
.removeDepLocked(dc
, dc
)
284 func (dc
*driverConn
) Close() error
{
288 return errors
.New("sql: duplicate driverConn close")
291 dc
.Unlock() // not defer; removeDep finalClose calls may need to lock
293 // And now updates that require holding dc.mu.Lock.
296 fn
:= dc
.db
.removeDepLocked(dc
, dc
)
301 func (dc
*driverConn
) finalClose() error
{
304 for si
:= range dc
.openStmt
{
311 dc
.finalClosed
= true
316 dc
.db
.maybeOpenNewConnections()
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
330 func (ds
*driverStmt
) Close() error
{
336 // depSet is a finalCloser's outstanding dependencies
337 type depSet
map[interface{}]bool // set of true bools
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.
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))
353 db
.addDepLocked(x
, dep
)
356 func (db
*DB
) addDepLocked(x finalCloser
, dep
interface{}) {
358 db
.dep
= make(map[finalCloser
]depSet
)
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
{
374 fn
:= db
.removeDepLocked(x
, dep
)
379 func (db
*DB
) removeDepLocked(x finalCloser
, dep
interface{}) func() error
{
380 //println(fmt.Sprintf("removeDep(%T %p, %T %p)", x, x, dep, dep))
382 xdep
, ok
:= db
.dep
[x
]
384 panic(fmt
.Sprintf("unpaired removeDep: no deps for %T", x
))
392 // Nothing removed. Shouldn't happen.
393 panic(fmt
.Sprintf("unpaired removeDep: no %T dep on %T", dep
, x
))
395 // No more dependencies.
399 // Dependencies remain.
400 return func() error
{ return nil }
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
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.
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.
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
423 func Open(driverName
, dataSourceName
string) (*DB
, error
) {
424 driveri
, ok
:= drivers
[driverName
]
426 return nil, fmt
.Errorf("sql: unknown driver %q (forgotten import?)", driverName
)
431 openerCh
: make(chan struct{}, connectionRequestQueueSize
),
432 lastPut
: make(map[*driverConn
]string),
434 db
.freeConn
= list
.New()
435 db
.connRequests
= list
.New()
436 go db
.connectionOpener()
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
454 // Close closes the database, releasing any open resources.
455 func (db
*DB
) Close() error
{
457 if db
.closed { // Make DB.Close idempotent
463 fns
:= make([]func() error
, 0, db
.freeConn
.Len())
464 for db
.freeConn
.Front() != nil {
465 dc
:= db
.freeConn
.Front().Value
.(*driverConn
)
467 fns
= append(fns
, dc
.closeDBLocked())
468 db
.freeConn
.Remove(db
.freeConn
.Front())
471 for db
.connRequests
.Front() != nil {
472 req
:= db
.connRequests
.Front().Value
.(connRequest
)
473 db
.connRequests
.Remove(db
.connRequests
.Front())
477 for _
, fn
:= range fns
{
486 const defaultMaxIdleConns
= 2
488 func (db
*DB
) maxIdleConnsLocked() int {
492 // TODO(bradfitz): ask driver, if supported, for its default preference
493 return defaultMaxIdleConns
501 // SetMaxIdleConns sets the maximum number of connections in the idle
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
507 // If n <= 0, no idle connections are retained.
508 func (db
*DB
) SetMaxIdleConns(n
int) {
513 // No idle connections.
516 // Make sure maxIdle doesn't exceed maxOpen
517 if db
.maxOpen
> 0 && db
.maxIdleConnsLocked() > db
.maxOpen
{
518 db
.maxIdle
= db
.maxOpen
520 var closing
[]*driverConn
521 for db
.freeConn
.Len() > db
.maxIdleConnsLocked() {
522 dc
:= db
.freeConn
.Back().Value
.(*driverConn
)
524 db
.freeConn
.Remove(db
.freeConn
.Back())
525 closing
= append(closing
, dc
)
528 for _
, c
:= range closing
{
533 // SetMaxOpenConns sets the maximum number of open connections to the database.
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
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) {
547 syncMaxIdle
:= db
.maxOpen
> 0 && db
.maxIdleConnsLocked() > db
.maxOpen
550 db
.SetMaxIdleConns(n
)
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
560 numCanOpen
:= db
.maxOpen
- (db
.numOpen
+ db
.pendingOpens
)
561 if numRequests
> numCanOpen
{
562 numRequests
= numCanOpen
565 for numRequests
> 0 {
568 db
.openerCh
<- struct{}{}
572 // Runs in a seperate goroutine, opens new connections when requested.
573 func (db
*DB
) connectionOpener() {
574 for _
= range db
.openerCh
{
575 db
.openNewConnection()
579 // Open one new connection
580 func (db
*DB
) openNewConnection() {
581 ci
, err
:= db
.driver
.Open(db
.dsn
)
592 db
.putConnDBLocked(nil, err
)
599 if db
.putConnDBLocked(dc
, err
) {
600 db
.addDepLocked(dc
, dc
)
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
612 var errDBClosed
= errors
.New("sql: database is closed")
614 // conn returns a newly-opened or cached *driverConn
615 func (db
*DB
) conn() (*driverConn
, error
) {
619 return nil, errDBClosed
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()
634 return nil, errDBClosed
638 return ret
.(*driverConn
), nil
640 return nil, ret
.(error
)
642 panic("sql: Unexpected type passed through connRequest.ch")
646 if f
:= db
.freeConn
.Front(); f
!= nil {
647 conn
:= f
.Value
.(*driverConn
)
649 db
.freeConn
.Remove(f
)
656 ci
, err
:= db
.driver
.Open(db
.dsn
)
666 db
.addDepLocked(dc
, dc
)
673 errConnClosed
= errors
.New("database/sql: internal sentinel error: conn is closed")
674 errConnBusy
= errors
.New("database/sql: internal sentinel error: conn is busy")
677 // connIfFree returns (wanted, nil) if wanted is still a valid conn and
680 // The error is errConnClosed if the connection if the requested connection
681 // is invalid because it's been closed.
683 // The error is errConnBusy if the connection is in use.
684 func (db
*DB
) connIfFree(wanted
*driverConn
) (*driverConn
, error
) {
687 if wanted
.dbmuClosed
{
688 return nil, errConnClosed
691 return nil, errConnBusy
693 if wanted
.listElem
!= nil {
694 db
.freeConn
.Remove(wanted
.listElem
)
695 wanted
.listElem
= nil
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
703 // Instead, treat it like a busy connection:
704 return nil, errConnBusy
707 // putConnHook is a hook for testing.
708 var putConnHook
func(*DB
, *driverConn
)
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
713 func (db
*DB
) noteUnusedDriverStatement(c
*driverConn
, si driver
.Stmt
) {
717 c
.onPut
= append(c
.onPut
, func() {
729 // debugGetPut determines whether getConn & putConn calls' stack traces
730 // are returned for more verbose crashes.
731 const debugGetPut
= false
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
) {
739 fmt
.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc
, stack(), db
.lastPut
[dc
])
741 panic("sql: connection returned that was never out")
744 db
.lastPut
[dc
] = stack()
748 for _
, fn
:= range dc
.onPut
{
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()
763 if putConnHook
!= nil {
766 added
:= db
.putConnDBLocked(dc
, nil)
774 // Satisfy a connRequest or put the driverConn in the idle pool and return true
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())
794 } else if err
== nil && !db
.closed && db
.maxIdleConnsLocked() > 0 && db
.maxIdleConnsLocked() > db
.freeConn
.Len() {
795 dc
.listElem
= db
.freeConn
.PushFront(dc
)
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
) {
807 for i
:= 0; i
< 10; i
++ {
808 stmt
, err
= db
.prepare(query
)
809 if err
!= driver
.ErrBadConn
{
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.
828 si
, err
:= dc
.prepareLocked(query
)
837 css
: []connStmt
{{dc
, si
}},
839 db
.addDep(stmt
, stmt
)
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
) {
849 for i
:= 0; i
< 10; i
++ {
850 res
, err
= db
.exec(query
, args
)
851 if err
!= driver
.ErrBadConn
{
858 func (db
*DB
) exec(query
string, args
[]interface{}) (res Result
, err error
) {
867 if execer
, ok
:= dc
.ci
.(driver
.Execer
); ok
{
868 dargs
, err
:= driverArgs(nil, args
)
873 resi
, err
:= execer
.Exec(query
, dargs
)
875 if err
!= driver
.ErrSkip
{
879 return driverResult
{dc
, resi
}, nil
884 si
, err
:= dc
.ci
.Prepare(query
)
889 defer withLock(dc
, func() { si
.Close() })
890 return resultFromStatement(driverStmt
{dc
, si
}, args
...)
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
) {
898 for i
:= 0; i
< 10; i
++ {
899 rows
, err
= db
.query(query
, args
)
900 if err
!= driver
.ErrBadConn
{
907 func (db
*DB
) query(query
string, args
[]interface{}) (*Rows
, error
) {
913 return db
.queryConn(ci
, ci
.releaseConn
, query
, args
)
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
)
926 rowsi
, err
:= queryer
.Query(query
, dargs
)
928 if err
!= driver
.ErrSkip
{
933 // Note: ownership of dc passes to the *Rows, to be freed
937 releaseConn
: releaseConn
,
945 si
, err
:= dc
.ci
.Prepare(query
)
952 ds
:= driverStmt
{dc
, si
}
953 rowsi
, err
:= rowsiFromStatement(ds
, args
...)
962 // Note: ownership of ci passes to the *Rows, to be freed
966 releaseConn
: releaseConn
,
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
}
981 // Begin starts a transaction. The isolation level is dependent on
983 func (db
*DB
) Begin() (*Tx
, error
) {
986 for i
:= 0; i
< 10; i
++ {
988 if err
!= driver
.ErrBadConn
{
995 func (db
*DB
) begin() (tx
*Tx
, err error
) {
1001 txi
, err
:= dc
.ci
.Begin()
1014 // Driver returns the database's underlying driver.
1015 func (db
*DB
) Driver() driver
.Driver
{
1019 // Tx is an in-progress database transaction.
1021 // A transaction must end with a call to Commit or Rollback.
1023 // After a call to Commit or Rollback, all operations on the
1024 // transaction fail with ErrTxDone.
1028 // dc is owned exclusively until Commit or Rollback, at which point
1029 // it's returned with putConn.
1033 // done transitions from false to true exactly once, on Commit
1034 // or Rollback. once done, all operations fail with
1039 var ErrTxDone
= errors
.New("sql: Transaction has already been committed or rolled back")
1041 func (tx
*Tx
) close() {
1043 panic("double close") // internal error
1046 tx
.db
.putConn(tx
.dc
, nil)
1051 func (tx
*Tx
) grabConn() (*driverConn
, error
) {
1053 return nil, ErrTxDone
1058 // Commit commits the transaction.
1059 func (tx
*Tx
) Commit() error
{
1065 defer tx
.dc
.Unlock()
1066 return tx
.txi
.Commit()
1069 // Rollback aborts the transaction.
1070 func (tx
*Tx
) Rollback() error
{
1076 defer tx
.dc
.Unlock()
1077 return tx
.txi
.Rollback()
1080 // Prepare creates a prepared statement for use within a transaction.
1082 // The returned statement operates within the transaction and can no longer
1083 // be used once the transaction has been committed or rolled back.
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()
1106 si
, err
:= dc
.ci
.Prepare(query
)
1124 // Stmt returns a transaction-specific prepared statement from
1125 // an existing statement.
1128 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
1130 // tx, err := db.Begin()
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.
1139 if tx
.db
!= stmt
.db
{
1140 return &Stmt
{stickyErr
: errors
.New("sql: Tx.Stmt: statement from different database used")}
1142 dc
, err
:= tx
.grabConn()
1144 return &Stmt
{stickyErr
: err
}
1147 si
, err
:= dc
.ci
.Prepare(stmt
.query
)
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()
1169 if execer
, ok
:= dc
.ci
.(driver
.Execer
); ok
{
1170 dargs
, err
:= driverArgs(nil, args
)
1175 resi
, err
:= execer
.Exec(query
, dargs
)
1178 return driverResult
{dc
, resi
}, nil
1180 if err
!= driver
.ErrSkip
{
1186 si
, err
:= dc
.ci
.Prepare(query
)
1191 defer withLock(dc
, func() { si
.Close() })
1193 return resultFromStatement(driverStmt
{dc
, si
}, args
...)
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()
1202 releaseConn
:= func(error
) {}
1203 return tx
.db
.queryConn(dc
, releaseConn
, query
, args
)
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
}
1214 // connStmt is a prepared statement on a particular connection.
1215 type connStmt
struct {
1220 // Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
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
1227 closemu sync
.RWMutex
// held exclusively during close, for read otherwise.
1229 // If in a transaction, else both nil:
1233 mu sync
.Mutex
// protects the rest of the fields
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.
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
) {
1247 defer s
.closemu
.RUnlock()
1248 dc
, releaseConn
, si
, err
:= s
.connStmt()
1252 defer releaseConn(nil)
1254 return resultFromStatement(driverStmt
{dc
, si
}, args
...)
1257 func resultFromStatement(ds driverStmt
, args
...interface{}) (Result
, error
) {
1259 want
:= ds
.si
.NumInput()
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
))
1269 dargs
, err
:= driverArgs(&ds
, args
)
1275 resi
, err
:= ds
.si
.Exec(dargs
)
1280 return driverResult
{ds
.Locker
, resi
}, nil
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 {
1293 err
= errors
.New("sql: statement is closed")
1297 // In a transaction, we always use the connection that the
1298 // transaction was created on.
1301 ci
, err
= s
.tx
.grabConn() // blocks, waiting for the connection.
1305 releaseConn
= func(error
) {}
1306 return ci
, releaseConn
, s
.txsi
.si
, nil
1311 for i
:= 0; i
< len(s
.css
); i
++ {
1313 _
, err
:= s
.db
.connIfFree(v
.dc
)
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]
1329 // Make a new conn if all are busy.
1330 // TODO(bradfitz): or wait for one? make configurable later?
1333 dc
, err
:= s
.db
.conn()
1335 return nil, nil, nil, err
1338 si
, err
:= dc
.prepareLocked(s
.query
)
1340 if err
== driver
.ErrBadConn
&& i
< 10 {
1344 return nil, nil, nil, err
1347 cs
= connStmt
{dc
, si
}
1348 s
.css
= append(s
.css
, cs
)
1355 return conn
, conn
.releaseConn
, cs
.si
, nil
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
) {
1362 defer s
.closemu
.RUnlock()
1364 dc
, releaseConn
, si
, err
:= s
.connStmt()
1369 ds
:= driverStmt
{dc
, si
}
1370 rowsi
, err
:= rowsiFromStatement(ds
, args
...)
1376 // Note: ownership of ci passes to the *Rows, to be freed
1377 // with releaseConn.
1381 // releaseConn set below
1383 s
.db
.addDep(s
, rows
)
1384 rows
.releaseConn
= func(err error
) {
1386 s
.db
.removeDep(s
, rows
)
1391 func rowsiFromStatement(ds driverStmt
, args
...interface{}) (driver
.Rows
, error
) {
1393 want
:= ds
.si
.NumInput()
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
))
1403 dargs
, err
:= driverArgs(&ds
, args
)
1409 rowsi
, err
:= ds
.si
.Query(dargs
)
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
1427 // err := nameByUseridStmt.QueryRow(id).Scan(&name)
1428 func (s
*Stmt
) QueryRow(args
...interface{}) *Row
{
1429 rows
, err
:= s
.Query(args
...)
1431 return &Row
{err
: err
}
1433 return &Row
{rows
: rows
}
1436 // Close closes the statement.
1437 func (s
*Stmt
) Close() error
{
1439 defer s
.closemu
.Unlock()
1441 if s
.stickyErr
!= nil {
1458 return s
.db
.removeDep(s
, s
)
1461 func (s
*Stmt
) finalClose() error
{
1465 for _
, v
:= range s
.css
{
1466 s
.db
.noteUnusedDriverStatement(v
.dc
, v
.si
)
1467 v
.dc
.removeOpenStmt(v
.si
)
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:
1477 // rows, err := db.Query("SELECT ...")
1479 // for rows.Next() {
1482 // err = rows.Scan(&id, &name)
1485 // err = rows.Err() // get any error encountered during iteration
1488 dc
*driverConn
// owned; must call releaseConn when closed to release
1489 releaseConn
func(error
)
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
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
1502 func (rs
*Rows
) Next() bool {
1506 if rs
.lastcols
== nil {
1507 rs
.lastcols
= make([]driver
.Value
, len(rs
.rowsi
.Columns()))
1509 rs
.lasterr
= rs
.rowsi
.Next(rs
.lastcols
)
1510 if rs
.lasterr
!= nil {
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
{
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
) {
1531 return nil, errors
.New("sql: Rows are closed")
1533 if rs
.rowsi
== nil {
1534 return nil, errors
.New("sql: no Rows available")
1536 return rs
.rowsi
.Columns(), nil
1539 // Scan copies the columns in the current row into the values pointed
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.
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
{
1553 return errors
.New("sql: Rows are closed")
1555 if rs
.lastcols
== nil {
1556 return errors
.New("sql: Scan called without calling Next")
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
))
1561 for i
, sv
:= range rs
.lastcols
{
1562 err
:= convertAssign(dest
[i
], sv
)
1564 return fmt
.Errorf("sql: Scan error on column index %d: %v", i
, err
)
1570 var rowsCloseHook
func(*Rows
, *error
)
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
{
1580 err
:= rs
.rowsi
.Close()
1581 if fn
:= rowsCloseHook
; fn
!= nil {
1584 if rs
.closeStmt
!= nil {
1585 rs
.closeStmt
.Close()
1591 // Row is the result of calling QueryRow to select a single row.
1593 // One of these two will be non-nil:
1594 err error
// deferred error for easy chaining
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
{
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
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")
1630 err
:= r
.rows
.Scan(dest
...)
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
)
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
)
1653 type driverResult
struct {
1654 sync
.Locker
// the *driverConn
1658 func (dr driverResult
) LastInsertId() (int64, error
) {
1661 return dr
.resi
.LastInsertId()
1664 func (dr driverResult
) RowsAffected() (int64, error
) {
1667 return dr
.resi
.RowsAffected()
1670 func stack() string {
1671 var buf
[2 << 10]byte
1672 return string(buf
[:runtime
.Stack(buf
[:], false)])
1675 // withLock runs while holding lk.
1676 func withLock(lk sync
.Locker
, fn
func()) {