libgo/go/exp/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         "errors"
  11         "fmt"
  12         "io"
  13         "sync"
  14
  15         "exp/sql/driver"
  16 )
  17
  18 var drivers = make(map[string]driver.Driver)
  19
  20 // Register makes a database driver available by the provided name.
  21 // If Register is called twice with the same name or if driver is nil,
  22 // it panics.
  23 func Register(name string, driver driver.Driver) {
  24         if driver == nil {
  25                 panic("db: Register driver is nil")
  26         }
  27         if _, dup := drivers[name]; dup {
  28                 panic("db: Register called twice for driver " + name)
  29         }
  30         drivers[name] = driver
  31 }
  32
  33 // NullableString represents a string that may be null.
  34 // NullableString implements the ScannerInto interface so
  35 // it can be used as a scan destination:
  36 //
  37 //  var s NullableString
  38 //  err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
  39 //  ...
  40 //  if s.Valid {
  41 //     // use s.String
  42 //  } else {
  43 //     // NULL value
  44 //  }
  45 //
  46 // TODO(bradfitz): add other types.
  47 type NullableString struct {
  48         String string
  49         Valid  bool // Valid is true if String is not NULL
  50 }
  51
  52 // ScanInto implements the ScannerInto interface.
  53 func (ms *NullableString) ScanInto(value interface{}) error {
  54         if value == nil {
  55                 ms.String, ms.Valid = "", false
  56                 return nil
  57         }
  58         ms.Valid = true
  59         return convertAssign(&ms.String, value)
  60 }
  61
  62 // ScannerInto is an interface used by Scan.
  63 type ScannerInto interface {
  64         // ScanInto assigns a value from a database driver.
  65         //
  66         // The value will be of one of the following restricted
  67         // set of types:
  68         //
  69         //    int64
  70         //    float64
  71         //    bool
  72         //    []byte
  73         //    nil - for NULL values
  74         //
  75         // An error should be returned if the value can not be stored
  76         // without loss of information.
  77         ScanInto(value interface{}) error
  78 }
  79
  80 // ErrNoRows is returned by Scan when QueryRow doesn't return a
  81 // row. In such a case, QueryRow returns a placeholder *Row value that
  82 // defers this error until a Scan.
  83 var ErrNoRows = errors.New("db: no rows in result set")
  84
  85 // DB is a database handle. It's safe for concurrent use by multiple
  86 // goroutines.
  87 type DB struct {
  88         driver driver.Driver
  89         dsn    string
  90
  91         mu       sync.Mutex // protects freeConn and closed
  92         freeConn []driver.Conn
  93         closed   bool
  94 }
  95
  96 // Open opens a database specified by its database driver name and a
  97 // driver-specific data source name, usually consisting of at least a
  98 // database name and connection information.
  99 //
 100 // Most users will open a database via a driver-specific connection
 101 // helper function that returns a *DB.
 102 func Open(driverName, dataSourceName string) (*DB, error) {
 103         driver, ok := drivers[driverName]
 104         if !ok {
 105                 return nil, fmt.Errorf("db: unknown driver %q (forgotten import?)", driverName)
 106         }
 107         return &DB{driver: driver, dsn: dataSourceName}, nil
 108 }
 109
 110 // Close closes the database, releasing any open resources.
 111 func (db *DB) Close() error {
 112         db.mu.Lock()
 113         defer db.mu.Unlock()
 114         var err error
 115         for _, c := range db.freeConn {
 116                 err1 := c.Close()
 117                 if err1 != nil {
 118                         err = err1
 119                 }
 120         }
 121         db.freeConn = nil
 122         db.closed = true
 123         return err
 124 }
 125
 126 func (db *DB) maxIdleConns() int {
 127         const defaultMaxIdleConns = 2
 128         // TODO(bradfitz): ask driver, if supported, for its default preference
 129         // TODO(bradfitz): let users override?
 130         return defaultMaxIdleConns
 131 }
 132
 133 // conn returns a newly-opened or cached driver.Conn
 134 func (db *DB) conn() (driver.Conn, error) {
 135         db.mu.Lock()
 136         if db.closed {
 137                 db.mu.Unlock()
 138                 return nil, errors.New("sql: database is closed")
 139         }
 140         if n := len(db.freeConn); n > 0 {
 141                 conn := db.freeConn[n-1]
 142                 db.freeConn = db.freeConn[:n-1]
 143                 db.mu.Unlock()
 144                 return conn, nil
 145         }
 146         db.mu.Unlock()
 147         return db.driver.Open(db.dsn)
 148 }
 149
 150 func (db *DB) connIfFree(wanted driver.Conn) (conn driver.Conn, ok bool) {
 151         db.mu.Lock()
 152         defer db.mu.Unlock()
 153         for n, conn := range db.freeConn {
 154                 if conn == wanted {
 155                         db.freeConn[n] = db.freeConn[len(db.freeConn)-1]
 156                         db.freeConn = db.freeConn[:len(db.freeConn)-1]
 157                         return wanted, true
 158                 }
 159         }
 160         return nil, false
 161 }
 162
 163 func (db *DB) putConn(c driver.Conn) {
 164         db.mu.Lock()
 165         defer db.mu.Unlock()
 166         if n := len(db.freeConn); !db.closed && n < db.maxIdleConns() {
 167                 db.freeConn = append(db.freeConn, c)
 168                 return
 169         }
 170         db.closeConn(c) // TODO(bradfitz): release lock before calling this?
 171 }
 172
 173 func (db *DB) closeConn(c driver.Conn) {
 174         // TODO: check to see if we need this Conn for any prepared statements
 175         // that are active.
 176         c.Close()
 177 }
 178
 179 // Prepare creates a prepared statement for later execution.
 180 func (db *DB) Prepare(query string) (*Stmt, error) {
 181         // TODO: check if db.driver supports an optional
 182         // driver.Preparer interface and call that instead, if so,
 183         // otherwise we make a prepared statement that's bound
 184         // to a connection, and to execute this prepared statement
 185         // we either need to use this connection (if it's free), else
 186         // get a new connection + re-prepare + execute on that one.
 187         ci, err := db.conn()
 188         if err != nil {
 189                 return nil, err
 190         }
 191         defer db.putConn(ci)
 192         si, err := ci.Prepare(query)
 193         if err != nil {
 194                 return nil, err
 195         }
 196         stmt := &Stmt{
 197                 db:    db,
 198                 query: query,
 199                 css:   []connStmt{{ci, si}},
 200         }
 201         return stmt, nil
 202 }
 203
 204 // Exec executes a query without returning any rows.
 205 func (db *DB) Exec(query string, args ...interface{}) (Result, error) {
 206         sargs, err := subsetTypeArgs(args)
 207         if err != nil {
 208                 return nil, err
 209         }
 210
 211         ci, err := db.conn()
 212         if err != nil {
 213                 return nil, err
 214         }
 215         defer db.putConn(ci)
 216
 217         if execer, ok := ci.(driver.Execer); ok {
 218                 resi, err := execer.Exec(query, sargs)
 219                 if err != driver.ErrSkip {
 220                         if err != nil {
 221                                 return nil, err
 222                         }
 223                         return result{resi}, nil
 224                 }
 225         }
 226
 227         sti, err := ci.Prepare(query)
 228         if err != nil {
 229                 return nil, err
 230         }
 231         defer sti.Close()
 232
 233         resi, err := sti.Exec(sargs)
 234         if err != nil {
 235                 return nil, err
 236         }
 237         return result{resi}, nil
 238 }
 239
 240 // Query executes a query that returns rows, typically a SELECT.
 241 func (db *DB) Query(query string, args ...interface{}) (*Rows, error) {
 242         stmt, err := db.Prepare(query)
 243         if err != nil {
 244                 return nil, err
 245         }
 246         defer stmt.Close()
 247         return stmt.Query(args...)
 248 }
 249
 250 // QueryRow executes a query that is expected to return at most one row.
 251 // QueryRow always return a non-nil value. Errors are deferred until
 252 // Row's Scan method is called.
 253 func (db *DB) QueryRow(query string, args ...interface{}) *Row {
 254         rows, err := db.Query(query, args...)
 255         return &Row{rows: rows, err: err}
 256 }
 257
 258 // Begin starts a transaction. The isolation level is dependent on
 259 // the driver.
 260 func (db *DB) Begin() (*Tx, error) {
 261         ci, err := db.conn()
 262         if err != nil {
 263                 return nil, err
 264         }
 265         txi, err := ci.Begin()
 266         if err != nil {
 267                 db.putConn(ci)
 268                 return nil, fmt.Errorf("sql: failed to Begin transaction: %v", err)
 269         }
 270         return &Tx{
 271                 db:  db,
 272                 ci:  ci,
 273                 txi: txi,
 274         }, nil
 275 }
 276
 277 // DriverDatabase returns the database's underlying driver.
 278 func (db *DB) Driver() driver.Driver {
 279         return db.driver
 280 }
 281
 282 // Tx is an in-progress database transaction.
 283 //
 284 // A transaction must end with a call to Commit or Rollback.
 285 //
 286 // After a call to Commit or Rollback, all operations on the
 287 // transaction fail with ErrTransactionFinished.
 288 type Tx struct {
 289         db *DB
 290
 291         // ci is owned exclusively until Commit or Rollback, at which point
 292         // it's returned with putConn.
 293         ci  driver.Conn
 294         txi driver.Tx
 295
 296         // cimu is held while somebody is using ci (between grabConn
 297         // and releaseConn)
 298         cimu sync.Mutex
 299
 300         // done transitions from false to true exactly once, on Commit
 301         // or Rollback. once done, all operations fail with
 302         // ErrTransactionFinished.
 303         done bool
 304 }
 305
 306 var ErrTransactionFinished = errors.New("sql: Transaction has already been committed or rolled back")
 307
 308 func (tx *Tx) close() {
 309         if tx.done {
 310                 panic("double close") // internal error
 311         }
 312         tx.done = true
 313         tx.db.putConn(tx.ci)
 314         tx.ci = nil
 315         tx.txi = nil
 316 }
 317
 318 func (tx *Tx) grabConn() (driver.Conn, error) {
 319         if tx.done {
 320                 return nil, ErrTransactionFinished
 321         }
 322         tx.cimu.Lock()
 323         return tx.ci, nil
 324 }
 325
 326 func (tx *Tx) releaseConn() {
 327         tx.cimu.Unlock()
 328 }
 329
 330 // Commit commits the transaction.
 331 func (tx *Tx) Commit() error {
 332         if tx.done {
 333                 return ErrTransactionFinished
 334         }
 335         defer tx.close()
 336         return tx.txi.Commit()
 337 }
 338
 339 // Rollback aborts the transaction.
 340 func (tx *Tx) Rollback() error {
 341         if tx.done {
 342                 return ErrTransactionFinished
 343         }
 344         defer tx.close()
 345         return tx.txi.Rollback()
 346 }
 347
 348 // Prepare creates a prepared statement for use within a transaction.
 349 //
 350 // The returned statement operates within the transaction and can no longer
 351 // be used once the transaction has been committed or rolled back.
 352 //
 353 // To use an existing prepared statement on this transaction, see Tx.Stmt.
 354 func (tx *Tx) Prepare(query string) (*Stmt, error) {
 355         // TODO(bradfitz): We could be more efficient here and either
 356         // provide a method to take an existing Stmt (created on
 357         // perhaps a different Conn), and re-create it on this Conn if
 358         // necessary. Or, better: keep a map in DB of query string to
 359         // Stmts, and have Stmt.Execute do the right thing and
 360         // re-prepare if the Conn in use doesn't have that prepared
 361         // statement.  But we'll want to avoid caching the statement
 362         // in the case where we only call conn.Prepare implicitly
 363         // (such as in db.Exec or tx.Exec), but the caller package
 364         // can't be holding a reference to the returned statement.
 365         // Perhaps just looking at the reference count (by noting
 366         // Stmt.Close) would be enough. We might also want a finalizer
 367         // on Stmt to drop the reference count.
 368         ci, err := tx.grabConn()
 369         if err != nil {
 370                 return nil, err
 371         }
 372         defer tx.releaseConn()
 373
 374         si, err := ci.Prepare(query)
 375         if err != nil {
 376                 return nil, err
 377         }
 378
 379         stmt := &Stmt{
 380                 db:    tx.db,
 381                 tx:    tx,
 382                 txsi:  si,
 383                 query: query,
 384         }
 385         return stmt, nil
 386 }
 387
 388 // Stmt returns a transaction-specific prepared statement from
 389 // an existing statement.
 390 //
 391 // Example:
 392 //  updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
 393 //  ...
 394 //  tx, err := db.Begin()
 395 //  ...
 396 //  res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
 397 func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
 398         // TODO(bradfitz): optimize this. Currently this re-prepares
 399         // each time.  This is fine for now to illustrate the API but
 400         // we should really cache already-prepared statements
 401         // per-Conn. See also the big comment in Tx.Prepare.
 402
 403         if tx.db != stmt.db {
 404                 return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")}
 405         }
 406         ci, err := tx.grabConn()
 407         if err != nil {
 408                 return &Stmt{stickyErr: err}
 409         }
 410         defer tx.releaseConn()
 411         si, err := ci.Prepare(stmt.query)
 412         return &Stmt{
 413                 db:        tx.db,
 414                 tx:        tx,
 415                 txsi:      si,
 416                 query:     stmt.query,
 417                 stickyErr: err,
 418         }
 419 }
 420
 421 // Exec executes a query that doesn't return rows.
 422 // For example: an INSERT and UPDATE.
 423 func (tx *Tx) Exec(query string, args ...interface{}) (Result, error) {
 424         ci, err := tx.grabConn()
 425         if err != nil {
 426                 return nil, err
 427         }
 428         defer tx.releaseConn()
 429
 430         if execer, ok := ci.(driver.Execer); ok {
 431                 resi, err := execer.Exec(query, args)
 432                 if err != nil {
 433                         return nil, err
 434                 }
 435                 return result{resi}, nil
 436         }
 437
 438         sti, err := ci.Prepare(query)
 439         if err != nil {
 440                 return nil, err
 441         }
 442         defer sti.Close()
 443
 444         sargs, err := subsetTypeArgs(args)
 445         if err != nil {
 446                 return nil, err
 447         }
 448
 449         resi, err := sti.Exec(sargs)
 450         if err != nil {
 451                 return nil, err
 452         }
 453         return result{resi}, nil
 454 }
 455
 456 // Query executes a query that returns rows, typically a SELECT.
 457 func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) {
 458         if tx.done {
 459                 return nil, ErrTransactionFinished
 460         }
 461         stmt, err := tx.Prepare(query)
 462         if err != nil {
 463                 return nil, err
 464         }
 465         defer stmt.Close()
 466         return stmt.Query(args...)
 467 }
 468
 469 // QueryRow executes a query that is expected to return at most one row.
 470 // QueryRow always return a non-nil value. Errors are deferred until
 471 // Row's Scan method is called.
 472 func (tx *Tx) QueryRow(query string, args ...interface{}) *Row {
 473         rows, err := tx.Query(query, args...)
 474         return &Row{rows: rows, err: err}
 475 }
 476
 477 // connStmt is a prepared statement on a particular connection.
 478 type connStmt struct {
 479         ci driver.Conn
 480         si driver.Stmt
 481 }
 482
 483 // Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
 484 type Stmt struct {
 485         // Immutable:
 486         db        *DB    // where we came from
 487         query     string // that created the Stmt
 488         stickyErr error  // if non-nil, this error is returned for all operations
 489
 490         // If in a transaction, else both nil:
 491         tx   *Tx
 492         txsi driver.Stmt
 493
 494         mu     sync.Mutex // protects the rest of the fields
 495         closed bool
 496
 497         // css is a list of underlying driver statement interfaces
 498         // that are valid on particular connections.  This is only
 499         // used if tx == nil and one is found that has idle
 500         // connections.  If tx != nil, txsi is always used.
 501         css []connStmt
 502 }
 503
 504 // Exec executes a prepared statement with the given arguments and
 505 // returns a Result summarizing the effect of the statement.
 506 func (s *Stmt) Exec(args ...interface{}) (Result, error) {
 507         _, releaseConn, si, err := s.connStmt()
 508         if err != nil {
 509                 return nil, err
 510         }
 511         defer releaseConn()
 512
 513         // -1 means the driver doesn't know how to count the number of
 514         // placeholders, so we won't sanity check input here and instead let the
 515         // driver deal with errors.
 516         if want := si.NumInput(); want != -1 && len(args) != want {
 517                 return nil, fmt.Errorf("db: expected %d arguments, got %d", want, len(args))
 518         }
 519
 520         // Convert args to subset types.
 521         if cc, ok := si.(driver.ColumnConverter); ok {
 522                 for n, arg := range args {
 523                         args[n], err = cc.ColumnConverter(n).ConvertValue(arg)
 524                         if err != nil {
 525                                 return nil, fmt.Errorf("db: converting Exec argument #%d's type: %v", n, err)
 526                         }
 527                         if !driver.IsParameterSubsetType(args[n]) {
 528                                 return nil, fmt.Errorf("db: driver ColumnConverter error converted %T to unsupported type %T",
 529                                         arg, args[n])
 530                         }
 531                 }
 532         } else {
 533                 for n, arg := range args {
 534                         args[n], err = driver.DefaultParameterConverter.ConvertValue(arg)
 535                         if err != nil {
 536                                 return nil, fmt.Errorf("db: converting Exec argument #%d's type: %v", n, err)
 537                         }
 538                 }
 539         }
 540
 541         resi, err := si.Exec(args)
 542         if err != nil {
 543                 return nil, err
 544         }
 545         return result{resi}, nil
 546 }
 547
 548 // connStmt returns a free driver connection on which to execute the
 549 // statement, a function to call to release the connection, and a
 550 // statement bound to that connection.
 551 func (s *Stmt) connStmt() (ci driver.Conn, releaseConn func(), si driver.Stmt, err error) {
 552         if s.stickyErr != nil {
 553                 return nil, nil, nil, s.stickyErr
 554         }
 555         s.mu.Lock()
 556         if s.closed {
 557                 s.mu.Unlock()
 558                 err = errors.New("db: statement is closed")
 559                 return
 560         }
 561
 562         // In a transaction, we always use the connection that the
 563         // transaction was created on.
 564         if s.tx != nil {
 565                 s.mu.Unlock()
 566                 ci, err = s.tx.grabConn() // blocks, waiting for the connection.
 567                 if err != nil {
 568                         return
 569                 }
 570                 releaseConn = func() { s.tx.releaseConn() }
 571                 return ci, releaseConn, s.txsi, nil
 572         }
 573
 574         var cs connStmt
 575         match := false
 576         for _, v := range s.css {
 577                 // TODO(bradfitz): lazily clean up entries in this
 578                 // list with dead conns while enumerating
 579                 if _, match = s.db.connIfFree(cs.ci); match {
 580                         cs = v
 581                         break
 582                 }
 583         }
 584         s.mu.Unlock()
 585
 586         // Make a new conn if all are busy.
 587         // TODO(bradfitz): or wait for one? make configurable later?
 588         if !match {
 589                 ci, err := s.db.conn()
 590                 if err != nil {
 591                         return nil, nil, nil, err
 592                 }
 593                 si, err := ci.Prepare(s.query)
 594                 if err != nil {
 595                         return nil, nil, nil, err
 596                 }
 597                 s.mu.Lock()
 598                 cs = connStmt{ci, si}
 599                 s.css = append(s.css, cs)
 600                 s.mu.Unlock()
 601         }
 602
 603         conn := cs.ci
 604         releaseConn = func() { s.db.putConn(conn) }
 605         return conn, releaseConn, cs.si, nil
 606 }
 607
 608 // Query executes a prepared query statement with the given arguments
 609 // and returns the query results as a *Rows.
 610 func (s *Stmt) Query(args ...interface{}) (*Rows, error) {
 611         ci, releaseConn, si, err := s.connStmt()
 612         if err != nil {
 613                 return nil, err
 614         }
 615
 616         // -1 means the driver doesn't know how to count the number of
 617         // placeholders, so we won't sanity check input here and instead let the
 618         // driver deal with errors.
 619         if want := si.NumInput(); want != -1 && len(args) != want {
 620                 return nil, fmt.Errorf("db: statement expects %d inputs; got %d", si.NumInput(), len(args))
 621         }
 622         sargs, err := subsetTypeArgs(args)
 623         if err != nil {
 624                 return nil, err
 625         }
 626         rowsi, err := si.Query(sargs)
 627         if err != nil {
 628                 s.db.putConn(ci)
 629                 return nil, err
 630         }
 631         // Note: ownership of ci passes to the *Rows, to be freed
 632         // with releaseConn.
 633         rows := &Rows{
 634                 db:          s.db,
 635                 ci:          ci,
 636                 releaseConn: releaseConn,
 637                 rowsi:       rowsi,
 638         }
 639         return rows, nil
 640 }
 641
 642 // QueryRow executes a prepared query statement with the given arguments.
 643 // If an error occurs during the execution of the statement, that error will
 644 // be returned by a call to Scan on the returned *Row, which is always non-nil.
 645 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
 646 // Otherwise, the *Row's Scan scans the first selected row and discards
 647 // the rest.
 648 //
 649 // Example usage:
 650 //
 651 //  var name string
 652 //  err := nameByUseridStmt.QueryRow(id).Scan(&s)
 653 func (s *Stmt) QueryRow(args ...interface{}) *Row {
 654         rows, err := s.Query(args...)
 655         if err != nil {
 656                 return &Row{err: err}
 657         }
 658         return &Row{rows: rows}
 659 }
 660
 661 // Close closes the statement.
 662 func (s *Stmt) Close() error {
 663         if s.stickyErr != nil {
 664                 return s.stickyErr
 665         }
 666         s.mu.Lock()
 667         defer s.mu.Unlock()
 668         if s.closed {
 669                 return nil
 670         }
 671         s.closed = true
 672
 673         if s.tx != nil {
 674                 s.txsi.Close()
 675         } else {
 676                 for _, v := range s.css {
 677                         if ci, match := s.db.connIfFree(v.ci); match {
 678                                 v.si.Close()
 679                                 s.db.putConn(ci)
 680                         } else {
 681                                 // TODO(bradfitz): care that we can't close
 682                                 // this statement because the statement's
 683                                 // connection is in use?
 684                         }
 685                 }
 686         }
 687         return nil
 688 }
 689
 690 // Rows is the result of a query. Its cursor starts before the first row
 691 // of the result set. Use Next to advance through the rows:
 692 //
 693 //     rows, err := db.Query("SELECT ...")
 694 //     ...
 695 //     for rows.Next() {
 696 //         var id int
 697 //         var name string
 698 //         err = rows.Scan(&id, &name)
 699 //         ...
 700 //     }
 701 //     err = rows.Err() // get any error encountered during iteration
 702 //     ...
 703 type Rows struct {
 704         db          *DB
 705         ci          driver.Conn // owned; must call putconn when closed to release
 706         releaseConn func()
 707         rowsi       driver.Rows
 708
 709         closed   bool
 710         lastcols []interface{}
 711         lasterr  error
 712 }
 713
 714 // Next prepares the next result row for reading with the Scan method.
 715 // It returns true on success, false if there is no next result row.
 716 // Every call to Scan, even the first one, must be preceded by a call
 717 // to Next.
 718 func (rs *Rows) Next() bool {
 719         if rs.closed {
 720                 return false
 721         }
 722         if rs.lasterr != nil {
 723                 return false
 724         }
 725         if rs.lastcols == nil {
 726                 rs.lastcols = make([]interface{}, len(rs.rowsi.Columns()))
 727         }
 728         rs.lasterr = rs.rowsi.Next(rs.lastcols)
 729         return rs.lasterr == nil
 730 }
 731
 732 // Err returns the error, if any, that was encountered during iteration.
 733 func (rs *Rows) Err() error {
 734         if rs.lasterr == io.EOF {
 735                 return nil
 736         }
 737         return rs.lasterr
 738 }
 739
 740 // Scan copies the columns in the current row into the values pointed
 741 // at by dest. If dest contains pointers to []byte, the slices should
 742 // not be modified and should only be considered valid until the next
 743 // call to Next or Scan.
 744 func (rs *Rows) Scan(dest ...interface{}) error {
 745         if rs.closed {
 746                 return errors.New("db: Rows closed")
 747         }
 748         if rs.lasterr != nil {
 749                 return rs.lasterr
 750         }
 751         if rs.lastcols == nil {
 752                 return errors.New("db: Scan called without calling Next")
 753         }
 754         if len(dest) != len(rs.lastcols) {
 755                 return fmt.Errorf("db: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest))
 756         }
 757         for i, sv := range rs.lastcols {
 758                 err := convertAssign(dest[i], sv)
 759                 if err != nil {
 760                         return fmt.Errorf("db: Scan error on column index %d: %v", i, err)
 761                 }
 762         }
 763         return nil
 764 }
 765
 766 // Close closes the Rows, preventing further enumeration. If the
 767 // end is encountered, the Rows are closed automatically. Close
 768 // is idempotent.
 769 func (rs *Rows) Close() error {
 770         if rs.closed {
 771                 return nil
 772         }
 773         rs.closed = true
 774         err := rs.rowsi.Close()
 775         rs.releaseConn()
 776         return err
 777 }
 778
 779 // Row is the result of calling QueryRow to select a single row.
 780 type Row struct {
 781         // One of these two will be non-nil:
 782         err  error // deferred error for easy chaining
 783         rows *Rows
 784 }
 785
 786 // Scan copies the columns from the matched row into the values
 787 // pointed at by dest.  If more than one row matches the query,
 788 // Scan uses the first row and discards the rest.  If no row matches
 789 // the query, Scan returns ErrNoRows.
 790 //
 791 // If dest contains pointers to []byte, the slices should not be
 792 // modified and should only be considered valid until the next call to
 793 // Next or Scan.
 794 func (r *Row) Scan(dest ...interface{}) error {
 795         if r.err != nil {
 796                 return r.err
 797         }
 798         defer r.rows.Close()
 799         if !r.rows.Next() {
 800                 return ErrNoRows
 801         }
 802         return r.rows.Scan(dest...)
 803 }
 804
 805 // A Result summarizes an executed SQL command.
 806 type Result interface {
 807         LastInsertId() (int64, error)
 808         RowsAffected() (int64, error)
 809 }
 810
 811 type result struct {
 812         driver.Result
 813 }