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