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