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