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