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