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 (
12 "context"
13 "errors"
14 "reflect"
15 )
16 17 // Value is a value that drivers must be able to handle. 18 // It is either nil, a type handled by a database driver's NamedValueChecker 19 // interface, or an instance of one of these types: 20 // 21 // int64 22 // float64 23 // bool 24 // []byte 25 // string 26 // time.Time 27 type Value interface{}
28 29 // NamedValue holds both the value name and value. 30 type NamedValue struct {
31 // If the Name is not empty it should be used for the parameter identifier and 32 // not the ordinal position. 33 // 34 // Name will not have a symbol prefix. 35 Name string
36 37 // Ordinal position of the parameter starting from one and is always set. 38 Ordinal int
39 40 // Value is the parameter value. 41 Value Value
42 }
43 44 // Driver is the interface that must be implemented by a database 45 // driver. 46 // 47 // Database drivers may implement DriverContext for access 48 // to contexts and to parse the name only once for a pool of connections, 49 // instead of once per connection. 50 type Driver interface {
51 // Open returns a new connection to the database. 52 // The name is a string in a driver-specific format. 53 // 54 // Open may return a cached connection (one previously 55 // closed), but doing so is unnecessary; the sql package 56 // maintains a pool of idle connections for efficient re-use. 57 // 58 // The returned connection is only used by one goroutine at a 59 // time. 60 Open(name string) (Conn, error)
61 }
62 63 // If a Driver implements DriverContext, then sql.DB will call 64 // OpenConnector to obtain a Connector and then invoke 65 // that Connector's Conn method to obtain each needed connection, 66 // instead of invoking the Driver's Open method for each connection. 67 // The two-step sequence allows drivers to parse the name just once 68 // and also provides access to per-Conn contexts. 69 type DriverContext interface {
70 // OpenConnector must parse the name in the same format that Driver.Open 71 // parses the name parameter. 72 OpenConnector(name string) (Connector, error)
73 }
74 75 // A Connector represents a driver in a fixed configuration 76 // and can create any number of equivalent Conns for use 77 // by multiple goroutines. 78 // 79 // A Connector can be passed to sql.OpenDB, to allow drivers 80 // to implement their own sql.DB constructors, or returned by 81 // DriverContext's OpenConnector method, to allow drivers 82 // access to context and to avoid repeated parsing of driver 83 // configuration. 84 type Connector interface {
85 // Connect returns a connection to the database. 86 // Connect may return a cached connection (one previously 87 // closed), but doing so is unnecessary; the sql package 88 // maintains a pool of idle connections for efficient re-use. 89 // 90 // The provided context.Context is for dialing purposes only 91 // (see net.DialContext) and should not be stored or used for 92 // other purposes. 93 // 94 // The returned connection is only used by one goroutine at a 95 // time. 96 Connect(context.Context) (Conn, error)
97 98 // Driver returns the underlying Driver of the Connector, 99 // mainly to maintain compatibility with the Driver method 100 // on sql.DB. 101 Driver() Driver
102 }
103 104 // ErrSkip may be returned by some optional interfaces' methods to 105 // indicate at runtime that the fast path is unavailable and the sql 106 // package should continue as if the optional interface was not 107 // implemented. ErrSkip is only supported where explicitly 108 // documented. 109 var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
110 111 // ErrBadConn should be returned by a driver to signal to the sql 112 // package that a driver.Conn is in a bad state (such as the server 113 // having earlier closed the connection) and the sql package should 114 // retry on a new connection. 115 // 116 // To prevent duplicate operations, ErrBadConn should NOT be returned 117 // if there's a possibility that the database server might have 118 // performed the operation. Even if the server sends back an error, 119 // you shouldn't return ErrBadConn. 120 var ErrBadConn = errors.New("driver: bad connection")
121 122 // Pinger is an optional interface that may be implemented by a Conn. 123 // 124 // If a Conn does not implement Pinger, the sql package's DB.Ping and 125 // DB.PingContext will check if there is at least one Conn available. 126 // 127 // If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove 128 // the Conn from pool. 129 type Pinger interface {
130 Ping(ctx context.Context) error
131 }
132 133 // Execer is an optional interface that may be implemented by a Conn. 134 // 135 // If a Conn implements neither ExecerContext nor Execer Execer, 136 // the sql package's DB.Exec will first prepare a query, execute the statement, 137 // and then close the statement. 138 // 139 // Exec may return ErrSkip. 140 // 141 // Deprecated: Drivers should implement ExecerContext instead. 142 type Execer interface {
143 Exec(query string, args []Value) (Result, error)
144 }
145 146 // ExecerContext is an optional interface that may be implemented by a Conn. 147 // 148 // If a Conn does not implement ExecerContext, the sql package's DB.Exec 149 // will fall back to Execer; if the Conn does not implement Execer either, 150 // DB.Exec will first prepare a query, execute the statement, and then 151 // close the statement. 152 // 153 // ExecerContext may return ErrSkip. 154 // 155 // ExecerContext must honor the context timeout and return when the context is canceled. 156 type ExecerContext interface {
157 ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
158 }
159 160 // Queryer is an optional interface that may be implemented by a Conn. 161 // 162 // If a Conn implements neither QueryerContext nor Queryer, 163 // the sql package's DB.Query will first prepare a query, execute the statement, 164 // and then close the statement. 165 // 166 // Query may return ErrSkip. 167 // 168 // Deprecated: Drivers should implement QueryerContext instead. 169 type Queryer interface {
170 Query(query string, args []Value) (Rows, error)
171 }
172 173 // QueryerContext is an optional interface that may be implemented by a Conn. 174 // 175 // If a Conn does not implement QueryerContext, the sql package's DB.Query 176 // will fall back to Queryer; if the Conn does not implement Queryer either, 177 // DB.Query will first prepare a query, execute the statement, and then 178 // close the statement. 179 // 180 // QueryerContext may return ErrSkip. 181 // 182 // QueryerContext must honor the context timeout and return when the context is canceled. 183 type QueryerContext interface {
184 QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
185 }
186 187 // Conn is a connection to a database. It is not used concurrently 188 // by multiple goroutines. 189 // 190 // Conn is assumed to be stateful. 191 type Conn interface {
192 // Prepare returns a prepared statement, bound to this connection. 193 Prepare(query string) (Stmt, error)
194 195 // Close invalidates and potentially stops any current 196 // prepared statements and transactions, marking this 197 // connection as no longer in use. 198 // 199 // Because the sql package maintains a free pool of 200 // connections and only calls Close when there's a surplus of 201 // idle connections, it shouldn't be necessary for drivers to 202 // do their own connection caching. 203 Close() error
204 205 // Begin starts and returns a new transaction. 206 // 207 // Deprecated: Drivers should implement ConnBeginTx instead (or additionally). 208 Begin() (Tx, error)
209 }
210 211 // ConnPrepareContext enhances the Conn interface with context. 212 type ConnPrepareContext interface {
213 // PrepareContext returns a prepared statement, bound to this connection. 214 // context is for the preparation of the statement, 215 // it must not store the context within the statement itself. 216 PrepareContext(ctx context.Context, query string) (Stmt, error)
217 }
218 219 // IsolationLevel is the transaction isolation level stored in TxOptions. 220 // 221 // This type should be considered identical to sql.IsolationLevel along 222 // with any values defined on it. 223 type IsolationLevel int
224 225 // TxOptions holds the transaction options. 226 // 227 // This type should be considered identical to sql.TxOptions. 228 type TxOptions struct {
229 Isolation IsolationLevel
230 ReadOnly bool
231 }
232 233 // ConnBeginTx enhances the Conn interface with context and TxOptions. 234 type ConnBeginTx interface {
235 // BeginTx starts and returns a new transaction. 236 // If the context is canceled by the user the sql package will 237 // call Tx.Rollback before discarding and closing the connection. 238 // 239 // This must check opts.Isolation to determine if there is a set 240 // isolation level. If the driver does not support a non-default 241 // level and one is set or if there is a non-default isolation level 242 // that is not supported, an error must be returned. 243 // 244 // This must also check opts.ReadOnly to determine if the read-only 245 // value is true to either set the read-only transaction property if supported 246 // or return an error if it is not supported. 247 BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
248 }
249 250 // SessionResetter may be implemented by Conn to allow drivers to reset the 251 // session state associated with the connection and to signal a bad connection. 252 type SessionResetter interface {
253 // ResetSession is called while a connection is in the connection 254 // pool. No queries will run on this connection until this method returns. 255 // 256 // If the connection is bad this should return driver.ErrBadConn to prevent 257 // the connection from being returned to the connection pool. Any other 258 // error will be discarded. 259 ResetSession(ctx context.Context) error
260 }
261 262 // Result is the result of a query execution. 263 type Result interface {
264 // LastInsertId returns the database's auto-generated ID 265 // after, for example, an INSERT into a table with primary 266 // key. 267 LastInsertId() (int64, error)
268 269 // RowsAffected returns the number of rows affected by the 270 // query. 271 RowsAffected() (int64, error)
272 }
273 274 // Stmt is a prepared statement. It is bound to a Conn and not 275 // used by multiple goroutines concurrently. 276 type Stmt interface {
277 // Close closes the statement. 278 // 279 // As of Go 1.1, a Stmt will not be closed if it's in use 280 // by any queries. 281 Close() error
282 283 // NumInput returns the number of placeholder parameters. 284 // 285 // If NumInput returns >= 0, the sql package will sanity check 286 // argument counts from callers and return errors to the caller 287 // before the statement's Exec or Query methods are called. 288 // 289 // NumInput may also return -1, if the driver doesn't know 290 // its number of placeholders. In that case, the sql package 291 // will not sanity check Exec or Query argument counts. 292 NumInput() int
293 294 // Exec executes a query that doesn't return rows, such 295 // as an INSERT or UPDATE. 296 // 297 // Deprecated: Drivers should implement StmtExecContext instead (or additionally). 298 Exec(args []Value) (Result, error)
299 300 // Query executes a query that may return rows, such as a 301 // SELECT. 302 // 303 // Deprecated: Drivers should implement StmtQueryContext instead (or additionally). 304 Query(args []Value) (Rows, error)
305 }
306 307 // StmtExecContext enhances the Stmt interface by providing Exec with context. 308 type StmtExecContext interface {
309 // ExecContext executes a query that doesn't return rows, such 310 // as an INSERT or UPDATE. 311 // 312 // ExecContext must honor the context timeout and return when it is canceled. 313 ExecContext(ctx context.Context, args []NamedValue) (Result, error)
314 }
315 316 // StmtQueryContext enhances the Stmt interface by providing Query with context. 317 type StmtQueryContext interface {
318 // QueryContext executes a query that may return rows, such as a 319 // SELECT. 320 // 321 // QueryContext must honor the context timeout and return when it is canceled. 322 QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
323 }
324 325 // ErrRemoveArgument may be returned from NamedValueChecker to instruct the 326 // sql package to not pass the argument to the driver query interface. 327 // Return when accepting query specific options or structures that aren't 328 // SQL query arguments. 329 var ErrRemoveArgument = errors.New("driver: remove argument from query")
330 331 // NamedValueChecker may be optionally implemented by Conn or Stmt. It provides 332 // the driver more control to handle Go and database types beyond the default 333 // Values types allowed. 334 // 335 // The sql package checks for value checkers in the following order, 336 // stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker, 337 // Stmt.ColumnConverter, DefaultParameterConverter. 338 // 339 // If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in 340 // the final query arguments. This may be used to pass special options to 341 // the query itself. 342 // 343 // If ErrSkip is returned the column converter error checking 344 // path is used for the argument. Drivers may wish to return ErrSkip after 345 // they have exhausted their own special cases. 346 type NamedValueChecker interface {
347 // CheckNamedValue is called before passing arguments to the driver 348 // and is called in place of any ColumnConverter. CheckNamedValue must do type 349 // validation and conversion as appropriate for the driver. 350 CheckNamedValue(*NamedValue) error
351 }
352 353 // ColumnConverter may be optionally implemented by Stmt if the 354 // statement is aware of its own columns' types and can convert from 355 // any type to a driver Value. 356 // 357 // Deprecated: Drivers should implement NamedValueChecker. 358 type ColumnConverter interface {
359 // ColumnConverter returns a ValueConverter for the provided 360 // column index. If the type of a specific column isn't known 361 // or shouldn't be handled specially, DefaultValueConverter 362 // can be returned. 363 ColumnConverter(idx int) ValueConverter
364 }
365 366 // Rows is an iterator over an executed query's results. 367 type Rows interface {
368 // Columns returns the names of the columns. The number of 369 // columns of the result is inferred from the length of the 370 // slice. If a particular column name isn't known, an empty 371 // string should be returned for that entry. 372 Columns() []string
373 374 // Close closes the rows iterator. 375 Close() error
376 377 // Next is called to populate the next row of data into 378 // the provided slice. The provided slice will be the same 379 // size as the Columns() are wide. 380 // 381 // Next should return io.EOF when there are no more rows. 382 // 383 // The dest should not be written to outside of Next. Care 384 // should be taken when closing Rows not to modify 385 // a buffer held in dest. 386 Next(dest []Value) error
387 }
388 389 // RowsNextResultSet extends the Rows interface by providing a way to signal 390 // the driver to advance to the next result set. 391 type RowsNextResultSet interface {
392 Rows
393 394 // HasNextResultSet is called at the end of the current result set and 395 // reports whether there is another result set after the current one. 396 HasNextResultSet() bool
397 398 // NextResultSet advances the driver to the next result set even 399 // if there are remaining rows in the current result set. 400 // 401 // NextResultSet should return io.EOF when there are no more result sets. 402 NextResultSet() error
403 }
404 405 // RowsColumnTypeScanType may be implemented by Rows. It should return 406 // the value type that can be used to scan types into. For example, the database 407 // column type "bigint" this should return "reflect.TypeOf(int64(0))". 408 type RowsColumnTypeScanType interface {
409 Rows
410 ColumnTypeScanType(index int) reflect.Type
411 } 412 413 // RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the 414 // database system type name without the length. Type names should be uppercase. 415 // Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", 416 // "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", 417 // "TIMESTAMP". 418 type RowsColumnTypeDatabaseTypeName interface {
419 Rows
420 ColumnTypeDatabaseTypeName(index int) string
421 }
422 423 // RowsColumnTypeLength may be implemented by Rows. It should return the length 424 // of the column type if the column is a variable length type. If the column is 425 // not a variable length type ok should return false. 426 // If length is not limited other than system limits, it should return math.MaxInt64. 427 // The following are examples of returned values for various types: 428 // TEXT (math.MaxInt64, true) 429 // varchar(10) (10, true) 430 // nvarchar(10) (10, true) 431 // decimal (0, false) 432 // int (0, false) 433 // bytea(30) (30, true) 434 type RowsColumnTypeLength interface {
435 Rows
436 ColumnTypeLength(index int) (length int64, ok bool)
437 }
438 439 // RowsColumnTypeNullable may be implemented by Rows. The nullable value should 440 // be true if it is known the column may be null, or false if the column is known 441 // to be not nullable. 442 // If the column nullability is unknown, ok should be false. 443 type RowsColumnTypeNullable interface {
444 Rows
445 ColumnTypeNullable(index int) (nullable, ok bool)
446 }
447 448 // RowsColumnTypePrecisionScale may be implemented by Rows. It should return 449 // the precision and scale for decimal types. If not applicable, ok should be false. 450 // The following are examples of returned values for various types: 451 // decimal(38, 4) (38, 4, true) 452 // int (0, 0, false) 453 // decimal (math.MaxInt64, math.MaxInt64, true) 454 type RowsColumnTypePrecisionScale interface {
455 Rows
456 ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
457 }
458 459 // Tx is a transaction. 460 type Tx interface {
461 Commit() error
462 Rollback() error
463 }
464 465 // RowsAffected implements Result for an INSERT or UPDATE operation 466 // which mutates a number of rows. 467 type RowsAffected int64
468 469 var _ Result = RowsAffected(0)
470 471 func (RowsAffected) LastInsertId() (int64, error) {
472 return 0, errors.New("no LastInsertId available")
473 }
474 475 func (v RowsAffected) RowsAffected() (int64, error) {
476 return int64(v), nil
477 }
478 479 // ResultNoRows is a pre-defined Result for drivers to return when a DDL 480 // command (such as a CREATE TABLE) succeeds. It returns an error for both 481 // LastInsertId and RowsAffected. 482 var ResultNoRows noRows
483 484 type noRows struct{}
485 486 var _ Result = noRows{}
487 488 func (noRows) LastInsertId() (int64, error) {
489 return 0, errors.New("no LastInsertId available after DDL statement")
490 }
491 492 func (noRows) RowsAffected() (int64, error) {
493 return 0, errors.New("no RowsAffected available after DDL statement")
494 }
495