Source file src/pkg/database/sql/driver/driver.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 driver defines interfaces to be implemented by database 6 // drivers as used by package sql. 7 // 8 // Most code should use package sql. 9 package driver 10 11 import "errors" 12 13 // A driver Value is a value that drivers must be able to handle. 14 // A Value is either nil or an instance of one of these types: 15 // 16 // int64 17 // float64 18 // bool 19 // []byte 20 // string [*] everywhere except from Rows.Next. 21 // time.Time 22 type Value interface{} 23 24 // Driver is the interface that must be implemented by a database 25 // driver. 26 type Driver interface { 27 // Open returns a new connection to the database. 28 // The name is a string in a driver-specific format. 29 // 30 // Open may return a cached connection (one previously 31 // closed), but doing so is unnecessary; the sql package 32 // maintains a pool of idle connections for efficient re-use. 33 // 34 // The returned connection is only used by one goroutine at a 35 // time. 36 Open(name string) (Conn, error) 37 } 38 39 // ErrSkip may be returned by some optional interfaces' methods to 40 // indicate at runtime that the fast path is unavailable and the sql 41 // package should continue as if the optional interface was not 42 // implemented. ErrSkip is only supported where explicitly 43 // documented. 44 var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") 45 46 // ErrBadConn should be returned by a driver to signal to the sql 47 // package that a driver.Conn is in a bad state (such as the server 48 // having earlier closed the connection) and the sql package should 49 // retry on a new connection. 50 // 51 // To prevent duplicate operations, ErrBadConn should NOT be returned 52 // if there's a possibility that the database server might have 53 // performed the operation. Even if the server sends back an error, 54 // you shouldn't return ErrBadConn. 55 var ErrBadConn = errors.New("driver: bad connection") 56 57 // Execer is an optional interface that may be implemented by a Conn. 58 // 59 // If a Conn does not implement Execer, the db package's DB.Exec will 60 // first prepare a query, execute the statement, and then close the 61 // statement. 62 // 63 // Exec may return ErrSkip. 64 type Execer interface { 65 Exec(query string, args []Value) (Result, error) 66 } 67 68 // Conn is a connection to a database. It is not used concurrently 69 // by multiple goroutines. 70 // 71 // Conn is assumed to be stateful. 72 type Conn interface { 73 // Prepare returns a prepared statement, bound to this connection. 74 Prepare(query string) (Stmt, error) 75 76 // Close invalidates and potentially stops any current 77 // prepared statements and transactions, marking this 78 // connection as no longer in use. 79 // 80 // Because the sql package maintains a free pool of 81 // connections and only calls Close when there's a surplus of 82 // idle connections, it shouldn't be necessary for drivers to 83 // do their own connection caching. 84 Close() error 85 86 // Begin starts and returns a new transaction. 87 Begin() (Tx, error) 88 } 89 90 // Result is the result of a query execution. 91 type Result interface { 92 // LastInsertId returns the database's auto-generated ID 93 // after, for example, an INSERT into a table with primary 94 // key. 95 LastInsertId() (int64, error) 96 97 // RowsAffected returns the number of rows affected by the 98 // query. 99 RowsAffected() (int64, error) 100 } 101 102 // Stmt is a prepared statement. It is bound to a Conn and not 103 // used by multiple goroutines concurrently. 104 type Stmt interface { 105 // Close closes the statement. 106 // 107 // Closing a statement should not interrupt any outstanding 108 // query created from that statement. That is, the following 109 // order of operations is valid: 110 // 111 // * create a driver statement 112 // * call Query on statement, returning Rows 113 // * close the statement 114 // * read from Rows 115 // 116 // If closing a statement invalidates currently-running 117 // queries, the final step above will incorrectly fail. 118 // 119 // TODO(bradfitz): possibly remove the restriction above, if 120 // enough driver authors object and find it complicates their 121 // code too much. The sql package could be smarter about 122 // refcounting the statement and closing it at the appropriate 123 // time. 124 Close() error 125 126 // NumInput returns the number of placeholder parameters. 127 // 128 // If NumInput returns >= 0, the sql package will sanity check 129 // argument counts from callers and return errors to the caller 130 // before the statement's Exec or Query methods are called. 131 // 132 // NumInput may also return -1, if the driver doesn't know 133 // its number of placeholders. In that case, the sql package 134 // will not sanity check Exec or Query argument counts. 135 NumInput() int 136 137 // Exec executes a query that doesn't return rows, such 138 // as an INSERT or UPDATE. 139 Exec(args []Value) (Result, error) 140 141 // Exec executes a query that may return rows, such as a 142 // SELECT. 143 Query(args []Value) (Rows, error) 144 } 145 146 // ColumnConverter may be optionally implemented by Stmt if the 147 // the statement is aware of its own columns' types and can 148 // convert from any type to a driver Value. 149 type ColumnConverter interface { 150 // ColumnConverter returns a ValueConverter for the provided 151 // column index. If the type of a specific column isn't known 152 // or shouldn't be handled specially, DefaultValueConverter 153 // can be returned. 154 ColumnConverter(idx int) ValueConverter 155 } 156 157 // Rows is an iterator over an executed query's results. 158 type Rows interface { 159 // Columns returns the names of the columns. The number of 160 // columns of the result is inferred from the length of the 161 // slice. If a particular column name isn't known, an empty 162 // string should be returned for that entry. 163 Columns() []string 164 165 // Close closes the rows iterator. 166 Close() error 167 168 // Next is called to populate the next row of data into 169 // the provided slice. The provided slice will be the same 170 // size as the Columns() are wide. 171 // 172 // The dest slice may be populated only with 173 // a driver Value type, but excluding string. 174 // All string values must be converted to []byte. 175 // 176 // Next should return io.EOF when there are no more rows. 177 Next(dest []Value) error 178 } 179 180 // Tx is a transaction. 181 type Tx interface { 182 Commit() error 183 Rollback() error 184 } 185 186 // RowsAffected implements Result for an INSERT or UPDATE operation 187 // which mutates a number of rows. 188 type RowsAffected int64 189 190 var _ Result = RowsAffected(0) 191 192 func (RowsAffected) LastInsertId() (int64, error) { 193 return 0, errors.New("no LastInsertId available") 194 } 195 196 func (v RowsAffected) RowsAffected() (int64, error) { 197 return int64(v), nil 198 } 199 200 // ResultNoRows is a pre-defined Result for drivers to return when a DDL 201 // command (such as a CREATE TABLE) succeeds. It returns an error for both 202 // LastInsertId and RowsAffected. 203 var ResultNoRows noRows 204 205 type noRows struct{} 206 207 var _ Result = noRows{} 208 209 func (noRows) LastInsertId() (int64, error) { 210 return 0, errors.New("no LastInsertId available after DDL statement") 211 } 212 213 func (noRows) RowsAffected() (int64, error) { 214 return 0, errors.New("no RowsAffected available after DDL statement") 215 }