Source file src/pkg/database/sql/sql.go
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 package sql 8 9 import ( 10 "database/sql/driver" 11 "errors" 12 "fmt" 13 "io" 14 "sync" 15 ) 16 17 var drivers = make(map[string]driver.Driver) 18 19 // Register makes a database driver available by the provided name. 20 // If Register is called twice with the same name or if driver is nil, 21 // it panics. 22 func Register(name string, driver driver.Driver) { 23 if driver == nil { 24 panic("sql: Register driver is nil") 25 } 26 if _, dup := drivers[name]; dup { 27 panic("sql: Register called twice for driver " + name) 28 } 29 drivers[name] = driver 30 } 31 32 // RawBytes is a byte slice that holds a reference to memory owned by 33 // the database itself. After a Scan into a RawBytes, the slice is only 34 // valid until the next call to Next, Scan, or Close. 35 type RawBytes []byte 36 37 // NullString represents a string that may be null. 38 // NullString implements the Scanner interface so 39 // it can be used as a scan destination: 40 // 41 // var s NullString 42 // err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s) 43 // ... 44 // if s.Valid { 45 // // use s.String 46 // } else { 47 // // NULL value 48 // } 49 // 50 type NullString struct { 51 String string 52 Valid bool // Valid is true if String is not NULL 53 } 54 55 // Scan implements the Scanner interface. 56 func (ns *NullString) Scan(value interface{}) error { 57 if value == nil { 58 ns.String, ns.Valid = "", false 59 return nil 60 } 61 ns.Valid = true 62 return convertAssign(&ns.String, value) 63 } 64 65 // Value implements the driver Valuer interface. 66 func (ns NullString) Value() (driver.Value, error) { 67 if !ns.Valid { 68 return nil, nil 69 } 70 return ns.String, nil 71 } 72 73 // NullInt64 represents an int64 that may be null. 74 // NullInt64 implements the Scanner interface so 75 // it can be used as a scan destination, similar to NullString. 76 type NullInt64 struct { 77 Int64 int64 78 Valid bool // Valid is true if Int64 is not NULL 79 } 80 81 // Scan implements the Scanner interface. 82 func (n *NullInt64) Scan(value interface{}) error { 83 if value == nil { 84 n.Int64, n.Valid = 0, false 85 return nil 86 } 87 n.Valid = true 88 return convertAssign(&n.Int64, value) 89 } 90 91 // Value implements the driver Valuer interface. 92 func (n NullInt64) Value() (driver.Value, error) { 93 if !n.Valid { 94 return nil, nil 95 } 96 return n.Int64, nil 97 } 98 99 // NullFloat64 represents a float64 that may be null. 100 // NullFloat64 implements the Scanner interface so 101 // it can be used as a scan destination, similar to NullString. 102 type NullFloat64 struct { 103 Float64 float64 104 Valid bool // Valid is true if Float64 is not NULL 105 } 106 107 // Scan implements the Scanner interface. 108 func (n *NullFloat64) Scan(value interface{}) error { 109 if value == nil { 110 n.Float64, n.Valid = 0, false 111 return nil 112 } 113 n.Valid = true 114 return convertAssign(&n.Float64, value) 115 } 116 117 // Value implements the driver Valuer interface. 118 func (n NullFloat64) Value() (driver.Value, error) { 119 if !n.Valid { 120 return nil, nil 121 } 122 return n.Float64, nil 123 } 124 125 // NullBool represents a bool that may be null. 126 // NullBool implements the Scanner interface so 127 // it can be used as a scan destination, similar to NullString. 128 type NullBool struct { 129 Bool bool 130 Valid bool // Valid is true if Bool is not NULL 131 } 132 133 // Scan implements the Scanner interface. 134 func (n *NullBool) Scan(value interface{}) error { 135 if value == nil { 136 n.Bool, n.Valid = false, false 137 return nil 138 } 139 n.Valid = true 140 return convertAssign(&n.Bool, value) 141 } 142 143 // Value implements the driver Valuer interface. 144 func (n NullBool) Value() (driver.Value, error) { 145 if !n.Valid { 146 return nil, nil 147 } 148 return n.Bool, nil 149 } 150 151 // Scanner is an interface used by Scan. 152 type Scanner interface { 153 // Scan assigns a value from a database driver. 154 // 155 // The src value will be of one of the following restricted 156 // set of types: 157 // 158 // int64 159 // float64 160 // bool 161 // []byte 162 // string 163 // time.Time 164 // nil - for NULL values 165 // 166 // An error should be returned if the value can not be stored 167 // without loss of information. 168 Scan(src interface{}) error 169 } 170 171 // ErrNoRows is returned by Scan when QueryRow doesn't return a 172 // row. In such a case, QueryRow returns a placeholder *Row value that 173 // defers this error until a Scan. 174 var ErrNoRows = errors.New("sql: no rows in result set") 175 176 // DB is a database handle. It's safe for concurrent use by multiple 177 // goroutines. 178 // 179 // If the underlying database driver has the concept of a connection 180 // and per-connection session state, the sql package manages creating 181 // and freeing connections automatically, including maintaining a free 182 // pool of idle connections. If observing session state is required, 183 // either do not share a *DB between multiple concurrent goroutines or 184 // create and observe all state only within a transaction. Once 185 // DB.Open is called, the returned Tx is bound to a single isolated 186 // connection. Once Tx.Commit or Tx.Rollback is called, that 187 // connection is returned to DB's idle connection pool. 188 type DB struct { 189 driver driver.Driver 190 dsn string 191 192 mu sync.Mutex // protects freeConn and closed 193 freeConn []driver.Conn 194 closed bool 195 } 196 197 // Open opens a database specified by its database driver name and a 198 // driver-specific data source name, usually consisting of at least a 199 // database name and connection information. 200 // 201 // Most users will open a database via a driver-specific connection 202 // helper function that returns a *DB. 203 func Open(driverName, dataSourceName string) (*DB, error) { 204 driver, ok := drivers[driverName] 205 if !ok { 206 return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName) 207 } 208 return &DB{driver: driver, dsn: dataSourceName}, nil 209 } 210 211 // Close closes the database, releasing any open resources. 212 func (db *DB) Close() error { 213 db.mu.Lock() 214 defer db.mu.Unlock() 215 var err error 216 for _, c := range db.freeConn { 217 err1 := c.Close() 218 if err1 != nil { 219 err = err1 220 } 221 } 222 db.freeConn = nil 223 db.closed = true 224 return err 225 } 226 227 func (db *DB) maxIdleConns() int { 228 const defaultMaxIdleConns = 2 229 // TODO(bradfitz): ask driver, if supported, for its default preference 230 // TODO(bradfitz): let users override? 231 return defaultMaxIdleConns 232 } 233 234 // conn returns a newly-opened or cached driver.Conn 235 func (db *DB) conn() (driver.Conn, error) { 236 db.mu.Lock() 237 if db.closed { 238 db.mu.Unlock() 239 return nil, errors.New("sql: database is closed") 240 } 241 if n := len(db.freeConn); n > 0 { 242 conn := db.freeConn[n-1] 243 db.freeConn = db.freeConn[:n-1] 244 db.mu.Unlock() 245 return conn, nil 246 } 247 db.mu.Unlock() 248 return db.driver.Open(db.dsn) 249 } 250 251 func (db *DB) connIfFree(wanted driver.Conn) (conn driver.Conn, ok bool) { 252 db.mu.Lock() 253 defer db.mu.Unlock() 254 for i, conn := range db.freeConn { 255 if conn != wanted { 256 continue 257 } 258 db.freeConn[i] = db.freeConn[len(db.freeConn)-1] 259 db.freeConn = db.freeConn[:len(db.freeConn)-1] 260 return wanted, true 261 } 262 return nil, false 263 } 264 265 // putConnHook is a hook for testing. 266 var putConnHook func(*DB, driver.Conn) 267 268 // putConn adds a connection to the db's free pool. 269 // err is optionally the last error that occured on this connection. 270 func (db *DB) putConn(c driver.Conn, err error) { 271 if err == driver.ErrBadConn { 272 // Don't reuse bad connections. 273 return 274 } 275 db.mu.Lock() 276 if putConnHook != nil { 277 putConnHook(db, c) 278 } 279 if n := len(db.freeConn); !db.closed && n < db.maxIdleConns() { 280 db.freeConn = append(db.freeConn, c) 281 db.mu.Unlock() 282 return 283 } 284 // TODO: check to see if we need this Conn for any prepared 285 // statements which are still active? 286 db.mu.Unlock() 287 c.Close() 288 } 289 290 // Prepare creates a prepared statement for later execution. 291 func (db *DB) Prepare(query string) (*Stmt, error) { 292 var stmt *Stmt 293 var err error 294 for i := 0; i < 10; i++ { 295 stmt, err = db.prepare(query) 296 if err != driver.ErrBadConn { 297 break 298 } 299 } 300 return stmt, err 301 } 302 303 func (db *DB) prepare(query string) (stmt *Stmt, err error) { 304 // TODO: check if db.driver supports an optional 305 // driver.Preparer interface and call that instead, if so, 306 // otherwise we make a prepared statement that's bound 307 // to a connection, and to execute this prepared statement 308 // we either need to use this connection (if it's free), else 309 // get a new connection + re-prepare + execute on that one. 310 ci, err := db.conn() 311 if err != nil { 312 return nil, err 313 } 314 defer db.putConn(ci, err) 315 si, err := ci.Prepare(query) 316 if err != nil { 317 return nil, err 318 } 319 stmt = &Stmt{ 320 db: db, 321 query: query, 322 css: []connStmt{{ci, si}}, 323 } 324 return stmt, nil 325 } 326 327 // Exec executes a query without returning any rows. 328 func (db *DB) Exec(query string, args ...interface{}) (Result, error) { 329 sargs, err := subsetTypeArgs(args) 330 if err != nil { 331 return nil, err 332 } 333 var res Result 334 for i := 0; i < 10; i++ { 335 res, err = db.exec(query, sargs) 336 if err != driver.ErrBadConn { 337 break 338 } 339 } 340 return res, err 341 } 342 343 func (db *DB) exec(query string, sargs []driver.Value) (res Result, err error) { 344 ci, err := db.conn() 345 if err != nil { 346 return nil, err 347 } 348 defer db.putConn(ci, err) 349 350 if execer, ok := ci.(driver.Execer); ok { 351 resi, err := execer.Exec(query, sargs) 352 if err != driver.ErrSkip { 353 if err != nil { 354 return nil, err 355 } 356 return result{resi}, nil 357 } 358 } 359 360 sti, err := ci.Prepare(query) 361 if err != nil { 362 return nil, err 363 } 364 defer sti.Close() 365 366 resi, err := sti.Exec(sargs) 367 if err != nil { 368 return nil, err 369 } 370 return result{resi}, nil 371 } 372 373 // Query executes a query that returns rows, typically a SELECT. 374 func (db *DB) Query(query string, args ...interface{}) (*Rows, error) { 375 stmt, err := db.Prepare(query) 376 if err != nil { 377 return nil, err 378 } 379 rows, err := stmt.Query(args...) 380 if err != nil { 381 stmt.Close() 382 return nil, err 383 } 384 rows.closeStmt = stmt 385 return rows, nil 386 } 387 388 // QueryRow executes a query that is expected to return at most one row. 389 // QueryRow always return a non-nil value. Errors are deferred until 390 // Row's Scan method is called. 391 func (db *DB) QueryRow(query string, args ...interface{}) *Row { 392 rows, err := db.Query(query, args...) 393 return &Row{rows: rows, err: err} 394 } 395 396 // Begin starts a transaction. The isolation level is dependent on 397 // the driver. 398 func (db *DB) Begin() (*Tx, error) { 399 var tx *Tx 400 var err error 401 for i := 0; i < 10; i++ { 402 tx, err = db.begin() 403 if err != driver.ErrBadConn { 404 break 405 } 406 } 407 return tx, err 408 } 409 410 func (db *DB) begin() (tx *Tx, err error) { 411 ci, err := db.conn() 412 if err != nil { 413 return nil, err 414 } 415 txi, err := ci.Begin() 416 if err != nil { 417 db.putConn(ci, err) 418 return nil, fmt.Errorf("sql: failed to Begin transaction: %v", err) 419 } 420 return &Tx{ 421 db: db, 422 ci: ci, 423 txi: txi, 424 }, nil 425 } 426 427 // Driver returns the database's underlying driver. 428 func (db *DB) Driver() driver.Driver { 429 return db.driver 430 } 431 432 // Tx is an in-progress database transaction. 433 // 434 // A transaction must end with a call to Commit or Rollback. 435 // 436 // After a call to Commit or Rollback, all operations on the 437 // transaction fail with ErrTxDone. 438 type Tx struct { 439 db *DB 440 441 // ci is owned exclusively until Commit or Rollback, at which point 442 // it's returned with putConn. 443 ci driver.Conn 444 txi driver.Tx 445 446 // cimu is held while somebody is using ci (between grabConn 447 // and releaseConn) 448 cimu sync.Mutex 449 450 // done transitions from false to true exactly once, on Commit 451 // or Rollback. once done, all operations fail with 452 // ErrTxDone. 453 done bool 454 } 455 456 var ErrTxDone = errors.New("sql: Transaction has already been committed or rolled back") 457 458 func (tx *Tx) close() { 459 if tx.done { 460 panic("double close") // internal error 461 } 462 tx.done = true 463 tx.db.putConn(tx.ci, nil) 464 tx.ci = nil 465 tx.txi = nil 466 } 467 468 func (tx *Tx) grabConn() (driver.Conn, error) { 469 if tx.done { 470 return nil, ErrTxDone 471 } 472 tx.cimu.Lock() 473 return tx.ci, nil 474 } 475 476 func (tx *Tx) releaseConn() { 477 tx.cimu.Unlock() 478 } 479 480 // Commit commits the transaction. 481 func (tx *Tx) Commit() error { 482 if tx.done { 483 return ErrTxDone 484 } 485 defer tx.close() 486 return tx.txi.Commit() 487 } 488 489 // Rollback aborts the transaction. 490 func (tx *Tx) Rollback() error { 491 if tx.done { 492 return ErrTxDone 493 } 494 defer tx.close() 495 return tx.txi.Rollback() 496 } 497 498 // Prepare creates a prepared statement for use within a transaction. 499 // 500 // The returned statement operates within the transaction and can no longer 501 // be used once the transaction has been committed or rolled back. 502 // 503 // To use an existing prepared statement on this transaction, see Tx.Stmt. 504 func (tx *Tx) Prepare(query string) (*Stmt, error) { 505 // TODO(bradfitz): We could be more efficient here and either 506 // provide a method to take an existing Stmt (created on 507 // perhaps a different Conn), and re-create it on this Conn if 508 // necessary. Or, better: keep a map in DB of query string to 509 // Stmts, and have Stmt.Execute do the right thing and 510 // re-prepare if the Conn in use doesn't have that prepared 511 // statement. But we'll want to avoid caching the statement 512 // in the case where we only call conn.Prepare implicitly 513 // (such as in db.Exec or tx.Exec), but the caller package 514 // can't be holding a reference to the returned statement. 515 // Perhaps just looking at the reference count (by noting 516 // Stmt.Close) would be enough. We might also want a finalizer 517 // on Stmt to drop the reference count. 518 ci, err := tx.grabConn() 519 if err != nil { 520 return nil, err 521 } 522 defer tx.releaseConn() 523 524 si, err := ci.Prepare(query) 525 if err != nil { 526 return nil, err 527 } 528 529 stmt := &Stmt{ 530 db: tx.db, 531 tx: tx, 532 txsi: si, 533 query: query, 534 } 535 return stmt, nil 536 } 537 538 // Stmt returns a transaction-specific prepared statement from 539 // an existing statement. 540 // 541 // Example: 542 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") 543 // ... 544 // tx, err := db.Begin() 545 // ... 546 // res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203) 547 func (tx *Tx) Stmt(stmt *Stmt) *Stmt { 548 // TODO(bradfitz): optimize this. Currently this re-prepares 549 // each time. This is fine for now to illustrate the API but 550 // we should really cache already-prepared statements 551 // per-Conn. See also the big comment in Tx.Prepare. 552 553 if tx.db != stmt.db { 554 return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")} 555 } 556 ci, err := tx.grabConn() 557 if err != nil { 558 return &Stmt{stickyErr: err} 559 } 560 defer tx.releaseConn() 561 si, err := ci.Prepare(stmt.query) 562 return &Stmt{ 563 db: tx.db, 564 tx: tx, 565 txsi: si, 566 query: stmt.query, 567 stickyErr: err, 568 } 569 } 570 571 // Exec executes a query that doesn't return rows. 572 // For example: an INSERT and UPDATE. 573 func (tx *Tx) Exec(query string, args ...interface{}) (Result, error) { 574 ci, err := tx.grabConn() 575 if err != nil { 576 return nil, err 577 } 578 defer tx.releaseConn() 579 580 sargs, err := subsetTypeArgs(args) 581 if err != nil { 582 return nil, err 583 } 584 585 if execer, ok := ci.(driver.Execer); ok { 586 resi, err := execer.Exec(query, sargs) 587 if err == nil { 588 return result{resi}, nil 589 } 590 if err != driver.ErrSkip { 591 return nil, err 592 } 593 } 594 595 sti, err := ci.Prepare(query) 596 if err != nil { 597 return nil, err 598 } 599 defer sti.Close() 600 601 resi, err := sti.Exec(sargs) 602 if err != nil { 603 return nil, err 604 } 605 return result{resi}, nil 606 } 607 608 // Query executes a query that returns rows, typically a SELECT. 609 func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) { 610 if tx.done { 611 return nil, ErrTxDone 612 } 613 stmt, err := tx.Prepare(query) 614 if err != nil { 615 return nil, err 616 } 617 rows, err := stmt.Query(args...) 618 if err != nil { 619 stmt.Close() 620 return nil, err 621 } 622 rows.closeStmt = stmt 623 return rows, err 624 } 625 626 // QueryRow executes a query that is expected to return at most one row. 627 // QueryRow always return a non-nil value. Errors are deferred until 628 // Row's Scan method is called. 629 func (tx *Tx) QueryRow(query string, args ...interface{}) *Row { 630 rows, err := tx.Query(query, args...) 631 return &Row{rows: rows, err: err} 632 } 633 634 // connStmt is a prepared statement on a particular connection. 635 type connStmt struct { 636 ci driver.Conn 637 si driver.Stmt 638 } 639 640 // Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines. 641 type Stmt struct { 642 // Immutable: 643 db *DB // where we came from 644 query string // that created the Stmt 645 stickyErr error // if non-nil, this error is returned for all operations 646 647 // If in a transaction, else both nil: 648 tx *Tx 649 txsi driver.Stmt 650 651 mu sync.Mutex // protects the rest of the fields 652 closed bool 653 654 // css is a list of underlying driver statement interfaces 655 // that are valid on particular connections. This is only 656 // used if tx == nil and one is found that has idle 657 // connections. If tx != nil, txsi is always used. 658 css []connStmt 659 } 660 661 // Exec executes a prepared statement with the given arguments and 662 // returns a Result summarizing the effect of the statement. 663 func (s *Stmt) Exec(args ...interface{}) (Result, error) { 664 _, releaseConn, si, err := s.connStmt() 665 if err != nil { 666 return nil, err 667 } 668 defer releaseConn(nil) 669 670 // -1 means the driver doesn't know how to count the number of 671 // placeholders, so we won't sanity check input here and instead let the 672 // driver deal with errors. 673 if want := si.NumInput(); want != -1 && len(args) != want { 674 return nil, fmt.Errorf("sql: expected %d arguments, got %d", want, len(args)) 675 } 676 677 sargs := make([]driver.Value, len(args)) 678 679 // Convert args to subset types. 680 if cc, ok := si.(driver.ColumnConverter); ok { 681 for n, arg := range args { 682 // First, see if the value itself knows how to convert 683 // itself to a driver type. For example, a NullString 684 // struct changing into a string or nil. 685 if svi, ok := arg.(driver.Valuer); ok { 686 sv, err := svi.Value() 687 if err != nil { 688 return nil, fmt.Errorf("sql: argument index %d from Value: %v", n, err) 689 } 690 if !driver.IsValue(sv) { 691 return nil, fmt.Errorf("sql: argument index %d: non-subset type %T returned from Value", n, sv) 692 } 693 arg = sv 694 } 695 696 // Second, ask the column to sanity check itself. For 697 // example, drivers might use this to make sure that 698 // an int64 values being inserted into a 16-bit 699 // integer field is in range (before getting 700 // truncated), or that a nil can't go into a NOT NULL 701 // column before going across the network to get the 702 // same error. 703 sargs[n], err = cc.ColumnConverter(n).ConvertValue(arg) 704 if err != nil { 705 return nil, fmt.Errorf("sql: converting Exec argument #%d's type: %v", n, err) 706 } 707 if !driver.IsValue(sargs[n]) { 708 return nil, fmt.Errorf("sql: driver ColumnConverter error converted %T to unsupported type %T", 709 arg, sargs[n]) 710 } 711 } 712 } else { 713 for n, arg := range args { 714 sargs[n], err = driver.DefaultParameterConverter.ConvertValue(arg) 715 if err != nil { 716 return nil, fmt.Errorf("sql: converting Exec argument #%d's type: %v", n, err) 717 } 718 } 719 } 720 721 resi, err := si.Exec(sargs) 722 if err != nil { 723 return nil, err 724 } 725 return result{resi}, nil 726 } 727 728 // connStmt returns a free driver connection on which to execute the 729 // statement, a function to call to release the connection, and a 730 // statement bound to that connection. 731 func (s *Stmt) connStmt() (ci driver.Conn, releaseConn func(error), si driver.Stmt, err error) { 732 if err = s.stickyErr; err != nil { 733 return 734 } 735 s.mu.Lock() 736 if s.closed { 737 s.mu.Unlock() 738 err = errors.New("sql: statement is closed") 739 return 740 } 741 742 // In a transaction, we always use the connection that the 743 // transaction was created on. 744 if s.tx != nil { 745 s.mu.Unlock() 746 ci, err = s.tx.grabConn() // blocks, waiting for the connection. 747 if err != nil { 748 return 749 } 750 releaseConn = func(error) { s.tx.releaseConn() } 751 return ci, releaseConn, s.txsi, nil 752 } 753 754 var cs connStmt 755 match := false 756 for _, v := range s.css { 757 // TODO(bradfitz): lazily clean up entries in this 758 // list with dead conns while enumerating 759 if _, match = s.db.connIfFree(v.ci); match { 760 cs = v 761 break 762 } 763 } 764 s.mu.Unlock() 765 766 // Make a new conn if all are busy. 767 // TODO(bradfitz): or wait for one? make configurable later? 768 if !match { 769 for i := 0; ; i++ { 770 ci, err := s.db.conn() 771 if err != nil { 772 return nil, nil, nil, err 773 } 774 si, err := ci.Prepare(s.query) 775 if err == driver.ErrBadConn && i < 10 { 776 continue 777 } 778 if err != nil { 779 return nil, nil, nil, err 780 } 781 s.mu.Lock() 782 cs = connStmt{ci, si} 783 s.css = append(s.css, cs) 784 s.mu.Unlock() 785 break 786 } 787 } 788 789 conn := cs.ci 790 releaseConn = func(err error) { s.db.putConn(conn, err) } 791 return conn, releaseConn, cs.si, nil 792 } 793 794 // Query executes a prepared query statement with the given arguments 795 // and returns the query results as a *Rows. 796 func (s *Stmt) Query(args ...interface{}) (*Rows, error) { 797 ci, releaseConn, si, err := s.connStmt() 798 if err != nil { 799 return nil, err 800 } 801 802 // -1 means the driver doesn't know how to count the number of 803 // placeholders, so we won't sanity check input here and instead let the 804 // driver deal with errors. 805 if want := si.NumInput(); want != -1 && len(args) != want { 806 return nil, fmt.Errorf("sql: statement expects %d inputs; got %d", si.NumInput(), len(args)) 807 } 808 sargs, err := subsetTypeArgs(args) 809 if err != nil { 810 return nil, err 811 } 812 rowsi, err := si.Query(sargs) 813 if err != nil { 814 releaseConn(err) 815 return nil, err 816 } 817 // Note: ownership of ci passes to the *Rows, to be freed 818 // with releaseConn. 819 rows := &Rows{ 820 db: s.db, 821 ci: ci, 822 releaseConn: releaseConn, 823 rowsi: rowsi, 824 } 825 return rows, nil 826 } 827 828 // QueryRow executes a prepared query statement with the given arguments. 829 // If an error occurs during the execution of the statement, that error will 830 // be returned by a call to Scan on the returned *Row, which is always non-nil. 831 // If the query selects no rows, the *Row's Scan will return ErrNoRows. 832 // Otherwise, the *Row's Scan scans the first selected row and discards 833 // the rest. 834 // 835 // Example usage: 836 // 837 // var name string 838 // err := nameByUseridStmt.QueryRow(id).Scan(&name) 839 func (s *Stmt) QueryRow(args ...interface{}) *Row { 840 rows, err := s.Query(args...) 841 if err != nil { 842 return &Row{err: err} 843 } 844 return &Row{rows: rows} 845 } 846 847 // Close closes the statement. 848 func (s *Stmt) Close() error { 849 if s.stickyErr != nil { 850 return s.stickyErr 851 } 852 s.mu.Lock() 853 defer s.mu.Unlock() 854 if s.closed { 855 return nil 856 } 857 s.closed = true 858 859 if s.tx != nil { 860 s.txsi.Close() 861 } else { 862 for _, v := range s.css { 863 if ci, match := s.db.connIfFree(v.ci); match { 864 v.si.Close() 865 s.db.putConn(ci, nil) 866 } else { 867 // TODO(bradfitz): care that we can't close 868 // this statement because the statement's 869 // connection is in use? 870 } 871 } 872 } 873 return nil 874 } 875 876 // Rows is the result of a query. Its cursor starts before the first row 877 // of the result set. Use Next to advance through the rows: 878 // 879 // rows, err := db.Query("SELECT ...") 880 // ... 881 // for rows.Next() { 882 // var id int 883 // var name string 884 // err = rows.Scan(&id, &name) 885 // ... 886 // } 887 // err = rows.Err() // get any error encountered during iteration 888 // ... 889 type Rows struct { 890 db *DB 891 ci driver.Conn // owned; must call putconn when closed to release 892 releaseConn func(error) 893 rowsi driver.Rows 894 895 closed bool 896 lastcols []driver.Value 897 lasterr error 898 closeStmt *Stmt // if non-nil, statement to Close on close 899 } 900 901 // Next prepares the next result row for reading with the Scan method. 902 // It returns true on success, false if there is no next result row. 903 // Every call to Scan, even the first one, must be preceded by a call 904 // to Next. 905 func (rs *Rows) Next() bool { 906 if rs.closed { 907 return false 908 } 909 if rs.lasterr != nil { 910 return false 911 } 912 if rs.lastcols == nil { 913 rs.lastcols = make([]driver.Value, len(rs.rowsi.Columns())) 914 } 915 rs.lasterr = rs.rowsi.Next(rs.lastcols) 916 if rs.lasterr == io.EOF { 917 rs.Close() 918 } 919 return rs.lasterr == nil 920 } 921 922 // Err returns the error, if any, that was encountered during iteration. 923 func (rs *Rows) Err() error { 924 if rs.lasterr == io.EOF { 925 return nil 926 } 927 return rs.lasterr 928 } 929 930 // Columns returns the column names. 931 // Columns returns an error if the rows are closed, or if the rows 932 // are from QueryRow and there was a deferred error. 933 func (rs *Rows) Columns() ([]string, error) { 934 if rs.closed { 935 return nil, errors.New("sql: Rows are closed") 936 } 937 if rs.rowsi == nil { 938 return nil, errors.New("sql: no Rows available") 939 } 940 return rs.rowsi.Columns(), nil 941 } 942 943 // Scan copies the columns in the current row into the values pointed 944 // at by dest. 945 // 946 // If an argument has type *[]byte, Scan saves in that argument a copy 947 // of the corresponding data. The copy is owned by the caller and can 948 // be modified and held indefinitely. The copy can be avoided by using 949 // an argument of type *RawBytes instead; see the documentation for 950 // RawBytes for restrictions on its use. 951 // 952 // If an argument has type *interface{}, Scan copies the value 953 // provided by the underlying driver without conversion. If the value 954 // is of type []byte, a copy is made and the caller owns the result. 955 func (rs *Rows) Scan(dest ...interface{}) error { 956 if rs.closed { 957 return errors.New("sql: Rows closed") 958 } 959 if rs.lasterr != nil { 960 return rs.lasterr 961 } 962 if rs.lastcols == nil { 963 return errors.New("sql: Scan called without calling Next") 964 } 965 if len(dest) != len(rs.lastcols) { 966 return fmt.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest)) 967 } 968 for i, sv := range rs.lastcols { 969 err := convertAssign(dest[i], sv) 970 if err != nil { 971 return fmt.Errorf("sql: Scan error on column index %d: %v", i, err) 972 } 973 } 974 for _, dp := range dest { 975 b, ok := dp.(*[]byte) 976 if !ok { 977 continue 978 } 979 if *b == nil { 980 // If the []byte is now nil (for a NULL value), 981 // don't fall through to below which would 982 // turn it into a non-nil 0-length byte slice 983 continue 984 } 985 if _, ok = dp.(*RawBytes); ok { 986 continue 987 } 988 clone := make([]byte, len(*b)) 989 copy(clone, *b) 990 *b = clone 991 } 992 return nil 993 } 994 995 // Close closes the Rows, preventing further enumeration. If the 996 // end is encountered, the Rows are closed automatically. Close 997 // is idempotent. 998 func (rs *Rows) Close() error { 999 if rs.closed { 1000 return nil 1001 } 1002 rs.closed = true 1003 err := rs.rowsi.Close() 1004 rs.releaseConn(err) 1005 if rs.closeStmt != nil { 1006 rs.closeStmt.Close() 1007 } 1008 return err 1009 } 1010 1011 // Row is the result of calling QueryRow to select a single row. 1012 type Row struct { 1013 // One of these two will be non-nil: 1014 err error // deferred error for easy chaining 1015 rows *Rows 1016 } 1017 1018 // Scan copies the columns from the matched row into the values 1019 // pointed at by dest. If more than one row matches the query, 1020 // Scan uses the first row and discards the rest. If no row matches 1021 // the query, Scan returns ErrNoRows. 1022 func (r *Row) Scan(dest ...interface{}) error { 1023 if r.err != nil { 1024 return r.err 1025 } 1026 1027 // TODO(bradfitz): for now we need to defensively clone all 1028 // []byte that the driver returned (not permitting 1029 // *RawBytes in Rows.Scan), since we're about to close 1030 // the Rows in our defer, when we return from this function. 1031 // the contract with the driver.Next(...) interface is that it 1032 // can return slices into read-only temporary memory that's 1033 // only valid until the next Scan/Close. But the TODO is that 1034 // for a lot of drivers, this copy will be unnecessary. We 1035 // should provide an optional interface for drivers to 1036 // implement to say, "don't worry, the []bytes that I return 1037 // from Next will not be modified again." (for instance, if 1038 // they were obtained from the network anyway) But for now we 1039 // don't care. 1040 for _, dp := range dest { 1041 if _, ok := dp.(*RawBytes); ok { 1042 return errors.New("sql: RawBytes isn't allowed on Row.Scan") 1043 } 1044 } 1045 1046 defer r.rows.Close() 1047 if !r.rows.Next() { 1048 return ErrNoRows 1049 } 1050 err := r.rows.Scan(dest...) 1051 if err != nil { 1052 return err 1053 } 1054 1055 return nil 1056 } 1057 1058 // A Result summarizes an executed SQL command. 1059 type Result interface { 1060 LastInsertId() (int64, error) 1061 RowsAffected() (int64, error) 1062 } 1063 1064 type result struct { 1065 driver.Result 1066 }