github.com/mtsmfm/go/src@v0.0.0-20221020090648-44bdcb9f8fde/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 // Drivers that do not support context cancellation will not return until 12 // after the query is completed. 13 // 14 // For usage examples, see the wiki page at 15 // https://golang.org/s/sqlwiki. 16 package sql 17 18 import ( 19 "context" 20 "database/sql/driver" 21 "errors" 22 "fmt" 23 "io" 24 "reflect" 25 "runtime" 26 "sort" 27 "strconv" 28 "sync" 29 "sync/atomic" 30 "time" 31 ) 32 33 var ( 34 driversMu sync.RWMutex 35 drivers = make(map[string]driver.Driver) 36 ) 37 38 // nowFunc returns the current time; it's overridden in tests. 39 var nowFunc = time.Now 40 41 // Register makes a database driver available by the provided name. 42 // If Register is called twice with the same name or if driver is nil, 43 // it panics. 44 func Register(name string, driver driver.Driver) { 45 driversMu.Lock() 46 defer driversMu.Unlock() 47 if driver == nil { 48 panic("sql: Register driver is nil") 49 } 50 if _, dup := drivers[name]; dup { 51 panic("sql: Register called twice for driver " + name) 52 } 53 drivers[name] = driver 54 } 55 56 func unregisterAllDrivers() { 57 driversMu.Lock() 58 defer driversMu.Unlock() 59 // For tests. 60 drivers = make(map[string]driver.Driver) 61 } 62 63 // Drivers returns a sorted list of the names of the registered drivers. 64 func Drivers() []string { 65 driversMu.RLock() 66 defer driversMu.RUnlock() 67 list := make([]string, 0, len(drivers)) 68 for name := range drivers { 69 list = append(list, name) 70 } 71 sort.Strings(list) 72 return list 73 } 74 75 // A NamedArg is a named argument. NamedArg values may be used as 76 // arguments to Query or Exec and bind to the corresponding named 77 // parameter in the SQL statement. 78 // 79 // For a more concise way to create NamedArg values, see 80 // the Named function. 81 type NamedArg struct { 82 _NamedFieldsRequired struct{} 83 84 // Name is the name of the parameter placeholder. 85 // 86 // If empty, the ordinal position in the argument list will be 87 // used. 88 // 89 // Name must omit any symbol prefix. 90 Name string 91 92 // Value is the value of the parameter. 93 // It may be assigned the same value types as the query 94 // arguments. 95 Value any 96 } 97 98 // Named provides a more concise way to create NamedArg values. 99 // 100 // Example usage: 101 // 102 // db.ExecContext(ctx, ` 103 // delete from Invoice 104 // where 105 // TimeCreated < @end 106 // and TimeCreated >= @start;`, 107 // sql.Named("start", startTime), 108 // sql.Named("end", endTime), 109 // ) 110 func Named(name string, value any) NamedArg { 111 // This method exists because the go1compat promise 112 // doesn't guarantee that structs don't grow more fields, 113 // so unkeyed struct literals are a vet error. Thus, we don't 114 // want to allow sql.NamedArg{name, value}. 115 return NamedArg{Name: name, Value: value} 116 } 117 118 // IsolationLevel is the transaction isolation level used in TxOptions. 119 type IsolationLevel int 120 121 // Various isolation levels that drivers may support in BeginTx. 122 // If a driver does not support a given isolation level an error may be returned. 123 // 124 // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels. 125 const ( 126 LevelDefault IsolationLevel = iota 127 LevelReadUncommitted 128 LevelReadCommitted 129 LevelWriteCommitted 130 LevelRepeatableRead 131 LevelSnapshot 132 LevelSerializable 133 LevelLinearizable 134 ) 135 136 // String returns the name of the transaction isolation level. 137 func (i IsolationLevel) String() string { 138 switch i { 139 case LevelDefault: 140 return "Default" 141 case LevelReadUncommitted: 142 return "Read Uncommitted" 143 case LevelReadCommitted: 144 return "Read Committed" 145 case LevelWriteCommitted: 146 return "Write Committed" 147 case LevelRepeatableRead: 148 return "Repeatable Read" 149 case LevelSnapshot: 150 return "Snapshot" 151 case LevelSerializable: 152 return "Serializable" 153 case LevelLinearizable: 154 return "Linearizable" 155 default: 156 return "IsolationLevel(" + strconv.Itoa(int(i)) + ")" 157 } 158 } 159 160 var _ fmt.Stringer = LevelDefault 161 162 // TxOptions holds the transaction options to be used in DB.BeginTx. 163 type TxOptions struct { 164 // Isolation is the transaction isolation level. 165 // If zero, the driver or database's default level is used. 166 Isolation IsolationLevel 167 ReadOnly bool 168 } 169 170 // RawBytes is a byte slice that holds a reference to memory owned by 171 // the database itself. After a Scan into a RawBytes, the slice is only 172 // valid until the next call to Next, Scan, or Close. 173 type RawBytes []byte 174 175 // NullString represents a string that may be null. 176 // NullString implements the Scanner interface so 177 // it can be used as a scan destination: 178 // 179 // var s NullString 180 // err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s) 181 // ... 182 // if s.Valid { 183 // // use s.String 184 // } else { 185 // // NULL value 186 // } 187 type NullString struct { 188 String string 189 Valid bool // Valid is true if String is not NULL 190 } 191 192 // Scan implements the Scanner interface. 193 func (ns *NullString) Scan(value any) error { 194 if value == nil { 195 ns.String, ns.Valid = "", false 196 return nil 197 } 198 ns.Valid = true 199 return convertAssign(&ns.String, value) 200 } 201 202 // Value implements the driver Valuer interface. 203 func (ns NullString) Value() (driver.Value, error) { 204 if !ns.Valid { 205 return nil, nil 206 } 207 return ns.String, nil 208 } 209 210 // NullInt64 represents an int64 that may be null. 211 // NullInt64 implements the Scanner interface so 212 // it can be used as a scan destination, similar to NullString. 213 type NullInt64 struct { 214 Int64 int64 215 Valid bool // Valid is true if Int64 is not NULL 216 } 217 218 // Scan implements the Scanner interface. 219 func (n *NullInt64) Scan(value any) error { 220 if value == nil { 221 n.Int64, n.Valid = 0, false 222 return nil 223 } 224 n.Valid = true 225 return convertAssign(&n.Int64, value) 226 } 227 228 // Value implements the driver Valuer interface. 229 func (n NullInt64) Value() (driver.Value, error) { 230 if !n.Valid { 231 return nil, nil 232 } 233 return n.Int64, nil 234 } 235 236 // NullInt32 represents an int32 that may be null. 237 // NullInt32 implements the Scanner interface so 238 // it can be used as a scan destination, similar to NullString. 239 type NullInt32 struct { 240 Int32 int32 241 Valid bool // Valid is true if Int32 is not NULL 242 } 243 244 // Scan implements the Scanner interface. 245 func (n *NullInt32) Scan(value any) error { 246 if value == nil { 247 n.Int32, n.Valid = 0, false 248 return nil 249 } 250 n.Valid = true 251 return convertAssign(&n.Int32, value) 252 } 253 254 // Value implements the driver Valuer interface. 255 func (n NullInt32) Value() (driver.Value, error) { 256 if !n.Valid { 257 return nil, nil 258 } 259 return int64(n.Int32), nil 260 } 261 262 // NullInt16 represents an int16 that may be null. 263 // NullInt16 implements the Scanner interface so 264 // it can be used as a scan destination, similar to NullString. 265 type NullInt16 struct { 266 Int16 int16 267 Valid bool // Valid is true if Int16 is not NULL 268 } 269 270 // Scan implements the Scanner interface. 271 func (n *NullInt16) Scan(value any) error { 272 if value == nil { 273 n.Int16, n.Valid = 0, false 274 return nil 275 } 276 err := convertAssign(&n.Int16, value) 277 n.Valid = err == nil 278 return err 279 } 280 281 // Value implements the driver Valuer interface. 282 func (n NullInt16) Value() (driver.Value, error) { 283 if !n.Valid { 284 return nil, nil 285 } 286 return int64(n.Int16), nil 287 } 288 289 // NullByte represents a byte that may be null. 290 // NullByte implements the Scanner interface so 291 // it can be used as a scan destination, similar to NullString. 292 type NullByte struct { 293 Byte byte 294 Valid bool // Valid is true if Byte is not NULL 295 } 296 297 // Scan implements the Scanner interface. 298 func (n *NullByte) Scan(value any) error { 299 if value == nil { 300 n.Byte, n.Valid = 0, false 301 return nil 302 } 303 err := convertAssign(&n.Byte, value) 304 n.Valid = err == nil 305 return err 306 } 307 308 // Value implements the driver Valuer interface. 309 func (n NullByte) Value() (driver.Value, error) { 310 if !n.Valid { 311 return nil, nil 312 } 313 return int64(n.Byte), nil 314 } 315 316 // NullFloat64 represents a float64 that may be null. 317 // NullFloat64 implements the Scanner interface so 318 // it can be used as a scan destination, similar to NullString. 319 type NullFloat64 struct { 320 Float64 float64 321 Valid bool // Valid is true if Float64 is not NULL 322 } 323 324 // Scan implements the Scanner interface. 325 func (n *NullFloat64) Scan(value any) error { 326 if value == nil { 327 n.Float64, n.Valid = 0, false 328 return nil 329 } 330 n.Valid = true 331 return convertAssign(&n.Float64, value) 332 } 333 334 // Value implements the driver Valuer interface. 335 func (n NullFloat64) Value() (driver.Value, error) { 336 if !n.Valid { 337 return nil, nil 338 } 339 return n.Float64, nil 340 } 341 342 // NullBool represents a bool that may be null. 343 // NullBool implements the Scanner interface so 344 // it can be used as a scan destination, similar to NullString. 345 type NullBool struct { 346 Bool bool 347 Valid bool // Valid is true if Bool is not NULL 348 } 349 350 // Scan implements the Scanner interface. 351 func (n *NullBool) Scan(value any) error { 352 if value == nil { 353 n.Bool, n.Valid = false, false 354 return nil 355 } 356 n.Valid = true 357 return convertAssign(&n.Bool, value) 358 } 359 360 // Value implements the driver Valuer interface. 361 func (n NullBool) Value() (driver.Value, error) { 362 if !n.Valid { 363 return nil, nil 364 } 365 return n.Bool, nil 366 } 367 368 // NullTime represents a time.Time that may be null. 369 // NullTime implements the Scanner interface so 370 // it can be used as a scan destination, similar to NullString. 371 type NullTime struct { 372 Time time.Time 373 Valid bool // Valid is true if Time is not NULL 374 } 375 376 // Scan implements the Scanner interface. 377 func (n *NullTime) Scan(value any) error { 378 if value == nil { 379 n.Time, n.Valid = time.Time{}, false 380 return nil 381 } 382 n.Valid = true 383 return convertAssign(&n.Time, value) 384 } 385 386 // Value implements the driver Valuer interface. 387 func (n NullTime) Value() (driver.Value, error) { 388 if !n.Valid { 389 return nil, nil 390 } 391 return n.Time, nil 392 } 393 394 // Scanner is an interface used by Scan. 395 type Scanner interface { 396 // Scan assigns a value from a database driver. 397 // 398 // The src value will be of one of the following types: 399 // 400 // int64 401 // float64 402 // bool 403 // []byte 404 // string 405 // time.Time 406 // nil - for NULL values 407 // 408 // An error should be returned if the value cannot be stored 409 // without loss of information. 410 // 411 // Reference types such as []byte are only valid until the next call to Scan 412 // and should not be retained. Their underlying memory is owned by the driver. 413 // If retention is necessary, copy their values before the next call to Scan. 414 Scan(src any) error 415 } 416 417 // Out may be used to retrieve OUTPUT value parameters from stored procedures. 418 // 419 // Not all drivers and databases support OUTPUT value parameters. 420 // 421 // Example usage: 422 // 423 // var outArg string 424 // _, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", sql.Out{Dest: &outArg})) 425 type Out struct { 426 _NamedFieldsRequired struct{} 427 428 // Dest is a pointer to the value that will be set to the result of the 429 // stored procedure's OUTPUT parameter. 430 Dest any 431 432 // In is whether the parameter is an INOUT parameter. If so, the input value to the stored 433 // procedure is the dereferenced value of Dest's pointer, which is then replaced with 434 // the output value. 435 In bool 436 } 437 438 // ErrNoRows is returned by Scan when QueryRow doesn't return a 439 // row. In such a case, QueryRow returns a placeholder *Row value that 440 // defers this error until a Scan. 441 var ErrNoRows = errors.New("sql: no rows in result set") 442 443 // DB is a database handle representing a pool of zero or more 444 // underlying connections. It's safe for concurrent use by multiple 445 // goroutines. 446 // 447 // The sql package creates and frees connections automatically; it 448 // also maintains a free pool of idle connections. If the database has 449 // a concept of per-connection state, such state can be reliably observed 450 // within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the 451 // returned Tx is bound to a single connection. Once Commit or 452 // Rollback is called on the transaction, that transaction's 453 // connection is returned to DB's idle connection pool. The pool size 454 // can be controlled with SetMaxIdleConns. 455 type DB struct { 456 // Total time waited for new connections. 457 waitDuration atomic.Int64 458 459 connector driver.Connector 460 // numClosed is an atomic counter which represents a total number of 461 // closed connections. Stmt.openStmt checks it before cleaning closed 462 // connections in Stmt.css. 463 numClosed atomic.Uint64 464 465 mu sync.Mutex // protects following fields 466 freeConn []*driverConn // free connections ordered by returnedAt oldest to newest 467 connRequests map[uint64]chan connRequest 468 nextRequest uint64 // Next key to use in connRequests. 469 numOpen int // number of opened and pending open connections 470 // Used to signal the need for new connections 471 // a goroutine running connectionOpener() reads on this chan and 472 // maybeOpenNewConnections sends on the chan (one send per needed connection) 473 // It is closed during db.Close(). The close tells the connectionOpener 474 // goroutine to exit. 475 openerCh chan struct{} 476 closed bool 477 dep map[finalCloser]depSet 478 lastPut map[*driverConn]string // stacktrace of last conn's put; debug only 479 maxIdleCount int // zero means defaultMaxIdleConns; negative means 0 480 maxOpen int // <= 0 means unlimited 481 maxLifetime time.Duration // maximum amount of time a connection may be reused 482 maxIdleTime time.Duration // maximum amount of time a connection may be idle before being closed 483 cleanerCh chan struct{} 484 waitCount int64 // Total number of connections waited for. 485 maxIdleClosed int64 // Total number of connections closed due to idle count. 486 maxIdleTimeClosed int64 // Total number of connections closed due to idle time. 487 maxLifetimeClosed int64 // Total number of connections closed due to max connection lifetime limit. 488 489 stop func() // stop cancels the connection opener. 490 } 491 492 // connReuseStrategy determines how (*DB).conn returns database connections. 493 type connReuseStrategy uint8 494 495 const ( 496 // alwaysNewConn forces a new connection to the database. 497 alwaysNewConn connReuseStrategy = iota 498 // cachedOrNewConn returns a cached connection, if available, else waits 499 // for one to become available (if MaxOpenConns has been reached) or 500 // creates a new database connection. 501 cachedOrNewConn 502 ) 503 504 // driverConn wraps a driver.Conn with a mutex, to 505 // be held during all calls into the Conn. (including any calls onto 506 // interfaces returned via that Conn, such as calls on Tx, Stmt, 507 // Result, Rows) 508 type driverConn struct { 509 db *DB 510 createdAt time.Time 511 512 sync.Mutex // guards following 513 ci driver.Conn 514 needReset bool // The connection session should be reset before use if true. 515 closed bool 516 finalClosed bool // ci.Close has been called 517 openStmt map[*driverStmt]bool 518 519 // guarded by db.mu 520 inUse bool 521 returnedAt time.Time // Time the connection was created or returned. 522 onPut []func() // code (with db.mu held) run when conn is next returned 523 dbmuClosed bool // same as closed, but guarded by db.mu, for removeClosedStmtLocked 524 } 525 526 func (dc *driverConn) releaseConn(err error) { 527 dc.db.putConn(dc, err, true) 528 } 529 530 func (dc *driverConn) removeOpenStmt(ds *driverStmt) { 531 dc.Lock() 532 defer dc.Unlock() 533 delete(dc.openStmt, ds) 534 } 535 536 func (dc *driverConn) expired(timeout time.Duration) bool { 537 if timeout <= 0 { 538 return false 539 } 540 return dc.createdAt.Add(timeout).Before(nowFunc()) 541 } 542 543 // resetSession checks if the driver connection needs the 544 // session to be reset and if required, resets it. 545 func (dc *driverConn) resetSession(ctx context.Context) error { 546 dc.Lock() 547 defer dc.Unlock() 548 549 if !dc.needReset { 550 return nil 551 } 552 if cr, ok := dc.ci.(driver.SessionResetter); ok { 553 return cr.ResetSession(ctx) 554 } 555 return nil 556 } 557 558 // validateConnection checks if the connection is valid and can 559 // still be used. It also marks the session for reset if required. 560 func (dc *driverConn) validateConnection(needsReset bool) bool { 561 dc.Lock() 562 defer dc.Unlock() 563 564 if needsReset { 565 dc.needReset = true 566 } 567 if cv, ok := dc.ci.(driver.Validator); ok { 568 return cv.IsValid() 569 } 570 return true 571 } 572 573 // prepareLocked prepares the query on dc. When cg == nil the dc must keep track of 574 // the prepared statements in a pool. 575 func (dc *driverConn) prepareLocked(ctx context.Context, cg stmtConnGrabber, query string) (*driverStmt, error) { 576 si, err := ctxDriverPrepare(ctx, dc.ci, query) 577 if err != nil { 578 return nil, err 579 } 580 ds := &driverStmt{Locker: dc, si: si} 581 582 // No need to manage open statements if there is a single connection grabber. 583 if cg != nil { 584 return ds, nil 585 } 586 587 // Track each driverConn's open statements, so we can close them 588 // before closing the conn. 589 // 590 // Wrap all driver.Stmt is *driverStmt to ensure they are only closed once. 591 if dc.openStmt == nil { 592 dc.openStmt = make(map[*driverStmt]bool) 593 } 594 dc.openStmt[ds] = true 595 return ds, nil 596 } 597 598 // the dc.db's Mutex is held. 599 func (dc *driverConn) closeDBLocked() func() error { 600 dc.Lock() 601 defer dc.Unlock() 602 if dc.closed { 603 return func() error { return errors.New("sql: duplicate driverConn close") } 604 } 605 dc.closed = true 606 return dc.db.removeDepLocked(dc, dc) 607 } 608 609 func (dc *driverConn) Close() error { 610 dc.Lock() 611 if dc.closed { 612 dc.Unlock() 613 return errors.New("sql: duplicate driverConn close") 614 } 615 dc.closed = true 616 dc.Unlock() // not defer; removeDep finalClose calls may need to lock 617 618 // And now updates that require holding dc.mu.Lock. 619 dc.db.mu.Lock() 620 dc.dbmuClosed = true 621 fn := dc.db.removeDepLocked(dc, dc) 622 dc.db.mu.Unlock() 623 return fn() 624 } 625 626 func (dc *driverConn) finalClose() error { 627 var err error 628 629 // Each *driverStmt has a lock to the dc. Copy the list out of the dc 630 // before calling close on each stmt. 631 var openStmt []*driverStmt 632 withLock(dc, func() { 633 openStmt = make([]*driverStmt, 0, len(dc.openStmt)) 634 for ds := range dc.openStmt { 635 openStmt = append(openStmt, ds) 636 } 637 dc.openStmt = nil 638 }) 639 for _, ds := range openStmt { 640 ds.Close() 641 } 642 withLock(dc, func() { 643 dc.finalClosed = true 644 err = dc.ci.Close() 645 dc.ci = nil 646 }) 647 648 dc.db.mu.Lock() 649 dc.db.numOpen-- 650 dc.db.maybeOpenNewConnections() 651 dc.db.mu.Unlock() 652 653 dc.db.numClosed.Add(1) 654 return err 655 } 656 657 // driverStmt associates a driver.Stmt with the 658 // *driverConn from which it came, so the driverConn's lock can be 659 // held during calls. 660 type driverStmt struct { 661 sync.Locker // the *driverConn 662 si driver.Stmt 663 closed bool 664 closeErr error // return value of previous Close call 665 } 666 667 // Close ensures driver.Stmt is only closed once and always returns the same 668 // result. 669 func (ds *driverStmt) Close() error { 670 ds.Lock() 671 defer ds.Unlock() 672 if ds.closed { 673 return ds.closeErr 674 } 675 ds.closed = true 676 ds.closeErr = ds.si.Close() 677 return ds.closeErr 678 } 679 680 // depSet is a finalCloser's outstanding dependencies 681 type depSet map[any]bool // set of true bools 682 683 // The finalCloser interface is used by (*DB).addDep and related 684 // dependency reference counting. 685 type finalCloser interface { 686 // finalClose is called when the reference count of an object 687 // goes to zero. (*DB).mu is not held while calling it. 688 finalClose() error 689 } 690 691 // addDep notes that x now depends on dep, and x's finalClose won't be 692 // called until all of x's dependencies are removed with removeDep. 693 func (db *DB) addDep(x finalCloser, dep any) { 694 db.mu.Lock() 695 defer db.mu.Unlock() 696 db.addDepLocked(x, dep) 697 } 698 699 func (db *DB) addDepLocked(x finalCloser, dep any) { 700 if db.dep == nil { 701 db.dep = make(map[finalCloser]depSet) 702 } 703 xdep := db.dep[x] 704 if xdep == nil { 705 xdep = make(depSet) 706 db.dep[x] = xdep 707 } 708 xdep[dep] = true 709 } 710 711 // removeDep notes that x no longer depends on dep. 712 // If x still has dependencies, nil is returned. 713 // If x no longer has any dependencies, its finalClose method will be 714 // called and its error value will be returned. 715 func (db *DB) removeDep(x finalCloser, dep any) error { 716 db.mu.Lock() 717 fn := db.removeDepLocked(x, dep) 718 db.mu.Unlock() 719 return fn() 720 } 721 722 func (db *DB) removeDepLocked(x finalCloser, dep any) func() error { 723 xdep, ok := db.dep[x] 724 if !ok { 725 panic(fmt.Sprintf("unpaired removeDep: no deps for %T", x)) 726 } 727 728 l0 := len(xdep) 729 delete(xdep, dep) 730 731 switch len(xdep) { 732 case l0: 733 // Nothing removed. Shouldn't happen. 734 panic(fmt.Sprintf("unpaired removeDep: no %T dep on %T", dep, x)) 735 case 0: 736 // No more dependencies. 737 delete(db.dep, x) 738 return x.finalClose 739 default: 740 // Dependencies remain. 741 return func() error { return nil } 742 } 743 } 744 745 // This is the size of the connectionOpener request chan (DB.openerCh). 746 // This value should be larger than the maximum typical value 747 // used for db.maxOpen. If maxOpen is significantly larger than 748 // connectionRequestQueueSize then it is possible for ALL calls into the *DB 749 // to block until the connectionOpener can satisfy the backlog of requests. 750 var connectionRequestQueueSize = 1000000 751 752 type dsnConnector struct { 753 dsn string 754 driver driver.Driver 755 } 756 757 func (t dsnConnector) Connect(_ context.Context) (driver.Conn, error) { 758 return t.driver.Open(t.dsn) 759 } 760 761 func (t dsnConnector) Driver() driver.Driver { 762 return t.driver 763 } 764 765 // OpenDB opens a database using a Connector, allowing drivers to 766 // bypass a string based data source name. 767 // 768 // Most users will open a database via a driver-specific connection 769 // helper function that returns a *DB. No database drivers are included 770 // in the Go standard library. See https://golang.org/s/sqldrivers for 771 // a list of third-party drivers. 772 // 773 // OpenDB may just validate its arguments without creating a connection 774 // to the database. To verify that the data source name is valid, call 775 // Ping. 776 // 777 // The returned DB is safe for concurrent use by multiple goroutines 778 // and maintains its own pool of idle connections. Thus, the OpenDB 779 // function should be called just once. It is rarely necessary to 780 // close a DB. 781 func OpenDB(c driver.Connector) *DB { 782 ctx, cancel := context.WithCancel(context.Background()) 783 db := &DB{ 784 connector: c, 785 openerCh: make(chan struct{}, connectionRequestQueueSize), 786 lastPut: make(map[*driverConn]string), 787 connRequests: make(map[uint64]chan connRequest), 788 stop: cancel, 789 } 790 791 go db.connectionOpener(ctx) 792 793 return db 794 } 795 796 // Open opens a database specified by its database driver name and a 797 // driver-specific data source name, usually consisting of at least a 798 // database name and connection information. 799 // 800 // Most users will open a database via a driver-specific connection 801 // helper function that returns a *DB. No database drivers are included 802 // in the Go standard library. See https://golang.org/s/sqldrivers for 803 // a list of third-party drivers. 804 // 805 // Open may just validate its arguments without creating a connection 806 // to the database. To verify that the data source name is valid, call 807 // Ping. 808 // 809 // The returned DB is safe for concurrent use by multiple goroutines 810 // and maintains its own pool of idle connections. Thus, the Open 811 // function should be called just once. It is rarely necessary to 812 // close a DB. 813 func Open(driverName, dataSourceName string) (*DB, error) { 814 driversMu.RLock() 815 driveri, ok := drivers[driverName] 816 driversMu.RUnlock() 817 if !ok { 818 return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName) 819 } 820 821 if driverCtx, ok := driveri.(driver.DriverContext); ok { 822 connector, err := driverCtx.OpenConnector(dataSourceName) 823 if err != nil { 824 return nil, err 825 } 826 return OpenDB(connector), nil 827 } 828 829 return OpenDB(dsnConnector{dsn: dataSourceName, driver: driveri}), nil 830 } 831 832 func (db *DB) pingDC(ctx context.Context, dc *driverConn, release func(error)) error { 833 var err error 834 if pinger, ok := dc.ci.(driver.Pinger); ok { 835 withLock(dc, func() { 836 err = pinger.Ping(ctx) 837 }) 838 } 839 release(err) 840 return err 841 } 842 843 // PingContext verifies a connection to the database is still alive, 844 // establishing a connection if necessary. 845 func (db *DB) PingContext(ctx context.Context) error { 846 var dc *driverConn 847 var err error 848 849 err = db.retry(func(strategy connReuseStrategy) error { 850 dc, err = db.conn(ctx, strategy) 851 return err 852 }) 853 854 if err != nil { 855 return err 856 } 857 858 return db.pingDC(ctx, dc, dc.releaseConn) 859 } 860 861 // Ping verifies a connection to the database is still alive, 862 // establishing a connection if necessary. 863 // 864 // Ping uses context.Background internally; to specify the context, use 865 // PingContext. 866 func (db *DB) Ping() error { 867 return db.PingContext(context.Background()) 868 } 869 870 // Close closes the database and prevents new queries from starting. 871 // Close then waits for all queries that have started processing on the server 872 // to finish. 873 // 874 // It is rare to Close a DB, as the DB handle is meant to be 875 // long-lived and shared between many goroutines. 876 func (db *DB) Close() error { 877 db.mu.Lock() 878 if db.closed { // Make DB.Close idempotent 879 db.mu.Unlock() 880 return nil 881 } 882 if db.cleanerCh != nil { 883 close(db.cleanerCh) 884 } 885 var err error 886 fns := make([]func() error, 0, len(db.freeConn)) 887 for _, dc := range db.freeConn { 888 fns = append(fns, dc.closeDBLocked()) 889 } 890 db.freeConn = nil 891 db.closed = true 892 for _, req := range db.connRequests { 893 close(req) 894 } 895 db.mu.Unlock() 896 for _, fn := range fns { 897 err1 := fn() 898 if err1 != nil { 899 err = err1 900 } 901 } 902 db.stop() 903 if c, ok := db.connector.(io.Closer); ok { 904 err1 := c.Close() 905 if err1 != nil { 906 err = err1 907 } 908 } 909 return err 910 } 911 912 const defaultMaxIdleConns = 2 913 914 func (db *DB) maxIdleConnsLocked() int { 915 n := db.maxIdleCount 916 switch { 917 case n == 0: 918 // TODO(bradfitz): ask driver, if supported, for its default preference 919 return defaultMaxIdleConns 920 case n < 0: 921 return 0 922 default: 923 return n 924 } 925 } 926 927 func (db *DB) shortestIdleTimeLocked() time.Duration { 928 if db.maxIdleTime <= 0 { 929 return db.maxLifetime 930 } 931 if db.maxLifetime <= 0 { 932 return db.maxIdleTime 933 } 934 935 min := db.maxIdleTime 936 if min > db.maxLifetime { 937 min = db.maxLifetime 938 } 939 return min 940 } 941 942 // SetMaxIdleConns sets the maximum number of connections in the idle 943 // connection pool. 944 // 945 // If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, 946 // then the new MaxIdleConns will be reduced to match the MaxOpenConns limit. 947 // 948 // If n <= 0, no idle connections are retained. 949 // 950 // The default max idle connections is currently 2. This may change in 951 // a future release. 952 func (db *DB) SetMaxIdleConns(n int) { 953 db.mu.Lock() 954 if n > 0 { 955 db.maxIdleCount = n 956 } else { 957 // No idle connections. 958 db.maxIdleCount = -1 959 } 960 // Make sure maxIdle doesn't exceed maxOpen 961 if db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen { 962 db.maxIdleCount = db.maxOpen 963 } 964 var closing []*driverConn 965 idleCount := len(db.freeConn) 966 maxIdle := db.maxIdleConnsLocked() 967 if idleCount > maxIdle { 968 closing = db.freeConn[maxIdle:] 969 db.freeConn = db.freeConn[:maxIdle] 970 } 971 db.maxIdleClosed += int64(len(closing)) 972 db.mu.Unlock() 973 for _, c := range closing { 974 c.Close() 975 } 976 } 977 978 // SetMaxOpenConns sets the maximum number of open connections to the database. 979 // 980 // If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than 981 // MaxIdleConns, then MaxIdleConns will be reduced to match the new 982 // MaxOpenConns limit. 983 // 984 // If n <= 0, then there is no limit on the number of open connections. 985 // The default is 0 (unlimited). 986 func (db *DB) SetMaxOpenConns(n int) { 987 db.mu.Lock() 988 db.maxOpen = n 989 if n < 0 { 990 db.maxOpen = 0 991 } 992 syncMaxIdle := db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen 993 db.mu.Unlock() 994 if syncMaxIdle { 995 db.SetMaxIdleConns(n) 996 } 997 } 998 999 // SetConnMaxLifetime sets the maximum amount of time a connection may be reused. 1000 // 1001 // Expired connections may be closed lazily before reuse. 1002 // 1003 // If d <= 0, connections are not closed due to a connection's age. 1004 func (db *DB) SetConnMaxLifetime(d time.Duration) { 1005 if d < 0 { 1006 d = 0 1007 } 1008 db.mu.Lock() 1009 // Wake cleaner up when lifetime is shortened. 1010 if d > 0 && d < db.maxLifetime && db.cleanerCh != nil { 1011 select { 1012 case db.cleanerCh <- struct{}{}: 1013 default: 1014 } 1015 } 1016 db.maxLifetime = d 1017 db.startCleanerLocked() 1018 db.mu.Unlock() 1019 } 1020 1021 // SetConnMaxIdleTime sets the maximum amount of time a connection may be idle. 1022 // 1023 // Expired connections may be closed lazily before reuse. 1024 // 1025 // If d <= 0, connections are not closed due to a connection's idle time. 1026 func (db *DB) SetConnMaxIdleTime(d time.Duration) { 1027 if d < 0 { 1028 d = 0 1029 } 1030 db.mu.Lock() 1031 defer db.mu.Unlock() 1032 1033 // Wake cleaner up when idle time is shortened. 1034 if d > 0 && d < db.maxIdleTime && db.cleanerCh != nil { 1035 select { 1036 case db.cleanerCh <- struct{}{}: 1037 default: 1038 } 1039 } 1040 db.maxIdleTime = d 1041 db.startCleanerLocked() 1042 } 1043 1044 // startCleanerLocked starts connectionCleaner if needed. 1045 func (db *DB) startCleanerLocked() { 1046 if (db.maxLifetime > 0 || db.maxIdleTime > 0) && db.numOpen > 0 && db.cleanerCh == nil { 1047 db.cleanerCh = make(chan struct{}, 1) 1048 go db.connectionCleaner(db.shortestIdleTimeLocked()) 1049 } 1050 } 1051 1052 func (db *DB) connectionCleaner(d time.Duration) { 1053 const minInterval = time.Second 1054 1055 if d < minInterval { 1056 d = minInterval 1057 } 1058 t := time.NewTimer(d) 1059 1060 for { 1061 select { 1062 case <-t.C: 1063 case <-db.cleanerCh: // maxLifetime was changed or db was closed. 1064 } 1065 1066 db.mu.Lock() 1067 1068 d = db.shortestIdleTimeLocked() 1069 if db.closed || db.numOpen == 0 || d <= 0 { 1070 db.cleanerCh = nil 1071 db.mu.Unlock() 1072 return 1073 } 1074 1075 d, closing := db.connectionCleanerRunLocked(d) 1076 db.mu.Unlock() 1077 for _, c := range closing { 1078 c.Close() 1079 } 1080 1081 if d < minInterval { 1082 d = minInterval 1083 } 1084 1085 if !t.Stop() { 1086 select { 1087 case <-t.C: 1088 default: 1089 } 1090 } 1091 t.Reset(d) 1092 } 1093 } 1094 1095 // connectionCleanerRunLocked removes connections that should be closed from 1096 // freeConn and returns them along side an updated duration to the next check 1097 // if a quicker check is required to ensure connections are checked appropriately. 1098 func (db *DB) connectionCleanerRunLocked(d time.Duration) (time.Duration, []*driverConn) { 1099 var idleClosing int64 1100 var closing []*driverConn 1101 if db.maxIdleTime > 0 { 1102 // As freeConn is ordered by returnedAt process 1103 // in reverse order to minimise the work needed. 1104 idleSince := nowFunc().Add(-db.maxIdleTime) 1105 last := len(db.freeConn) - 1 1106 for i := last; i >= 0; i-- { 1107 c := db.freeConn[i] 1108 if c.returnedAt.Before(idleSince) { 1109 i++ 1110 closing = db.freeConn[:i:i] 1111 db.freeConn = db.freeConn[i:] 1112 idleClosing = int64(len(closing)) 1113 db.maxIdleTimeClosed += idleClosing 1114 break 1115 } 1116 } 1117 1118 if len(db.freeConn) > 0 { 1119 c := db.freeConn[0] 1120 if d2 := c.returnedAt.Sub(idleSince); d2 < d { 1121 // Ensure idle connections are cleaned up as soon as 1122 // possible. 1123 d = d2 1124 } 1125 } 1126 } 1127 1128 if db.maxLifetime > 0 { 1129 expiredSince := nowFunc().Add(-db.maxLifetime) 1130 for i := 0; i < len(db.freeConn); i++ { 1131 c := db.freeConn[i] 1132 if c.createdAt.Before(expiredSince) { 1133 closing = append(closing, c) 1134 1135 last := len(db.freeConn) - 1 1136 // Use slow delete as order is required to ensure 1137 // connections are reused least idle time first. 1138 copy(db.freeConn[i:], db.freeConn[i+1:]) 1139 db.freeConn[last] = nil 1140 db.freeConn = db.freeConn[:last] 1141 i-- 1142 } else if d2 := c.createdAt.Sub(expiredSince); d2 < d { 1143 // Prevent connections sitting the freeConn when they 1144 // have expired by updating our next deadline d. 1145 d = d2 1146 } 1147 } 1148 db.maxLifetimeClosed += int64(len(closing)) - idleClosing 1149 } 1150 1151 return d, closing 1152 } 1153 1154 // DBStats contains database statistics. 1155 type DBStats struct { 1156 MaxOpenConnections int // Maximum number of open connections to the database. 1157 1158 // Pool Status 1159 OpenConnections int // The number of established connections both in use and idle. 1160 InUse int // The number of connections currently in use. 1161 Idle int // The number of idle connections. 1162 1163 // Counters 1164 WaitCount int64 // The total number of connections waited for. 1165 WaitDuration time.Duration // The total time blocked waiting for a new connection. 1166 MaxIdleClosed int64 // The total number of connections closed due to SetMaxIdleConns. 1167 MaxIdleTimeClosed int64 // The total number of connections closed due to SetConnMaxIdleTime. 1168 MaxLifetimeClosed int64 // The total number of connections closed due to SetConnMaxLifetime. 1169 } 1170 1171 // Stats returns database statistics. 1172 func (db *DB) Stats() DBStats { 1173 wait := db.waitDuration.Load() 1174 1175 db.mu.Lock() 1176 defer db.mu.Unlock() 1177 1178 stats := DBStats{ 1179 MaxOpenConnections: db.maxOpen, 1180 1181 Idle: len(db.freeConn), 1182 OpenConnections: db.numOpen, 1183 InUse: db.numOpen - len(db.freeConn), 1184 1185 WaitCount: db.waitCount, 1186 WaitDuration: time.Duration(wait), 1187 MaxIdleClosed: db.maxIdleClosed, 1188 MaxIdleTimeClosed: db.maxIdleTimeClosed, 1189 MaxLifetimeClosed: db.maxLifetimeClosed, 1190 } 1191 return stats 1192 } 1193 1194 // Assumes db.mu is locked. 1195 // If there are connRequests and the connection limit hasn't been reached, 1196 // then tell the connectionOpener to open new connections. 1197 func (db *DB) maybeOpenNewConnections() { 1198 numRequests := len(db.connRequests) 1199 if db.maxOpen > 0 { 1200 numCanOpen := db.maxOpen - db.numOpen 1201 if numRequests > numCanOpen { 1202 numRequests = numCanOpen 1203 } 1204 } 1205 for numRequests > 0 { 1206 db.numOpen++ // optimistically 1207 numRequests-- 1208 if db.closed { 1209 return 1210 } 1211 db.openerCh <- struct{}{} 1212 } 1213 } 1214 1215 // Runs in a separate goroutine, opens new connections when requested. 1216 func (db *DB) connectionOpener(ctx context.Context) { 1217 for { 1218 select { 1219 case <-ctx.Done(): 1220 return 1221 case <-db.openerCh: 1222 db.openNewConnection(ctx) 1223 } 1224 } 1225 } 1226 1227 // Open one new connection 1228 func (db *DB) openNewConnection(ctx context.Context) { 1229 // maybeOpenNewConnections has already executed db.numOpen++ before it sent 1230 // on db.openerCh. This function must execute db.numOpen-- if the 1231 // connection fails or is closed before returning. 1232 ci, err := db.connector.Connect(ctx) 1233 db.mu.Lock() 1234 defer db.mu.Unlock() 1235 if db.closed { 1236 if err == nil { 1237 ci.Close() 1238 } 1239 db.numOpen-- 1240 return 1241 } 1242 if err != nil { 1243 db.numOpen-- 1244 db.putConnDBLocked(nil, err) 1245 db.maybeOpenNewConnections() 1246 return 1247 } 1248 dc := &driverConn{ 1249 db: db, 1250 createdAt: nowFunc(), 1251 returnedAt: nowFunc(), 1252 ci: ci, 1253 } 1254 if db.putConnDBLocked(dc, err) { 1255 db.addDepLocked(dc, dc) 1256 } else { 1257 db.numOpen-- 1258 ci.Close() 1259 } 1260 } 1261 1262 // connRequest represents one request for a new connection 1263 // When there are no idle connections available, DB.conn will create 1264 // a new connRequest and put it on the db.connRequests list. 1265 type connRequest struct { 1266 conn *driverConn 1267 err error 1268 } 1269 1270 var errDBClosed = errors.New("sql: database is closed") 1271 1272 // nextRequestKeyLocked returns the next connection request key. 1273 // It is assumed that nextRequest will not overflow. 1274 func (db *DB) nextRequestKeyLocked() uint64 { 1275 next := db.nextRequest 1276 db.nextRequest++ 1277 return next 1278 } 1279 1280 // conn returns a newly-opened or cached *driverConn. 1281 func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) { 1282 db.mu.Lock() 1283 if db.closed { 1284 db.mu.Unlock() 1285 return nil, errDBClosed 1286 } 1287 // Check if the context is expired. 1288 select { 1289 default: 1290 case <-ctx.Done(): 1291 db.mu.Unlock() 1292 return nil, ctx.Err() 1293 } 1294 lifetime := db.maxLifetime 1295 1296 // Prefer a free connection, if possible. 1297 last := len(db.freeConn) - 1 1298 if strategy == cachedOrNewConn && last >= 0 { 1299 // Reuse the lowest idle time connection so we can close 1300 // connections which remain idle as soon as possible. 1301 conn := db.freeConn[last] 1302 db.freeConn = db.freeConn[:last] 1303 conn.inUse = true 1304 if conn.expired(lifetime) { 1305 db.maxLifetimeClosed++ 1306 db.mu.Unlock() 1307 conn.Close() 1308 return nil, driver.ErrBadConn 1309 } 1310 db.mu.Unlock() 1311 1312 // Reset the session if required. 1313 if err := conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) { 1314 conn.Close() 1315 return nil, err 1316 } 1317 1318 return conn, nil 1319 } 1320 1321 // Out of free connections or we were asked not to use one. If we're not 1322 // allowed to open any more connections, make a request and wait. 1323 if db.maxOpen > 0 && db.numOpen >= db.maxOpen { 1324 // Make the connRequest channel. It's buffered so that the 1325 // connectionOpener doesn't block while waiting for the req to be read. 1326 req := make(chan connRequest, 1) 1327 reqKey := db.nextRequestKeyLocked() 1328 db.connRequests[reqKey] = req 1329 db.waitCount++ 1330 db.mu.Unlock() 1331 1332 waitStart := nowFunc() 1333 1334 // Timeout the connection request with the context. 1335 select { 1336 case <-ctx.Done(): 1337 // Remove the connection request and ensure no value has been sent 1338 // on it after removing. 1339 db.mu.Lock() 1340 delete(db.connRequests, reqKey) 1341 db.mu.Unlock() 1342 1343 db.waitDuration.Add(int64(time.Since(waitStart))) 1344 1345 select { 1346 default: 1347 case ret, ok := <-req: 1348 if ok && ret.conn != nil { 1349 db.putConn(ret.conn, ret.err, false) 1350 } 1351 } 1352 return nil, ctx.Err() 1353 case ret, ok := <-req: 1354 db.waitDuration.Add(int64(time.Since(waitStart))) 1355 1356 if !ok { 1357 return nil, errDBClosed 1358 } 1359 // Only check if the connection is expired if the strategy is cachedOrNewConns. 1360 // If we require a new connection, just re-use the connection without looking 1361 // at the expiry time. If it is expired, it will be checked when it is placed 1362 // back into the connection pool. 1363 // This prioritizes giving a valid connection to a client over the exact connection 1364 // lifetime, which could expire exactly after this point anyway. 1365 if strategy == cachedOrNewConn && ret.err == nil && ret.conn.expired(lifetime) { 1366 db.mu.Lock() 1367 db.maxLifetimeClosed++ 1368 db.mu.Unlock() 1369 ret.conn.Close() 1370 return nil, driver.ErrBadConn 1371 } 1372 if ret.conn == nil { 1373 return nil, ret.err 1374 } 1375 1376 // Reset the session if required. 1377 if err := ret.conn.resetSession(ctx); errors.Is(err, driver.ErrBadConn) { 1378 ret.conn.Close() 1379 return nil, err 1380 } 1381 return ret.conn, ret.err 1382 } 1383 } 1384 1385 db.numOpen++ // optimistically 1386 db.mu.Unlock() 1387 ci, err := db.connector.Connect(ctx) 1388 if err != nil { 1389 db.mu.Lock() 1390 db.numOpen-- // correct for earlier optimism 1391 db.maybeOpenNewConnections() 1392 db.mu.Unlock() 1393 return nil, err 1394 } 1395 db.mu.Lock() 1396 dc := &driverConn{ 1397 db: db, 1398 createdAt: nowFunc(), 1399 returnedAt: nowFunc(), 1400 ci: ci, 1401 inUse: true, 1402 } 1403 db.addDepLocked(dc, dc) 1404 db.mu.Unlock() 1405 return dc, nil 1406 } 1407 1408 // putConnHook is a hook for testing. 1409 var putConnHook func(*DB, *driverConn) 1410 1411 // noteUnusedDriverStatement notes that ds is no longer used and should 1412 // be closed whenever possible (when c is next not in use), unless c is 1413 // already closed. 1414 func (db *DB) noteUnusedDriverStatement(c *driverConn, ds *driverStmt) { 1415 db.mu.Lock() 1416 defer db.mu.Unlock() 1417 if c.inUse { 1418 c.onPut = append(c.onPut, func() { 1419 ds.Close() 1420 }) 1421 } else { 1422 c.Lock() 1423 fc := c.finalClosed 1424 c.Unlock() 1425 if !fc { 1426 ds.Close() 1427 } 1428 } 1429 } 1430 1431 // debugGetPut determines whether getConn & putConn calls' stack traces 1432 // are returned for more verbose crashes. 1433 const debugGetPut = false 1434 1435 // putConn adds a connection to the db's free pool. 1436 // err is optionally the last error that occurred on this connection. 1437 func (db *DB) putConn(dc *driverConn, err error, resetSession bool) { 1438 if !errors.Is(err, driver.ErrBadConn) { 1439 if !dc.validateConnection(resetSession) { 1440 err = driver.ErrBadConn 1441 } 1442 } 1443 db.mu.Lock() 1444 if !dc.inUse { 1445 db.mu.Unlock() 1446 if debugGetPut { 1447 fmt.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc, stack(), db.lastPut[dc]) 1448 } 1449 panic("sql: connection returned that was never out") 1450 } 1451 1452 if !errors.Is(err, driver.ErrBadConn) && dc.expired(db.maxLifetime) { 1453 db.maxLifetimeClosed++ 1454 err = driver.ErrBadConn 1455 } 1456 if debugGetPut { 1457 db.lastPut[dc] = stack() 1458 } 1459 dc.inUse = false 1460 dc.returnedAt = nowFunc() 1461 1462 for _, fn := range dc.onPut { 1463 fn() 1464 } 1465 dc.onPut = nil 1466 1467 if errors.Is(err, driver.ErrBadConn) { 1468 // Don't reuse bad connections. 1469 // Since the conn is considered bad and is being discarded, treat it 1470 // as closed. Don't decrement the open count here, finalClose will 1471 // take care of that. 1472 db.maybeOpenNewConnections() 1473 db.mu.Unlock() 1474 dc.Close() 1475 return 1476 } 1477 if putConnHook != nil { 1478 putConnHook(db, dc) 1479 } 1480 added := db.putConnDBLocked(dc, nil) 1481 db.mu.Unlock() 1482 1483 if !added { 1484 dc.Close() 1485 return 1486 } 1487 } 1488 1489 // Satisfy a connRequest or put the driverConn in the idle pool and return true 1490 // or return false. 1491 // putConnDBLocked will satisfy a connRequest if there is one, or it will 1492 // return the *driverConn to the freeConn list if err == nil and the idle 1493 // connection limit will not be exceeded. 1494 // If err != nil, the value of dc is ignored. 1495 // If err == nil, then dc must not equal nil. 1496 // If a connRequest was fulfilled or the *driverConn was placed in the 1497 // freeConn list, then true is returned, otherwise false is returned. 1498 func (db *DB) putConnDBLocked(dc *driverConn, err error) bool { 1499 if db.closed { 1500 return false 1501 } 1502 if db.maxOpen > 0 && db.numOpen > db.maxOpen { 1503 return false 1504 } 1505 if c := len(db.connRequests); c > 0 { 1506 var req chan connRequest 1507 var reqKey uint64 1508 for reqKey, req = range db.connRequests { 1509 break 1510 } 1511 delete(db.connRequests, reqKey) // Remove from pending requests. 1512 if err == nil { 1513 dc.inUse = true 1514 } 1515 req <- connRequest{ 1516 conn: dc, 1517 err: err, 1518 } 1519 return true 1520 } else if err == nil && !db.closed { 1521 if db.maxIdleConnsLocked() > len(db.freeConn) { 1522 db.freeConn = append(db.freeConn, dc) 1523 db.startCleanerLocked() 1524 return true 1525 } 1526 db.maxIdleClosed++ 1527 } 1528 return false 1529 } 1530 1531 // maxBadConnRetries is the number of maximum retries if the driver returns 1532 // driver.ErrBadConn to signal a broken connection before forcing a new 1533 // connection to be opened. 1534 const maxBadConnRetries = 2 1535 1536 func (db *DB) retry(fn func(strategy connReuseStrategy) error) error { 1537 for i := int64(0); i < maxBadConnRetries; i++ { 1538 err := fn(cachedOrNewConn) 1539 // retry if err is driver.ErrBadConn 1540 if err == nil || !errors.Is(err, driver.ErrBadConn) { 1541 return err 1542 } 1543 } 1544 1545 return fn(alwaysNewConn) 1546 } 1547 1548 // PrepareContext creates a prepared statement for later queries or executions. 1549 // Multiple queries or executions may be run concurrently from the 1550 // returned statement. 1551 // The caller must call the statement's Close method 1552 // when the statement is no longer needed. 1553 // 1554 // The provided context is used for the preparation of the statement, not for the 1555 // execution of the statement. 1556 func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) { 1557 var stmt *Stmt 1558 var err error 1559 1560 err = db.retry(func(strategy connReuseStrategy) error { 1561 stmt, err = db.prepare(ctx, query, strategy) 1562 return err 1563 }) 1564 1565 return stmt, err 1566 } 1567 1568 // Prepare creates a prepared statement for later queries or executions. 1569 // Multiple queries or executions may be run concurrently from the 1570 // returned statement. 1571 // The caller must call the statement's Close method 1572 // when the statement is no longer needed. 1573 // 1574 // Prepare uses context.Background internally; to specify the context, use 1575 // PrepareContext. 1576 func (db *DB) Prepare(query string) (*Stmt, error) { 1577 return db.PrepareContext(context.Background(), query) 1578 } 1579 1580 func (db *DB) prepare(ctx context.Context, query string, strategy connReuseStrategy) (*Stmt, error) { 1581 // TODO: check if db.driver supports an optional 1582 // driver.Preparer interface and call that instead, if so, 1583 // otherwise we make a prepared statement that's bound 1584 // to a connection, and to execute this prepared statement 1585 // we either need to use this connection (if it's free), else 1586 // get a new connection + re-prepare + execute on that one. 1587 dc, err := db.conn(ctx, strategy) 1588 if err != nil { 1589 return nil, err 1590 } 1591 return db.prepareDC(ctx, dc, dc.releaseConn, nil, query) 1592 } 1593 1594 // prepareDC prepares a query on the driverConn and calls release before 1595 // returning. When cg == nil it implies that a connection pool is used, and 1596 // when cg != nil only a single driver connection is used. 1597 func (db *DB) prepareDC(ctx context.Context, dc *driverConn, release func(error), cg stmtConnGrabber, query string) (*Stmt, error) { 1598 var ds *driverStmt 1599 var err error 1600 defer func() { 1601 release(err) 1602 }() 1603 withLock(dc, func() { 1604 ds, err = dc.prepareLocked(ctx, cg, query) 1605 }) 1606 if err != nil { 1607 return nil, err 1608 } 1609 stmt := &Stmt{ 1610 db: db, 1611 query: query, 1612 cg: cg, 1613 cgds: ds, 1614 } 1615 1616 // When cg == nil this statement will need to keep track of various 1617 // connections they are prepared on and record the stmt dependency on 1618 // the DB. 1619 if cg == nil { 1620 stmt.css = []connStmt{{dc, ds}} 1621 stmt.lastNumClosed = db.numClosed.Load() 1622 db.addDep(stmt, stmt) 1623 } 1624 return stmt, nil 1625 } 1626 1627 // ExecContext executes a query without returning any rows. 1628 // The args are for any placeholder parameters in the query. 1629 func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error) { 1630 var res Result 1631 var err error 1632 1633 err = db.retry(func(strategy connReuseStrategy) error { 1634 res, err = db.exec(ctx, query, args, strategy) 1635 return err 1636 }) 1637 1638 return res, err 1639 } 1640 1641 // Exec executes a query without returning any rows. 1642 // The args are for any placeholder parameters in the query. 1643 // 1644 // Exec uses context.Background internally; to specify the context, use 1645 // ExecContext. 1646 func (db *DB) Exec(query string, args ...any) (Result, error) { 1647 return db.ExecContext(context.Background(), query, args...) 1648 } 1649 1650 func (db *DB) exec(ctx context.Context, query string, args []any, strategy connReuseStrategy) (Result, error) { 1651 dc, err := db.conn(ctx, strategy) 1652 if err != nil { 1653 return nil, err 1654 } 1655 return db.execDC(ctx, dc, dc.releaseConn, query, args) 1656 } 1657 1658 func (db *DB) execDC(ctx context.Context, dc *driverConn, release func(error), query string, args []any) (res Result, err error) { 1659 defer func() { 1660 release(err) 1661 }() 1662 execerCtx, ok := dc.ci.(driver.ExecerContext) 1663 var execer driver.Execer 1664 if !ok { 1665 execer, ok = dc.ci.(driver.Execer) 1666 } 1667 if ok { 1668 var nvdargs []driver.NamedValue 1669 var resi driver.Result 1670 withLock(dc, func() { 1671 nvdargs, err = driverArgsConnLocked(dc.ci, nil, args) 1672 if err != nil { 1673 return 1674 } 1675 resi, err = ctxDriverExec(ctx, execerCtx, execer, query, nvdargs) 1676 }) 1677 if err != driver.ErrSkip { 1678 if err != nil { 1679 return nil, err 1680 } 1681 return driverResult{dc, resi}, nil 1682 } 1683 } 1684 1685 var si driver.Stmt 1686 withLock(dc, func() { 1687 si, err = ctxDriverPrepare(ctx, dc.ci, query) 1688 }) 1689 if err != nil { 1690 return nil, err 1691 } 1692 ds := &driverStmt{Locker: dc, si: si} 1693 defer ds.Close() 1694 return resultFromStatement(ctx, dc.ci, ds, args...) 1695 } 1696 1697 // QueryContext executes a query that returns rows, typically a SELECT. 1698 // The args are for any placeholder parameters in the query. 1699 func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) { 1700 var rows *Rows 1701 var err error 1702 1703 err = db.retry(func(strategy connReuseStrategy) error { 1704 rows, err = db.query(ctx, query, args, strategy) 1705 return err 1706 }) 1707 1708 return rows, err 1709 } 1710 1711 // Query executes a query that returns rows, typically a SELECT. 1712 // The args are for any placeholder parameters in the query. 1713 // 1714 // Query uses context.Background internally; to specify the context, use 1715 // QueryContext. 1716 func (db *DB) Query(query string, args ...any) (*Rows, error) { 1717 return db.QueryContext(context.Background(), query, args...) 1718 } 1719 1720 func (db *DB) query(ctx context.Context, query string, args []any, strategy connReuseStrategy) (*Rows, error) { 1721 dc, err := db.conn(ctx, strategy) 1722 if err != nil { 1723 return nil, err 1724 } 1725 1726 return db.queryDC(ctx, nil, dc, dc.releaseConn, query, args) 1727 } 1728 1729 // queryDC executes a query on the given connection. 1730 // The connection gets released by the releaseConn function. 1731 // The ctx context is from a query method and the txctx context is from an 1732 // optional transaction context. 1733 func (db *DB) queryDC(ctx, txctx context.Context, dc *driverConn, releaseConn func(error), query string, args []any) (*Rows, error) { 1734 queryerCtx, ok := dc.ci.(driver.QueryerContext) 1735 var queryer driver.Queryer 1736 if !ok { 1737 queryer, ok = dc.ci.(driver.Queryer) 1738 } 1739 if ok { 1740 var nvdargs []driver.NamedValue 1741 var rowsi driver.Rows 1742 var err error 1743 withLock(dc, func() { 1744 nvdargs, err = driverArgsConnLocked(dc.ci, nil, args) 1745 if err != nil { 1746 return 1747 } 1748 rowsi, err = ctxDriverQuery(ctx, queryerCtx, queryer, query, nvdargs) 1749 }) 1750 if err != driver.ErrSkip { 1751 if err != nil { 1752 releaseConn(err) 1753 return nil, err 1754 } 1755 // Note: ownership of dc passes to the *Rows, to be freed 1756 // with releaseConn. 1757 rows := &Rows{ 1758 dc: dc, 1759 releaseConn: releaseConn, 1760 rowsi: rowsi, 1761 } 1762 rows.initContextClose(ctx, txctx) 1763 return rows, nil 1764 } 1765 } 1766 1767 var si driver.Stmt 1768 var err error 1769 withLock(dc, func() { 1770 si, err = ctxDriverPrepare(ctx, dc.ci, query) 1771 }) 1772 if err != nil { 1773 releaseConn(err) 1774 return nil, err 1775 } 1776 1777 ds := &driverStmt{Locker: dc, si: si} 1778 rowsi, err := rowsiFromStatement(ctx, dc.ci, ds, args...) 1779 if err != nil { 1780 ds.Close() 1781 releaseConn(err) 1782 return nil, err 1783 } 1784 1785 // Note: ownership of ci passes to the *Rows, to be freed 1786 // with releaseConn. 1787 rows := &Rows{ 1788 dc: dc, 1789 releaseConn: releaseConn, 1790 rowsi: rowsi, 1791 closeStmt: ds, 1792 } 1793 rows.initContextClose(ctx, txctx) 1794 return rows, nil 1795 } 1796 1797 // QueryRowContext executes a query that is expected to return at most one row. 1798 // QueryRowContext always returns a non-nil value. Errors are deferred until 1799 // Row's Scan method is called. 1800 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 1801 // Otherwise, the *Row's Scan scans the first selected row and discards 1802 // the rest. 1803 func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row { 1804 rows, err := db.QueryContext(ctx, query, args...) 1805 return &Row{rows: rows, err: err} 1806 } 1807 1808 // QueryRow executes a query that is expected to return at most one row. 1809 // QueryRow always returns a non-nil value. Errors are deferred until 1810 // Row's Scan method is called. 1811 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 1812 // Otherwise, the *Row's Scan scans the first selected row and discards 1813 // the rest. 1814 // 1815 // QueryRow uses context.Background internally; to specify the context, use 1816 // QueryRowContext. 1817 func (db *DB) QueryRow(query string, args ...any) *Row { 1818 return db.QueryRowContext(context.Background(), query, args...) 1819 } 1820 1821 // BeginTx starts a transaction. 1822 // 1823 // The provided context is used until the transaction is committed or rolled back. 1824 // If the context is canceled, the sql package will roll back 1825 // the transaction. Tx.Commit will return an error if the context provided to 1826 // BeginTx is canceled. 1827 // 1828 // The provided TxOptions is optional and may be nil if defaults should be used. 1829 // If a non-default isolation level is used that the driver doesn't support, 1830 // an error will be returned. 1831 func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) { 1832 var tx *Tx 1833 var err error 1834 1835 err = db.retry(func(strategy connReuseStrategy) error { 1836 tx, err = db.begin(ctx, opts, strategy) 1837 return err 1838 }) 1839 1840 return tx, err 1841 } 1842 1843 // Begin starts a transaction. The default isolation level is dependent on 1844 // the driver. 1845 // 1846 // Begin uses context.Background internally; to specify the context, use 1847 // BeginTx. 1848 func (db *DB) Begin() (*Tx, error) { 1849 return db.BeginTx(context.Background(), nil) 1850 } 1851 1852 func (db *DB) begin(ctx context.Context, opts *TxOptions, strategy connReuseStrategy) (tx *Tx, err error) { 1853 dc, err := db.conn(ctx, strategy) 1854 if err != nil { 1855 return nil, err 1856 } 1857 return db.beginDC(ctx, dc, dc.releaseConn, opts) 1858 } 1859 1860 // beginDC starts a transaction. The provided dc must be valid and ready to use. 1861 func (db *DB) beginDC(ctx context.Context, dc *driverConn, release func(error), opts *TxOptions) (tx *Tx, err error) { 1862 var txi driver.Tx 1863 keepConnOnRollback := false 1864 withLock(dc, func() { 1865 _, hasSessionResetter := dc.ci.(driver.SessionResetter) 1866 _, hasConnectionValidator := dc.ci.(driver.Validator) 1867 keepConnOnRollback = hasSessionResetter && hasConnectionValidator 1868 txi, err = ctxDriverBegin(ctx, opts, dc.ci) 1869 }) 1870 if err != nil { 1871 release(err) 1872 return nil, err 1873 } 1874 1875 // Schedule the transaction to rollback when the context is canceled. 1876 // The cancel function in Tx will be called after done is set to true. 1877 ctx, cancel := context.WithCancel(ctx) 1878 tx = &Tx{ 1879 db: db, 1880 dc: dc, 1881 releaseConn: release, 1882 txi: txi, 1883 cancel: cancel, 1884 keepConnOnRollback: keepConnOnRollback, 1885 ctx: ctx, 1886 } 1887 go tx.awaitDone() 1888 return tx, nil 1889 } 1890 1891 // Driver returns the database's underlying driver. 1892 func (db *DB) Driver() driver.Driver { 1893 return db.connector.Driver() 1894 } 1895 1896 // ErrConnDone is returned by any operation that is performed on a connection 1897 // that has already been returned to the connection pool. 1898 var ErrConnDone = errors.New("sql: connection is already closed") 1899 1900 // Conn returns a single connection by either opening a new connection 1901 // or returning an existing connection from the connection pool. Conn will 1902 // block until either a connection is returned or ctx is canceled. 1903 // Queries run on the same Conn will be run in the same database session. 1904 // 1905 // Every Conn must be returned to the database pool after use by 1906 // calling Conn.Close. 1907 func (db *DB) Conn(ctx context.Context) (*Conn, error) { 1908 var dc *driverConn 1909 var err error 1910 1911 err = db.retry(func(strategy connReuseStrategy) error { 1912 dc, err = db.conn(ctx, strategy) 1913 return err 1914 }) 1915 1916 if err != nil { 1917 return nil, err 1918 } 1919 1920 conn := &Conn{ 1921 db: db, 1922 dc: dc, 1923 } 1924 return conn, nil 1925 } 1926 1927 type releaseConn func(error) 1928 1929 // Conn represents a single database connection rather than a pool of database 1930 // connections. Prefer running queries from DB unless there is a specific 1931 // need for a continuous single database connection. 1932 // 1933 // A Conn must call Close to return the connection to the database pool 1934 // and may do so concurrently with a running query. 1935 // 1936 // After a call to Close, all operations on the 1937 // connection fail with ErrConnDone. 1938 type Conn struct { 1939 db *DB 1940 1941 // closemu prevents the connection from closing while there 1942 // is an active query. It is held for read during queries 1943 // and exclusively during close. 1944 closemu sync.RWMutex 1945 1946 // dc is owned until close, at which point 1947 // it's returned to the connection pool. 1948 dc *driverConn 1949 1950 // done transitions from 0 to 1 exactly once, on close. 1951 // Once done, all operations fail with ErrConnDone. 1952 // Use atomic operations on value when checking value. 1953 done int32 1954 } 1955 1956 // grabConn takes a context to implement stmtConnGrabber 1957 // but the context is not used. 1958 func (c *Conn) grabConn(context.Context) (*driverConn, releaseConn, error) { 1959 if atomic.LoadInt32(&c.done) != 0 { 1960 return nil, nil, ErrConnDone 1961 } 1962 c.closemu.RLock() 1963 return c.dc, c.closemuRUnlockCondReleaseConn, nil 1964 } 1965 1966 // PingContext verifies the connection to the database is still alive. 1967 func (c *Conn) PingContext(ctx context.Context) error { 1968 dc, release, err := c.grabConn(ctx) 1969 if err != nil { 1970 return err 1971 } 1972 return c.db.pingDC(ctx, dc, release) 1973 } 1974 1975 // ExecContext executes a query without returning any rows. 1976 // The args are for any placeholder parameters in the query. 1977 func (c *Conn) ExecContext(ctx context.Context, query string, args ...any) (Result, error) { 1978 dc, release, err := c.grabConn(ctx) 1979 if err != nil { 1980 return nil, err 1981 } 1982 return c.db.execDC(ctx, dc, release, query, args) 1983 } 1984 1985 // QueryContext executes a query that returns rows, typically a SELECT. 1986 // The args are for any placeholder parameters in the query. 1987 func (c *Conn) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) { 1988 dc, release, err := c.grabConn(ctx) 1989 if err != nil { 1990 return nil, err 1991 } 1992 return c.db.queryDC(ctx, nil, dc, release, query, args) 1993 } 1994 1995 // QueryRowContext executes a query that is expected to return at most one row. 1996 // QueryRowContext always returns a non-nil value. Errors are deferred until 1997 // Row's Scan method is called. 1998 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 1999 // Otherwise, the *Row's Scan scans the first selected row and discards 2000 // the rest. 2001 func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...any) *Row { 2002 rows, err := c.QueryContext(ctx, query, args...) 2003 return &Row{rows: rows, err: err} 2004 } 2005 2006 // PrepareContext creates a prepared statement for later queries or executions. 2007 // Multiple queries or executions may be run concurrently from the 2008 // returned statement. 2009 // The caller must call the statement's Close method 2010 // when the statement is no longer needed. 2011 // 2012 // The provided context is used for the preparation of the statement, not for the 2013 // execution of the statement. 2014 func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error) { 2015 dc, release, err := c.grabConn(ctx) 2016 if err != nil { 2017 return nil, err 2018 } 2019 return c.db.prepareDC(ctx, dc, release, c, query) 2020 } 2021 2022 // Raw executes f exposing the underlying driver connection for the 2023 // duration of f. The driverConn must not be used outside of f. 2024 // 2025 // Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable 2026 // until Conn.Close is called. 2027 func (c *Conn) Raw(f func(driverConn any) error) (err error) { 2028 var dc *driverConn 2029 var release releaseConn 2030 2031 // grabConn takes a context to implement stmtConnGrabber, but the context is not used. 2032 dc, release, err = c.grabConn(nil) 2033 if err != nil { 2034 return 2035 } 2036 fPanic := true 2037 dc.Mutex.Lock() 2038 defer func() { 2039 dc.Mutex.Unlock() 2040 2041 // If f panics fPanic will remain true. 2042 // Ensure an error is passed to release so the connection 2043 // may be discarded. 2044 if fPanic { 2045 err = driver.ErrBadConn 2046 } 2047 release(err) 2048 }() 2049 err = f(dc.ci) 2050 fPanic = false 2051 2052 return 2053 } 2054 2055 // BeginTx starts a transaction. 2056 // 2057 // The provided context is used until the transaction is committed or rolled back. 2058 // If the context is canceled, the sql package will roll back 2059 // the transaction. Tx.Commit will return an error if the context provided to 2060 // BeginTx is canceled. 2061 // 2062 // The provided TxOptions is optional and may be nil if defaults should be used. 2063 // If a non-default isolation level is used that the driver doesn't support, 2064 // an error will be returned. 2065 func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) { 2066 dc, release, err := c.grabConn(ctx) 2067 if err != nil { 2068 return nil, err 2069 } 2070 return c.db.beginDC(ctx, dc, release, opts) 2071 } 2072 2073 // closemuRUnlockCondReleaseConn read unlocks closemu 2074 // as the sql operation is done with the dc. 2075 func (c *Conn) closemuRUnlockCondReleaseConn(err error) { 2076 c.closemu.RUnlock() 2077 if errors.Is(err, driver.ErrBadConn) { 2078 c.close(err) 2079 } 2080 } 2081 2082 func (c *Conn) txCtx() context.Context { 2083 return nil 2084 } 2085 2086 func (c *Conn) close(err error) error { 2087 if !atomic.CompareAndSwapInt32(&c.done, 0, 1) { 2088 return ErrConnDone 2089 } 2090 2091 // Lock around releasing the driver connection 2092 // to ensure all queries have been stopped before doing so. 2093 c.closemu.Lock() 2094 defer c.closemu.Unlock() 2095 2096 c.dc.releaseConn(err) 2097 c.dc = nil 2098 c.db = nil 2099 return err 2100 } 2101 2102 // Close returns the connection to the connection pool. 2103 // All operations after a Close will return with ErrConnDone. 2104 // Close is safe to call concurrently with other operations and will 2105 // block until all other operations finish. It may be useful to first 2106 // cancel any used context and then call close directly after. 2107 func (c *Conn) Close() error { 2108 return c.close(nil) 2109 } 2110 2111 // Tx is an in-progress database transaction. 2112 // 2113 // A transaction must end with a call to Commit or Rollback. 2114 // 2115 // After a call to Commit or Rollback, all operations on the 2116 // transaction fail with ErrTxDone. 2117 // 2118 // The statements prepared for a transaction by calling 2119 // the transaction's Prepare or Stmt methods are closed 2120 // by the call to Commit or Rollback. 2121 type Tx struct { 2122 db *DB 2123 2124 // closemu prevents the transaction from closing while there 2125 // is an active query. It is held for read during queries 2126 // and exclusively during close. 2127 closemu sync.RWMutex 2128 2129 // dc is owned exclusively until Commit or Rollback, at which point 2130 // it's returned with putConn. 2131 dc *driverConn 2132 txi driver.Tx 2133 2134 // releaseConn is called once the Tx is closed to release 2135 // any held driverConn back to the pool. 2136 releaseConn func(error) 2137 2138 // done transitions from false to true exactly once, on Commit 2139 // or Rollback. once done, all operations fail with 2140 // ErrTxDone. 2141 done atomic.Bool 2142 2143 // keepConnOnRollback is true if the driver knows 2144 // how to reset the connection's session and if need be discard 2145 // the connection. 2146 keepConnOnRollback bool 2147 2148 // All Stmts prepared for this transaction. These will be closed after the 2149 // transaction has been committed or rolled back. 2150 stmts struct { 2151 sync.Mutex 2152 v []*Stmt 2153 } 2154 2155 // cancel is called after done transitions from 0 to 1. 2156 cancel func() 2157 2158 // ctx lives for the life of the transaction. 2159 ctx context.Context 2160 } 2161 2162 // awaitDone blocks until the context in Tx is canceled and rolls back 2163 // the transaction if it's not already done. 2164 func (tx *Tx) awaitDone() { 2165 // Wait for either the transaction to be committed or rolled 2166 // back, or for the associated context to be closed. 2167 <-tx.ctx.Done() 2168 2169 // Discard and close the connection used to ensure the 2170 // transaction is closed and the resources are released. This 2171 // rollback does nothing if the transaction has already been 2172 // committed or rolled back. 2173 // Do not discard the connection if the connection knows 2174 // how to reset the session. 2175 discardConnection := !tx.keepConnOnRollback 2176 tx.rollback(discardConnection) 2177 } 2178 2179 func (tx *Tx) isDone() bool { 2180 return tx.done.Load() 2181 } 2182 2183 // ErrTxDone is returned by any operation that is performed on a transaction 2184 // that has already been committed or rolled back. 2185 var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back") 2186 2187 // close returns the connection to the pool and 2188 // must only be called by Tx.rollback or Tx.Commit while 2189 // tx is already canceled and won't be executed concurrently. 2190 func (tx *Tx) close(err error) { 2191 tx.releaseConn(err) 2192 tx.dc = nil 2193 tx.txi = nil 2194 } 2195 2196 // hookTxGrabConn specifies an optional hook to be called on 2197 // a successful call to (*Tx).grabConn. For tests. 2198 var hookTxGrabConn func() 2199 2200 func (tx *Tx) grabConn(ctx context.Context) (*driverConn, releaseConn, error) { 2201 select { 2202 default: 2203 case <-ctx.Done(): 2204 return nil, nil, ctx.Err() 2205 } 2206 2207 // closemu.RLock must come before the check for isDone to prevent the Tx from 2208 // closing while a query is executing. 2209 tx.closemu.RLock() 2210 if tx.isDone() { 2211 tx.closemu.RUnlock() 2212 return nil, nil, ErrTxDone 2213 } 2214 if hookTxGrabConn != nil { // test hook 2215 hookTxGrabConn() 2216 } 2217 return tx.dc, tx.closemuRUnlockRelease, nil 2218 } 2219 2220 func (tx *Tx) txCtx() context.Context { 2221 return tx.ctx 2222 } 2223 2224 // closemuRUnlockRelease is used as a func(error) method value in 2225 // ExecContext and QueryContext. Unlocking in the releaseConn keeps 2226 // the driver conn from being returned to the connection pool until 2227 // the Rows has been closed. 2228 func (tx *Tx) closemuRUnlockRelease(error) { 2229 tx.closemu.RUnlock() 2230 } 2231 2232 // Closes all Stmts prepared for this transaction. 2233 func (tx *Tx) closePrepared() { 2234 tx.stmts.Lock() 2235 defer tx.stmts.Unlock() 2236 for _, stmt := range tx.stmts.v { 2237 stmt.Close() 2238 } 2239 } 2240 2241 // Commit commits the transaction. 2242 func (tx *Tx) Commit() error { 2243 // Check context first to avoid transaction leak. 2244 // If put it behind tx.done CompareAndSwap statement, we can't ensure 2245 // the consistency between tx.done and the real COMMIT operation. 2246 select { 2247 default: 2248 case <-tx.ctx.Done(): 2249 if tx.done.Load() { 2250 return ErrTxDone 2251 } 2252 return tx.ctx.Err() 2253 } 2254 if !tx.done.CompareAndSwap(false, true) { 2255 return ErrTxDone 2256 } 2257 2258 // Cancel the Tx to release any active R-closemu locks. 2259 // This is safe to do because tx.done has already transitioned 2260 // from 0 to 1. Hold the W-closemu lock prior to rollback 2261 // to ensure no other connection has an active query. 2262 tx.cancel() 2263 tx.closemu.Lock() 2264 tx.closemu.Unlock() 2265 2266 var err error 2267 withLock(tx.dc, func() { 2268 err = tx.txi.Commit() 2269 }) 2270 if !errors.Is(err, driver.ErrBadConn) { 2271 tx.closePrepared() 2272 } 2273 tx.close(err) 2274 return err 2275 } 2276 2277 var rollbackHook func() 2278 2279 // rollback aborts the transaction and optionally forces the pool to discard 2280 // the connection. 2281 func (tx *Tx) rollback(discardConn bool) error { 2282 if !tx.done.CompareAndSwap(false, true) { 2283 return ErrTxDone 2284 } 2285 2286 if rollbackHook != nil { 2287 rollbackHook() 2288 } 2289 2290 // Cancel the Tx to release any active R-closemu locks. 2291 // This is safe to do because tx.done has already transitioned 2292 // from 0 to 1. Hold the W-closemu lock prior to rollback 2293 // to ensure no other connection has an active query. 2294 tx.cancel() 2295 tx.closemu.Lock() 2296 tx.closemu.Unlock() 2297 2298 var err error 2299 withLock(tx.dc, func() { 2300 err = tx.txi.Rollback() 2301 }) 2302 if !errors.Is(err, driver.ErrBadConn) { 2303 tx.closePrepared() 2304 } 2305 if discardConn { 2306 err = driver.ErrBadConn 2307 } 2308 tx.close(err) 2309 return err 2310 } 2311 2312 // Rollback aborts the transaction. 2313 func (tx *Tx) Rollback() error { 2314 return tx.rollback(false) 2315 } 2316 2317 // PrepareContext creates a prepared statement for use within a transaction. 2318 // 2319 // The returned statement operates within the transaction and will be closed 2320 // when the transaction has been committed or rolled back. 2321 // 2322 // To use an existing prepared statement on this transaction, see Tx.Stmt. 2323 // 2324 // The provided context will be used for the preparation of the context, not 2325 // for the execution of the returned statement. The returned statement 2326 // will run in the transaction context. 2327 func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) { 2328 dc, release, err := tx.grabConn(ctx) 2329 if err != nil { 2330 return nil, err 2331 } 2332 2333 stmt, err := tx.db.prepareDC(ctx, dc, release, tx, query) 2334 if err != nil { 2335 return nil, err 2336 } 2337 tx.stmts.Lock() 2338 tx.stmts.v = append(tx.stmts.v, stmt) 2339 tx.stmts.Unlock() 2340 return stmt, nil 2341 } 2342 2343 // Prepare creates a prepared statement for use within a transaction. 2344 // 2345 // The returned statement operates within the transaction and will be closed 2346 // when the transaction has been committed or rolled back. 2347 // 2348 // To use an existing prepared statement on this transaction, see Tx.Stmt. 2349 // 2350 // Prepare uses context.Background internally; to specify the context, use 2351 // PrepareContext. 2352 func (tx *Tx) Prepare(query string) (*Stmt, error) { 2353 return tx.PrepareContext(context.Background(), query) 2354 } 2355 2356 // StmtContext returns a transaction-specific prepared statement from 2357 // an existing statement. 2358 // 2359 // Example: 2360 // 2361 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") 2362 // ... 2363 // tx, err := db.Begin() 2364 // ... 2365 // res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203) 2366 // 2367 // The provided context is used for the preparation of the statement, not for the 2368 // execution of the statement. 2369 // 2370 // The returned statement operates within the transaction and will be closed 2371 // when the transaction has been committed or rolled back. 2372 func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt { 2373 dc, release, err := tx.grabConn(ctx) 2374 if err != nil { 2375 return &Stmt{stickyErr: err} 2376 } 2377 defer release(nil) 2378 2379 if tx.db != stmt.db { 2380 return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")} 2381 } 2382 var si driver.Stmt 2383 var parentStmt *Stmt 2384 stmt.mu.Lock() 2385 if stmt.closed || stmt.cg != nil { 2386 // If the statement has been closed or already belongs to a 2387 // transaction, we can't reuse it in this connection. 2388 // Since tx.StmtContext should never need to be called with a 2389 // Stmt already belonging to tx, we ignore this edge case and 2390 // re-prepare the statement in this case. No need to add 2391 // code-complexity for this. 2392 stmt.mu.Unlock() 2393 withLock(dc, func() { 2394 si, err = ctxDriverPrepare(ctx, dc.ci, stmt.query) 2395 }) 2396 if err != nil { 2397 return &Stmt{stickyErr: err} 2398 } 2399 } else { 2400 stmt.removeClosedStmtLocked() 2401 // See if the statement has already been prepared on this connection, 2402 // and reuse it if possible. 2403 for _, v := range stmt.css { 2404 if v.dc == dc { 2405 si = v.ds.si 2406 break 2407 } 2408 } 2409 2410 stmt.mu.Unlock() 2411 2412 if si == nil { 2413 var ds *driverStmt 2414 withLock(dc, func() { 2415 ds, err = stmt.prepareOnConnLocked(ctx, dc) 2416 }) 2417 if err != nil { 2418 return &Stmt{stickyErr: err} 2419 } 2420 si = ds.si 2421 } 2422 parentStmt = stmt 2423 } 2424 2425 txs := &Stmt{ 2426 db: tx.db, 2427 cg: tx, 2428 cgds: &driverStmt{ 2429 Locker: dc, 2430 si: si, 2431 }, 2432 parentStmt: parentStmt, 2433 query: stmt.query, 2434 } 2435 if parentStmt != nil { 2436 tx.db.addDep(parentStmt, txs) 2437 } 2438 tx.stmts.Lock() 2439 tx.stmts.v = append(tx.stmts.v, txs) 2440 tx.stmts.Unlock() 2441 return txs 2442 } 2443 2444 // Stmt returns a transaction-specific prepared statement from 2445 // an existing statement. 2446 // 2447 // Example: 2448 // 2449 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") 2450 // ... 2451 // tx, err := db.Begin() 2452 // ... 2453 // res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203) 2454 // 2455 // The returned statement operates within the transaction and will be closed 2456 // when the transaction has been committed or rolled back. 2457 // 2458 // Stmt uses context.Background internally; to specify the context, use 2459 // StmtContext. 2460 func (tx *Tx) Stmt(stmt *Stmt) *Stmt { 2461 return tx.StmtContext(context.Background(), stmt) 2462 } 2463 2464 // ExecContext executes a query that doesn't return rows. 2465 // For example: an INSERT and UPDATE. 2466 func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (Result, error) { 2467 dc, release, err := tx.grabConn(ctx) 2468 if err != nil { 2469 return nil, err 2470 } 2471 return tx.db.execDC(ctx, dc, release, query, args) 2472 } 2473 2474 // Exec executes a query that doesn't return rows. 2475 // For example: an INSERT and UPDATE. 2476 // 2477 // Exec uses context.Background internally; to specify the context, use 2478 // ExecContext. 2479 func (tx *Tx) Exec(query string, args ...any) (Result, error) { 2480 return tx.ExecContext(context.Background(), query, args...) 2481 } 2482 2483 // QueryContext executes a query that returns rows, typically a SELECT. 2484 func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) { 2485 dc, release, err := tx.grabConn(ctx) 2486 if err != nil { 2487 return nil, err 2488 } 2489 2490 return tx.db.queryDC(ctx, tx.ctx, dc, release, query, args) 2491 } 2492 2493 // Query executes a query that returns rows, typically a SELECT. 2494 // 2495 // Query uses context.Background internally; to specify the context, use 2496 // QueryContext. 2497 func (tx *Tx) Query(query string, args ...any) (*Rows, error) { 2498 return tx.QueryContext(context.Background(), query, args...) 2499 } 2500 2501 // QueryRowContext executes a query that is expected to return at most one row. 2502 // QueryRowContext always returns a non-nil value. Errors are deferred until 2503 // Row's Scan method is called. 2504 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 2505 // Otherwise, the *Row's Scan scans the first selected row and discards 2506 // the rest. 2507 func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *Row { 2508 rows, err := tx.QueryContext(ctx, query, args...) 2509 return &Row{rows: rows, err: err} 2510 } 2511 2512 // QueryRow executes a query that is expected to return at most one row. 2513 // QueryRow always returns a non-nil value. Errors are deferred until 2514 // Row's Scan method is called. 2515 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 2516 // Otherwise, the *Row's Scan scans the first selected row and discards 2517 // the rest. 2518 // 2519 // QueryRow uses context.Background internally; to specify the context, use 2520 // QueryRowContext. 2521 func (tx *Tx) QueryRow(query string, args ...any) *Row { 2522 return tx.QueryRowContext(context.Background(), query, args...) 2523 } 2524 2525 // connStmt is a prepared statement on a particular connection. 2526 type connStmt struct { 2527 dc *driverConn 2528 ds *driverStmt 2529 } 2530 2531 // stmtConnGrabber represents a Tx or Conn that will return the underlying 2532 // driverConn and release function. 2533 type stmtConnGrabber interface { 2534 // grabConn returns the driverConn and the associated release function 2535 // that must be called when the operation completes. 2536 grabConn(context.Context) (*driverConn, releaseConn, error) 2537 2538 // txCtx returns the transaction context if available. 2539 // The returned context should be selected on along with 2540 // any query context when awaiting a cancel. 2541 txCtx() context.Context 2542 } 2543 2544 var ( 2545 _ stmtConnGrabber = &Tx{} 2546 _ stmtConnGrabber = &Conn{} 2547 ) 2548 2549 // Stmt is a prepared statement. 2550 // A Stmt is safe for concurrent use by multiple goroutines. 2551 // 2552 // If a Stmt is prepared on a Tx or Conn, it will be bound to a single 2553 // underlying connection forever. If the Tx or Conn closes, the Stmt will 2554 // become unusable and all operations will return an error. 2555 // If a Stmt is prepared on a DB, it will remain usable for the lifetime of the 2556 // DB. When the Stmt needs to execute on a new underlying connection, it will 2557 // prepare itself on the new connection automatically. 2558 type Stmt struct { 2559 // Immutable: 2560 db *DB // where we came from 2561 query string // that created the Stmt 2562 stickyErr error // if non-nil, this error is returned for all operations 2563 2564 closemu sync.RWMutex // held exclusively during close, for read otherwise. 2565 2566 // If Stmt is prepared on a Tx or Conn then cg is present and will 2567 // only ever grab a connection from cg. 2568 // If cg is nil then the Stmt must grab an arbitrary connection 2569 // from db and determine if it must prepare the stmt again by 2570 // inspecting css. 2571 cg stmtConnGrabber 2572 cgds *driverStmt 2573 2574 // parentStmt is set when a transaction-specific statement 2575 // is requested from an identical statement prepared on the same 2576 // conn. parentStmt is used to track the dependency of this statement 2577 // on its originating ("parent") statement so that parentStmt may 2578 // be closed by the user without them having to know whether or not 2579 // any transactions are still using it. 2580 parentStmt *Stmt 2581 2582 mu sync.Mutex // protects the rest of the fields 2583 closed bool 2584 2585 // css is a list of underlying driver statement interfaces 2586 // that are valid on particular connections. This is only 2587 // used if cg == nil and one is found that has idle 2588 // connections. If cg != nil, cgds is always used. 2589 css []connStmt 2590 2591 // lastNumClosed is copied from db.numClosed when Stmt is created 2592 // without tx and closed connections in css are removed. 2593 lastNumClosed uint64 2594 } 2595 2596 // ExecContext executes a prepared statement with the given arguments and 2597 // returns a Result summarizing the effect of the statement. 2598 func (s *Stmt) ExecContext(ctx context.Context, args ...any) (Result, error) { 2599 s.closemu.RLock() 2600 defer s.closemu.RUnlock() 2601 2602 var res Result 2603 err := s.db.retry(func(strategy connReuseStrategy) error { 2604 dc, releaseConn, ds, err := s.connStmt(ctx, strategy) 2605 if err != nil { 2606 return err 2607 } 2608 2609 res, err = resultFromStatement(ctx, dc.ci, ds, args...) 2610 releaseConn(err) 2611 return err 2612 }) 2613 2614 return res, err 2615 } 2616 2617 // Exec executes a prepared statement with the given arguments and 2618 // returns a Result summarizing the effect of the statement. 2619 // 2620 // Exec uses context.Background internally; to specify the context, use 2621 // ExecContext. 2622 func (s *Stmt) Exec(args ...any) (Result, error) { 2623 return s.ExecContext(context.Background(), args...) 2624 } 2625 2626 func resultFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...any) (Result, error) { 2627 ds.Lock() 2628 defer ds.Unlock() 2629 2630 dargs, err := driverArgsConnLocked(ci, ds, args) 2631 if err != nil { 2632 return nil, err 2633 } 2634 2635 resi, err := ctxDriverStmtExec(ctx, ds.si, dargs) 2636 if err != nil { 2637 return nil, err 2638 } 2639 return driverResult{ds.Locker, resi}, nil 2640 } 2641 2642 // removeClosedStmtLocked removes closed conns in s.css. 2643 // 2644 // To avoid lock contention on DB.mu, we do it only when 2645 // s.db.numClosed - s.lastNum is large enough. 2646 func (s *Stmt) removeClosedStmtLocked() { 2647 t := len(s.css)/2 + 1 2648 if t > 10 { 2649 t = 10 2650 } 2651 dbClosed := s.db.numClosed.Load() 2652 if dbClosed-s.lastNumClosed < uint64(t) { 2653 return 2654 } 2655 2656 s.db.mu.Lock() 2657 for i := 0; i < len(s.css); i++ { 2658 if s.css[i].dc.dbmuClosed { 2659 s.css[i] = s.css[len(s.css)-1] 2660 s.css = s.css[:len(s.css)-1] 2661 i-- 2662 } 2663 } 2664 s.db.mu.Unlock() 2665 s.lastNumClosed = dbClosed 2666 } 2667 2668 // connStmt returns a free driver connection on which to execute the 2669 // statement, a function to call to release the connection, and a 2670 // statement bound to that connection. 2671 func (s *Stmt) connStmt(ctx context.Context, strategy connReuseStrategy) (dc *driverConn, releaseConn func(error), ds *driverStmt, err error) { 2672 if err = s.stickyErr; err != nil { 2673 return 2674 } 2675 s.mu.Lock() 2676 if s.closed { 2677 s.mu.Unlock() 2678 err = errors.New("sql: statement is closed") 2679 return 2680 } 2681 2682 // In a transaction or connection, we always use the connection that the 2683 // stmt was created on. 2684 if s.cg != nil { 2685 s.mu.Unlock() 2686 dc, releaseConn, err = s.cg.grabConn(ctx) // blocks, waiting for the connection. 2687 if err != nil { 2688 return 2689 } 2690 return dc, releaseConn, s.cgds, nil 2691 } 2692 2693 s.removeClosedStmtLocked() 2694 s.mu.Unlock() 2695 2696 dc, err = s.db.conn(ctx, strategy) 2697 if err != nil { 2698 return nil, nil, nil, err 2699 } 2700 2701 s.mu.Lock() 2702 for _, v := range s.css { 2703 if v.dc == dc { 2704 s.mu.Unlock() 2705 return dc, dc.releaseConn, v.ds, nil 2706 } 2707 } 2708 s.mu.Unlock() 2709 2710 // No luck; we need to prepare the statement on this connection 2711 withLock(dc, func() { 2712 ds, err = s.prepareOnConnLocked(ctx, dc) 2713 }) 2714 if err != nil { 2715 dc.releaseConn(err) 2716 return nil, nil, nil, err 2717 } 2718 2719 return dc, dc.releaseConn, ds, nil 2720 } 2721 2722 // prepareOnConnLocked prepares the query in Stmt s on dc and adds it to the list of 2723 // open connStmt on the statement. It assumes the caller is holding the lock on dc. 2724 func (s *Stmt) prepareOnConnLocked(ctx context.Context, dc *driverConn) (*driverStmt, error) { 2725 si, err := dc.prepareLocked(ctx, s.cg, s.query) 2726 if err != nil { 2727 return nil, err 2728 } 2729 cs := connStmt{dc, si} 2730 s.mu.Lock() 2731 s.css = append(s.css, cs) 2732 s.mu.Unlock() 2733 return cs.ds, nil 2734 } 2735 2736 // QueryContext executes a prepared query statement with the given arguments 2737 // and returns the query results as a *Rows. 2738 func (s *Stmt) QueryContext(ctx context.Context, args ...any) (*Rows, error) { 2739 s.closemu.RLock() 2740 defer s.closemu.RUnlock() 2741 2742 var rowsi driver.Rows 2743 var rows *Rows 2744 2745 err := s.db.retry(func(strategy connReuseStrategy) error { 2746 dc, releaseConn, ds, err := s.connStmt(ctx, strategy) 2747 if err != nil { 2748 return err 2749 } 2750 2751 rowsi, err = rowsiFromStatement(ctx, dc.ci, ds, args...) 2752 if err == nil { 2753 // Note: ownership of ci passes to the *Rows, to be freed 2754 // with releaseConn. 2755 rows = &Rows{ 2756 dc: dc, 2757 rowsi: rowsi, 2758 // releaseConn set below 2759 } 2760 // addDep must be added before initContextClose or it could attempt 2761 // to removeDep before it has been added. 2762 s.db.addDep(s, rows) 2763 2764 // releaseConn must be set before initContextClose or it could 2765 // release the connection before it is set. 2766 rows.releaseConn = func(err error) { 2767 releaseConn(err) 2768 s.db.removeDep(s, rows) 2769 } 2770 var txctx context.Context 2771 if s.cg != nil { 2772 txctx = s.cg.txCtx() 2773 } 2774 rows.initContextClose(ctx, txctx) 2775 return nil 2776 } 2777 2778 releaseConn(err) 2779 return err 2780 }) 2781 2782 return rows, err 2783 } 2784 2785 // Query executes a prepared query statement with the given arguments 2786 // and returns the query results as a *Rows. 2787 // 2788 // Query uses context.Background internally; to specify the context, use 2789 // QueryContext. 2790 func (s *Stmt) Query(args ...any) (*Rows, error) { 2791 return s.QueryContext(context.Background(), args...) 2792 } 2793 2794 func rowsiFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...any) (driver.Rows, error) { 2795 ds.Lock() 2796 defer ds.Unlock() 2797 dargs, err := driverArgsConnLocked(ci, ds, args) 2798 if err != nil { 2799 return nil, err 2800 } 2801 return ctxDriverStmtQuery(ctx, ds.si, dargs) 2802 } 2803 2804 // QueryRowContext executes a prepared query statement with the given arguments. 2805 // If an error occurs during the execution of the statement, that error will 2806 // be returned by a call to Scan on the returned *Row, which is always non-nil. 2807 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 2808 // Otherwise, the *Row's Scan scans the first selected row and discards 2809 // the rest. 2810 func (s *Stmt) QueryRowContext(ctx context.Context, args ...any) *Row { 2811 rows, err := s.QueryContext(ctx, args...) 2812 if err != nil { 2813 return &Row{err: err} 2814 } 2815 return &Row{rows: rows} 2816 } 2817 2818 // QueryRow executes a prepared query statement with the given arguments. 2819 // If an error occurs during the execution of the statement, that error will 2820 // be returned by a call to Scan on the returned *Row, which is always non-nil. 2821 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 2822 // Otherwise, the *Row's Scan scans the first selected row and discards 2823 // the rest. 2824 // 2825 // Example usage: 2826 // 2827 // var name string 2828 // err := nameByUseridStmt.QueryRow(id).Scan(&name) 2829 // 2830 // QueryRow uses context.Background internally; to specify the context, use 2831 // QueryRowContext. 2832 func (s *Stmt) QueryRow(args ...any) *Row { 2833 return s.QueryRowContext(context.Background(), args...) 2834 } 2835 2836 // Close closes the statement. 2837 func (s *Stmt) Close() error { 2838 s.closemu.Lock() 2839 defer s.closemu.Unlock() 2840 2841 if s.stickyErr != nil { 2842 return s.stickyErr 2843 } 2844 s.mu.Lock() 2845 if s.closed { 2846 s.mu.Unlock() 2847 return nil 2848 } 2849 s.closed = true 2850 txds := s.cgds 2851 s.cgds = nil 2852 2853 s.mu.Unlock() 2854 2855 if s.cg == nil { 2856 return s.db.removeDep(s, s) 2857 } 2858 2859 if s.parentStmt != nil { 2860 // If parentStmt is set, we must not close s.txds since it's stored 2861 // in the css array of the parentStmt. 2862 return s.db.removeDep(s.parentStmt, s) 2863 } 2864 return txds.Close() 2865 } 2866 2867 func (s *Stmt) finalClose() error { 2868 s.mu.Lock() 2869 defer s.mu.Unlock() 2870 if s.css != nil { 2871 for _, v := range s.css { 2872 s.db.noteUnusedDriverStatement(v.dc, v.ds) 2873 v.dc.removeOpenStmt(v.ds) 2874 } 2875 s.css = nil 2876 } 2877 return nil 2878 } 2879 2880 // Rows is the result of a query. Its cursor starts before the first row 2881 // of the result set. Use Next to advance from row to row. 2882 type Rows struct { 2883 dc *driverConn // owned; must call releaseConn when closed to release 2884 releaseConn func(error) 2885 rowsi driver.Rows 2886 cancel func() // called when Rows is closed, may be nil. 2887 closeStmt *driverStmt // if non-nil, statement to Close on close 2888 2889 // closemu prevents Rows from closing while there 2890 // is an active streaming result. It is held for read during non-close operations 2891 // and exclusively during close. 2892 // 2893 // closemu guards lasterr and closed. 2894 closemu sync.RWMutex 2895 closed bool 2896 lasterr error // non-nil only if closed is true 2897 2898 // lastcols is only used in Scan, Next, and NextResultSet which are expected 2899 // not to be called concurrently. 2900 lastcols []driver.Value 2901 } 2902 2903 // lasterrOrErrLocked returns either lasterr or the provided err. 2904 // rs.closemu must be read-locked. 2905 func (rs *Rows) lasterrOrErrLocked(err error) error { 2906 if rs.lasterr != nil && rs.lasterr != io.EOF { 2907 return rs.lasterr 2908 } 2909 return err 2910 } 2911 2912 // bypassRowsAwaitDone is only used for testing. 2913 // If true, it will not close the Rows automatically from the context. 2914 var bypassRowsAwaitDone = false 2915 2916 func (rs *Rows) initContextClose(ctx, txctx context.Context) { 2917 if ctx.Done() == nil && (txctx == nil || txctx.Done() == nil) { 2918 return 2919 } 2920 if bypassRowsAwaitDone { 2921 return 2922 } 2923 ctx, rs.cancel = context.WithCancel(ctx) 2924 go rs.awaitDone(ctx, txctx) 2925 } 2926 2927 // awaitDone blocks until either ctx or txctx is canceled. The ctx is provided 2928 // from the query context and is canceled when the query Rows is closed. 2929 // If the query was issued in a transaction, the transaction's context 2930 // is also provided in txctx to ensure Rows is closed if the Tx is closed. 2931 func (rs *Rows) awaitDone(ctx, txctx context.Context) { 2932 var txctxDone <-chan struct{} 2933 if txctx != nil { 2934 txctxDone = txctx.Done() 2935 } 2936 select { 2937 case <-ctx.Done(): 2938 case <-txctxDone: 2939 } 2940 rs.close(ctx.Err()) 2941 } 2942 2943 // Next prepares the next result row for reading with the Scan method. It 2944 // returns true on success, or false if there is no next result row or an error 2945 // happened while preparing it. Err should be consulted to distinguish between 2946 // the two cases. 2947 // 2948 // Every call to Scan, even the first one, must be preceded by a call to Next. 2949 func (rs *Rows) Next() bool { 2950 var doClose, ok bool 2951 withLock(rs.closemu.RLocker(), func() { 2952 doClose, ok = rs.nextLocked() 2953 }) 2954 if doClose { 2955 rs.Close() 2956 } 2957 return ok 2958 } 2959 2960 func (rs *Rows) nextLocked() (doClose, ok bool) { 2961 if rs.closed { 2962 return false, false 2963 } 2964 2965 // Lock the driver connection before calling the driver interface 2966 // rowsi to prevent a Tx from rolling back the connection at the same time. 2967 rs.dc.Lock() 2968 defer rs.dc.Unlock() 2969 2970 if rs.lastcols == nil { 2971 rs.lastcols = make([]driver.Value, len(rs.rowsi.Columns())) 2972 } 2973 2974 rs.lasterr = rs.rowsi.Next(rs.lastcols) 2975 if rs.lasterr != nil { 2976 // Close the connection if there is a driver error. 2977 if rs.lasterr != io.EOF { 2978 return true, false 2979 } 2980 nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet) 2981 if !ok { 2982 return true, false 2983 } 2984 // The driver is at the end of the current result set. 2985 // Test to see if there is another result set after the current one. 2986 // Only close Rows if there is no further result sets to read. 2987 if !nextResultSet.HasNextResultSet() { 2988 doClose = true 2989 } 2990 return doClose, false 2991 } 2992 return false, true 2993 } 2994 2995 // NextResultSet prepares the next result set for reading. It reports whether 2996 // there is further result sets, or false if there is no further result set 2997 // or if there is an error advancing to it. The Err method should be consulted 2998 // to distinguish between the two cases. 2999 // 3000 // After calling NextResultSet, the Next method should always be called before 3001 // scanning. If there are further result sets they may not have rows in the result 3002 // set. 3003 func (rs *Rows) NextResultSet() bool { 3004 var doClose bool 3005 defer func() { 3006 if doClose { 3007 rs.Close() 3008 } 3009 }() 3010 rs.closemu.RLock() 3011 defer rs.closemu.RUnlock() 3012 3013 if rs.closed { 3014 return false 3015 } 3016 3017 rs.lastcols = nil 3018 nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet) 3019 if !ok { 3020 doClose = true 3021 return false 3022 } 3023 3024 // Lock the driver connection before calling the driver interface 3025 // rowsi to prevent a Tx from rolling back the connection at the same time. 3026 rs.dc.Lock() 3027 defer rs.dc.Unlock() 3028 3029 rs.lasterr = nextResultSet.NextResultSet() 3030 if rs.lasterr != nil { 3031 doClose = true 3032 return false 3033 } 3034 return true 3035 } 3036 3037 // Err returns the error, if any, that was encountered during iteration. 3038 // Err may be called after an explicit or implicit Close. 3039 func (rs *Rows) Err() error { 3040 rs.closemu.RLock() 3041 defer rs.closemu.RUnlock() 3042 return rs.lasterrOrErrLocked(nil) 3043 } 3044 3045 var errRowsClosed = errors.New("sql: Rows are closed") 3046 var errNoRows = errors.New("sql: no Rows available") 3047 3048 // Columns returns the column names. 3049 // Columns returns an error if the rows are closed. 3050 func (rs *Rows) Columns() ([]string, error) { 3051 rs.closemu.RLock() 3052 defer rs.closemu.RUnlock() 3053 if rs.closed { 3054 return nil, rs.lasterrOrErrLocked(errRowsClosed) 3055 } 3056 if rs.rowsi == nil { 3057 return nil, rs.lasterrOrErrLocked(errNoRows) 3058 } 3059 rs.dc.Lock() 3060 defer rs.dc.Unlock() 3061 3062 return rs.rowsi.Columns(), nil 3063 } 3064 3065 // ColumnTypes returns column information such as column type, length, 3066 // and nullable. Some information may not be available from some drivers. 3067 func (rs *Rows) ColumnTypes() ([]*ColumnType, error) { 3068 rs.closemu.RLock() 3069 defer rs.closemu.RUnlock() 3070 if rs.closed { 3071 return nil, rs.lasterrOrErrLocked(errRowsClosed) 3072 } 3073 if rs.rowsi == nil { 3074 return nil, rs.lasterrOrErrLocked(errNoRows) 3075 } 3076 rs.dc.Lock() 3077 defer rs.dc.Unlock() 3078 3079 return rowsColumnInfoSetupConnLocked(rs.rowsi), nil 3080 } 3081 3082 // ColumnType contains the name and type of a column. 3083 type ColumnType struct { 3084 name string 3085 3086 hasNullable bool 3087 hasLength bool 3088 hasPrecisionScale bool 3089 3090 nullable bool 3091 length int64 3092 databaseType string 3093 precision int64 3094 scale int64 3095 scanType reflect.Type 3096 } 3097 3098 // Name returns the name or alias of the column. 3099 func (ci *ColumnType) Name() string { 3100 return ci.name 3101 } 3102 3103 // Length returns the column type length for variable length column types such 3104 // as text and binary field types. If the type length is unbounded the value will 3105 // be math.MaxInt64 (any database limits will still apply). 3106 // If the column type is not variable length, such as an int, or if not supported 3107 // by the driver ok is false. 3108 func (ci *ColumnType) Length() (length int64, ok bool) { 3109 return ci.length, ci.hasLength 3110 } 3111 3112 // DecimalSize returns the scale and precision of a decimal type. 3113 // If not applicable or if not supported ok is false. 3114 func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool) { 3115 return ci.precision, ci.scale, ci.hasPrecisionScale 3116 } 3117 3118 // ScanType returns a Go type suitable for scanning into using Rows.Scan. 3119 // If a driver does not support this property ScanType will return 3120 // the type of an empty interface. 3121 func (ci *ColumnType) ScanType() reflect.Type { 3122 return ci.scanType 3123 } 3124 3125 // Nullable reports whether the column may be null. 3126 // If a driver does not support this property ok will be false. 3127 func (ci *ColumnType) Nullable() (nullable, ok bool) { 3128 return ci.nullable, ci.hasNullable 3129 } 3130 3131 // DatabaseTypeName returns the database system name of the column type. If an empty 3132 // string is returned, then the driver type name is not supported. 3133 // Consult your driver documentation for a list of driver data types. Length specifiers 3134 // are not included. 3135 // Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL", 3136 // "INT", and "BIGINT". 3137 func (ci *ColumnType) DatabaseTypeName() string { 3138 return ci.databaseType 3139 } 3140 3141 func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType { 3142 names := rowsi.Columns() 3143 3144 list := make([]*ColumnType, len(names)) 3145 for i := range list { 3146 ci := &ColumnType{ 3147 name: names[i], 3148 } 3149 list[i] = ci 3150 3151 if prop, ok := rowsi.(driver.RowsColumnTypeScanType); ok { 3152 ci.scanType = prop.ColumnTypeScanType(i) 3153 } else { 3154 ci.scanType = reflect.TypeOf(new(any)).Elem() 3155 } 3156 if prop, ok := rowsi.(driver.RowsColumnTypeDatabaseTypeName); ok { 3157 ci.databaseType = prop.ColumnTypeDatabaseTypeName(i) 3158 } 3159 if prop, ok := rowsi.(driver.RowsColumnTypeLength); ok { 3160 ci.length, ci.hasLength = prop.ColumnTypeLength(i) 3161 } 3162 if prop, ok := rowsi.(driver.RowsColumnTypeNullable); ok { 3163 ci.nullable, ci.hasNullable = prop.ColumnTypeNullable(i) 3164 } 3165 if prop, ok := rowsi.(driver.RowsColumnTypePrecisionScale); ok { 3166 ci.precision, ci.scale, ci.hasPrecisionScale = prop.ColumnTypePrecisionScale(i) 3167 } 3168 } 3169 return list 3170 } 3171 3172 // Scan copies the columns in the current row into the values pointed 3173 // at by dest. The number of values in dest must be the same as the 3174 // number of columns in Rows. 3175 // 3176 // Scan converts columns read from the database into the following 3177 // common Go types and special types provided by the sql package: 3178 // 3179 // *string 3180 // *[]byte 3181 // *int, *int8, *int16, *int32, *int64 3182 // *uint, *uint8, *uint16, *uint32, *uint64 3183 // *bool 3184 // *float32, *float64 3185 // *interface{} 3186 // *RawBytes 3187 // *Rows (cursor value) 3188 // any type implementing Scanner (see Scanner docs) 3189 // 3190 // In the most simple case, if the type of the value from the source 3191 // column is an integer, bool or string type T and dest is of type *T, 3192 // Scan simply assigns the value through the pointer. 3193 // 3194 // Scan also converts between string and numeric types, as long as no 3195 // information would be lost. While Scan stringifies all numbers 3196 // scanned from numeric database columns into *string, scans into 3197 // numeric types are checked for overflow. For example, a float64 with 3198 // value 300 or a string with value "300" can scan into a uint16, but 3199 // not into a uint8, though float64(255) or "255" can scan into a 3200 // uint8. One exception is that scans of some float64 numbers to 3201 // strings may lose information when stringifying. In general, scan 3202 // floating point columns into *float64. 3203 // 3204 // If a dest argument has type *[]byte, Scan saves in that argument a 3205 // copy of the corresponding data. The copy is owned by the caller and 3206 // can be modified and held indefinitely. The copy can be avoided by 3207 // using an argument of type *RawBytes instead; see the documentation 3208 // for RawBytes for restrictions on its use. 3209 // 3210 // If an argument has type *interface{}, Scan copies the value 3211 // provided by the underlying driver without conversion. When scanning 3212 // from a source value of type []byte to *interface{}, a copy of the 3213 // slice is made and the caller owns the result. 3214 // 3215 // Source values of type time.Time may be scanned into values of type 3216 // *time.Time, *interface{}, *string, or *[]byte. When converting to 3217 // the latter two, time.RFC3339Nano is used. 3218 // 3219 // Source values of type bool may be scanned into types *bool, 3220 // *interface{}, *string, *[]byte, or *RawBytes. 3221 // 3222 // For scanning into *bool, the source may be true, false, 1, 0, or 3223 // string inputs parseable by strconv.ParseBool. 3224 // 3225 // Scan can also convert a cursor returned from a query, such as 3226 // "select cursor(select * from my_table) from dual", into a 3227 // *Rows value that can itself be scanned from. The parent 3228 // select query will close any cursor *Rows if the parent *Rows is closed. 3229 // 3230 // If any of the first arguments implementing Scanner returns an error, 3231 // that error will be wrapped in the returned error 3232 func (rs *Rows) Scan(dest ...any) error { 3233 rs.closemu.RLock() 3234 3235 if rs.lasterr != nil && rs.lasterr != io.EOF { 3236 rs.closemu.RUnlock() 3237 return rs.lasterr 3238 } 3239 if rs.closed { 3240 err := rs.lasterrOrErrLocked(errRowsClosed) 3241 rs.closemu.RUnlock() 3242 return err 3243 } 3244 rs.closemu.RUnlock() 3245 3246 if rs.lastcols == nil { 3247 return errors.New("sql: Scan called without calling Next") 3248 } 3249 if len(dest) != len(rs.lastcols) { 3250 return fmt.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest)) 3251 } 3252 for i, sv := range rs.lastcols { 3253 err := convertAssignRows(dest[i], sv, rs) 3254 if err != nil { 3255 return fmt.Errorf(`sql: Scan error on column index %d, name %q: %w`, i, rs.rowsi.Columns()[i], err) 3256 } 3257 } 3258 return nil 3259 } 3260 3261 // rowsCloseHook returns a function so tests may install the 3262 // hook through a test only mutex. 3263 var rowsCloseHook = func() func(*Rows, *error) { return nil } 3264 3265 // Close closes the Rows, preventing further enumeration. If Next is called 3266 // and returns false and there are no further result sets, 3267 // the Rows are closed automatically and it will suffice to check the 3268 // result of Err. Close is idempotent and does not affect the result of Err. 3269 func (rs *Rows) Close() error { 3270 return rs.close(nil) 3271 } 3272 3273 func (rs *Rows) close(err error) error { 3274 rs.closemu.Lock() 3275 defer rs.closemu.Unlock() 3276 3277 if rs.closed { 3278 return nil 3279 } 3280 rs.closed = true 3281 3282 if rs.lasterr == nil { 3283 rs.lasterr = err 3284 } 3285 3286 withLock(rs.dc, func() { 3287 err = rs.rowsi.Close() 3288 }) 3289 if fn := rowsCloseHook(); fn != nil { 3290 fn(rs, &err) 3291 } 3292 if rs.cancel != nil { 3293 rs.cancel() 3294 } 3295 3296 if rs.closeStmt != nil { 3297 rs.closeStmt.Close() 3298 } 3299 rs.releaseConn(err) 3300 3301 rs.lasterr = rs.lasterrOrErrLocked(err) 3302 return err 3303 } 3304 3305 // Row is the result of calling QueryRow to select a single row. 3306 type Row struct { 3307 // One of these two will be non-nil: 3308 err error // deferred error for easy chaining 3309 rows *Rows 3310 } 3311 3312 // Scan copies the columns from the matched row into the values 3313 // pointed at by dest. See the documentation on Rows.Scan for details. 3314 // If more than one row matches the query, 3315 // Scan uses the first row and discards the rest. If no row matches 3316 // the query, Scan returns ErrNoRows. 3317 func (r *Row) Scan(dest ...any) error { 3318 if r.err != nil { 3319 return r.err 3320 } 3321 3322 // TODO(bradfitz): for now we need to defensively clone all 3323 // []byte that the driver returned (not permitting 3324 // *RawBytes in Rows.Scan), since we're about to close 3325 // the Rows in our defer, when we return from this function. 3326 // the contract with the driver.Next(...) interface is that it 3327 // can return slices into read-only temporary memory that's 3328 // only valid until the next Scan/Close. But the TODO is that 3329 // for a lot of drivers, this copy will be unnecessary. We 3330 // should provide an optional interface for drivers to 3331 // implement to say, "don't worry, the []bytes that I return 3332 // from Next will not be modified again." (for instance, if 3333 // they were obtained from the network anyway) But for now we 3334 // don't care. 3335 defer r.rows.Close() 3336 for _, dp := range dest { 3337 if _, ok := dp.(*RawBytes); ok { 3338 return errors.New("sql: RawBytes isn't allowed on Row.Scan") 3339 } 3340 } 3341 3342 if !r.rows.Next() { 3343 if err := r.rows.Err(); err != nil { 3344 return err 3345 } 3346 return ErrNoRows 3347 } 3348 err := r.rows.Scan(dest...) 3349 if err != nil { 3350 return err 3351 } 3352 // Make sure the query can be processed to completion with no errors. 3353 return r.rows.Close() 3354 } 3355 3356 // Err provides a way for wrapping packages to check for 3357 // query errors without calling Scan. 3358 // Err returns the error, if any, that was encountered while running the query. 3359 // If this error is not nil, this error will also be returned from Scan. 3360 func (r *Row) Err() error { 3361 return r.err 3362 } 3363 3364 // A Result summarizes an executed SQL command. 3365 type Result interface { 3366 // LastInsertId returns the integer generated by the database 3367 // in response to a command. Typically this will be from an 3368 // "auto increment" column when inserting a new row. Not all 3369 // databases support this feature, and the syntax of such 3370 // statements varies. 3371 LastInsertId() (int64, error) 3372 3373 // RowsAffected returns the number of rows affected by an 3374 // update, insert, or delete. Not every database or database 3375 // driver may support this. 3376 RowsAffected() (int64, error) 3377 } 3378 3379 type driverResult struct { 3380 sync.Locker // the *driverConn 3381 resi driver.Result 3382 } 3383 3384 func (dr driverResult) LastInsertId() (int64, error) { 3385 dr.Lock() 3386 defer dr.Unlock() 3387 return dr.resi.LastInsertId() 3388 } 3389 3390 func (dr driverResult) RowsAffected() (int64, error) { 3391 dr.Lock() 3392 defer dr.Unlock() 3393 return dr.resi.RowsAffected() 3394 } 3395 3396 func stack() string { 3397 var buf [2 << 10]byte 3398 return string(buf[:runtime.Stack(buf[:], false)]) 3399 } 3400 3401 // withLock runs while holding lk. 3402 func withLock(lk sync.Locker, fn func()) { 3403 lk.Lock() 3404 defer lk.Unlock() // in case fn panics 3405 fn() 3406 }